Skip to main content

whisker_engine/
measurement.rs

1//! Retained intrinsic-measurement coordination for one surface.
2
3use std::{
4    collections::{BTreeMap, BTreeSet, HashMap},
5    error::Error,
6    fmt,
7};
8
9use whisker_layout::{
10    IntrinsicMeasurer, IntrinsicResult, LayoutSize, MeasureRequest as LayoutMeasureRequest,
11    MeasuredInlineChild, MeasurementState,
12};
13use whisker_protocol::{
14    AvailableSpace, ElementTypeId, MeasureConstraints, MeasuredSize, MeasurementKey,
15    MeasurementKind, MeasurementMetrics, MeasurementPayload, MeasurementPayloadError,
16    MeasurementReady, MeasurementRequest, MeasurementRequestId, MeasurementResponse,
17    MeasurementSpec, NodeId, PendingMeasurePolicy, UnsupportedMeasurementReason,
18};
19
20use crate::LayoutUpdate;
21
22/// State reached by one Host-backed layout attempt.
23#[derive(Clone, Debug, PartialEq)]
24pub enum LayoutProgress {
25    /// Every intrinsic measurement was final and geometry can be presented.
26    Complete(LayoutUpdate),
27    /// Geometry used an explicit provisional policy and may be presented.
28    Provisional {
29        /// Geometry projected into the retained scene.
30        update: LayoutUpdate,
31        /// Cache-missing requests that should be sent in one Host batch.
32        requests: Vec<MeasurementRequest>,
33        /// Number of deferred Host requests still awaiting completion.
34        pending: usize,
35    },
36    /// Geometry was withheld because at least one measurement had no fallback.
37    Blocked {
38        /// Cache-missing requests that should be sent in one Host batch.
39        requests: Vec<MeasurementRequest>,
40        /// Number of deferred Host requests still awaiting completion.
41        pending: usize,
42    },
43}
44
45impl LayoutProgress {
46    /// Returns requests that must be passed to `RendererV1::measure_batch`.
47    pub fn requests(&self) -> &[MeasurementRequest] {
48        match self {
49            Self::Complete(_) => &[],
50            Self::Provisional { requests, .. } | Self::Blocked { requests, .. } => requests,
51        }
52    }
53
54    /// Returns whether geometry was committed to the retained scene.
55    pub const fn has_layout(&self) -> bool {
56        matches!(self, Self::Complete(_) | Self::Provisional { .. })
57    }
58}
59
60/// Summary of applying immediate Host measurement responses.
61#[derive(Clone, Debug, Default, PartialEq, Eq)]
62pub struct MeasurementApply {
63    applied: usize,
64    stale: usize,
65    invalidated_nodes: Vec<NodeId>,
66}
67
68impl MeasurementApply {
69    /// Returns the number of responses accepted into retained state.
70    pub const fn applied(&self) -> usize {
71        self.applied
72    }
73
74    /// Returns the number of unknown or wrong-epoch responses ignored.
75    pub const fn stale(&self) -> usize {
76        self.stale
77    }
78
79    pub(crate) fn invalidated_nodes(&self) -> &[NodeId] {
80        &self.invalidated_nodes
81    }
82}
83
84/// Result of applying one deferred Host measurement event.
85#[derive(Clone, Debug, PartialEq, Eq)]
86pub enum DeferredMeasurementApply {
87    /// Final metrics replaced a pending entry and dirtied current consumers.
88    Applied {
89        /// Nodes whose Taffy measurement cache must be invalidated.
90        invalidated_nodes: Vec<NodeId>,
91    },
92    /// The request, key, or environment generation was no longer current.
93    IgnoredStale,
94    /// A re-entrant Host callback was accepted for ordered delivery at the
95    /// next safe runtime boundary.
96    Queued,
97}
98
99impl DeferredMeasurementApply {
100    pub(crate) fn invalidated_nodes(&self) -> &[NodeId] {
101        match self {
102            Self::Applied { invalidated_nodes } => invalidated_nodes,
103            Self::IgnoredStale | Self::Queued => &[],
104        }
105    }
106}
107
108/// Failure while validating or resolving intrinsic measurement.
109#[derive(Clone, Debug, PartialEq)]
110pub enum MeasurementError {
111    /// A typed provider payload violated its schema invariants.
112    InvalidPayload {
113        /// Node whose payload was rejected.
114        node: NodeId,
115        /// Stable validation category.
116        error: MeasurementPayloadError,
117    },
118    /// A schema declared an invalid provisional placeholder.
119    InvalidPlaceholder {
120        /// Node whose schema was rejected.
121        node: NodeId,
122    },
123    /// A Host response contained non-finite or negative geometry.
124    InvalidMetrics {
125        /// Immediate request correlation key.
126        key: MeasurementKey,
127    },
128    /// Two live pending responses reused a deferred request identifier.
129    DuplicateRequestId {
130        /// Reused Host identifier.
131        request_id: MeasurementRequestId,
132    },
133    /// A measurable Taffy leaf had no paired measurement schema.
134    MissingSpec {
135        /// Inconsistent retained node.
136        node: NodeId,
137    },
138    /// A required provider explicitly rejected the request.
139    Unsupported {
140        /// Node that required measurement.
141        node: NodeId,
142        /// Provider diagnostic category.
143        reason: UnsupportedMeasurementReason,
144    },
145    /// The surface exhausted its immediate correlation-key space.
146    KeyExhausted,
147}
148
149impl fmt::Display for MeasurementError {
150    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
151        write!(formatter, "Whisker measurement error: {self:?}")
152    }
153}
154
155impl Error for MeasurementError {}
156
157#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
158enum AvailableSpaceKey {
159    Definite(u32),
160    MinContent,
161    MaxContent,
162}
163
164impl From<AvailableSpace> for AvailableSpaceKey {
165    fn from(value: AvailableSpace) -> Self {
166        match value {
167            AvailableSpace::Definite(value) => Self::Definite(value.to_bits()),
168            AvailableSpace::MinContent => Self::MinContent,
169            AvailableSpace::MaxContent => Self::MaxContent,
170        }
171    }
172}
173
174#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
175struct ConstraintsKey {
176    known_dimensions: [Option<u32>; 2],
177    available_space: [AvailableSpaceKey; 2],
178}
179
180impl From<MeasureConstraints> for ConstraintsKey {
181    fn from(value: MeasureConstraints) -> Self {
182        Self {
183            known_dimensions: value
184                .known_dimensions
185                .map(|dimension| dimension.map(f32::to_bits)),
186            available_space: value.available_space.map(Into::into),
187        }
188    }
189}
190
191#[derive(Clone, Debug, PartialEq, Eq, Hash)]
192struct CacheKey {
193    element_type: ElementTypeId,
194    kind: MeasurementKind,
195    content_hash: u64,
196    style_hash: u64,
197    environment_epoch: u64,
198    constraints: ConstraintsKey,
199    inline_children: Vec<(NodeId, u32, u32, u32)>,
200    paragraph_node: Option<NodeId>,
201}
202
203#[derive(Clone, Debug)]
204struct SpecState {
205    element_type: ElementTypeId,
206    spec: MeasurementSpec,
207    last_ready: Option<MeasurementMetrics>,
208    attachments: Vec<crate::InlineAttachmentInput>,
209}
210
211#[derive(Clone, Debug)]
212enum CachedState {
213    Ready(MeasurementMetrics),
214    Pending {
215        key: MeasurementKey,
216        request_id: MeasurementRequestId,
217        provisional: Option<MeasurementMetrics>,
218    },
219    Unsupported(UnsupportedMeasurementReason),
220}
221
222#[derive(Clone, Debug)]
223struct CacheEntry {
224    key: MeasurementKey,
225    payload: MeasurementPayload,
226    state: CachedState,
227    consumers: BTreeSet<NodeId>,
228}
229
230#[derive(Clone, Debug)]
231struct OutstandingRequest {
232    request: MeasurementRequest,
233    cache_key: CacheKey,
234    consumers: BTreeSet<NodeId>,
235}
236
237#[derive(Clone, Debug)]
238struct PendingRequest {
239    key: MeasurementKey,
240    cache_key: CacheKey,
241    environment_epoch: u64,
242}
243
244#[derive(Clone, Debug, Default)]
245struct PassState {
246    requests: BTreeMap<MeasurementKey, MeasurementRequest>,
247    pending: BTreeSet<MeasurementRequestId>,
248    blocking: bool,
249    provisional: bool,
250    error: Option<MeasurementError>,
251    issued: Option<MeasurementKey>,
252}
253
254#[derive(Clone, Debug)]
255pub(crate) struct MeasurementCoordinator {
256    specs: BTreeMap<NodeId, SpecState>,
257    cache: HashMap<CacheKey, CacheEntry>,
258    consumer_keys: HashMap<NodeId, Vec<CacheKey>>,
259    outstanding: BTreeMap<MeasurementKey, OutstandingRequest>,
260    outstanding_by_cache: HashMap<CacheKey, MeasurementKey>,
261    pending: BTreeMap<MeasurementRequestId, PendingRequest>,
262    environment_epoch: Option<u64>,
263    next_key: u64,
264    retention_revision: u64,
265    pass: PassState,
266}
267
268impl Default for MeasurementCoordinator {
269    fn default() -> Self {
270        Self {
271            specs: BTreeMap::new(),
272            cache: HashMap::new(),
273            consumer_keys: HashMap::new(),
274            outstanding: BTreeMap::new(),
275            outstanding_by_cache: HashMap::new(),
276            pending: BTreeMap::new(),
277            environment_epoch: None,
278            next_key: 1,
279            retention_revision: 0,
280            pass: PassState::default(),
281        }
282    }
283}
284
285impl MeasurementCoordinator {
286    pub(crate) fn set_environment(&mut self, epoch: u64) -> Vec<NodeId> {
287        let changed = self
288            .environment_epoch
289            .is_some_and(|current| current != epoch);
290        self.environment_epoch = Some(epoch);
291        if !changed {
292            return Vec::new();
293        }
294        self.retention_revision = self.retention_revision.wrapping_add(1);
295        self.cache.clear();
296        self.consumer_keys.clear();
297        self.outstanding.clear();
298        self.outstanding_by_cache.clear();
299        self.pending.clear();
300        self.specs.keys().copied().collect()
301    }
302
303    pub(crate) fn retained_content(
304        &self,
305    ) -> (
306        u64,
307        impl Iterator<Item = whisker_protocol::PreparedContentId> + '_,
308    ) {
309        let cached = self.cache.values().filter_map(|entry| match &entry.state {
310            CachedState::Ready(metrics) => metrics.prepared_content,
311            CachedState::Pending { provisional, .. } => provisional
312                .as_ref()
313                .and_then(|metrics| metrics.prepared_content),
314            CachedState::Unsupported(_) => None,
315        });
316        let provisional = self.specs.values().filter_map(|state| {
317            state
318                .last_ready
319                .as_ref()
320                .and_then(|metrics| metrics.prepared_content)
321        });
322        (self.retention_revision, cached.chain(provisional))
323    }
324
325    pub(crate) fn environment_epoch(&self) -> Option<u64> {
326        self.environment_epoch
327    }
328
329    pub(crate) fn matches_spec(
330        &self,
331        node: NodeId,
332        element_type: ElementTypeId,
333        spec: Option<&MeasurementSpec>,
334    ) -> bool {
335        self.specs
336            .get(&node)
337            .map(|state| (state.element_type, &state.spec))
338            == spec.map(|spec| (element_type, spec))
339    }
340
341    pub(crate) fn set_spec(
342        &mut self,
343        node: NodeId,
344        element_type: ElementTypeId,
345        spec: Option<MeasurementSpec>,
346    ) -> Result<bool, MeasurementError> {
347        if let Some(spec) = &spec {
348            spec.payload
349                .validate()
350                .map_err(|error| MeasurementError::InvalidPayload { node, error })?;
351        }
352        if let Some(MeasurementSpec {
353            pending_policy: PendingMeasurePolicy::Placeholder(size),
354            ..
355        }) = &spec
356            && !size.is_valid()
357        {
358            return Err(MeasurementError::InvalidPlaceholder { node });
359        }
360        if self.matches_spec(node, element_type, spec.as_ref()) {
361            return Ok(false);
362        }
363
364        self.retention_revision = self.retention_revision.wrapping_add(1);
365        self.remove_consumer(node);
366        let previous = self.specs.remove(&node).and_then(|state| state.last_ready);
367        if let Some(spec) = spec {
368            self.specs.insert(
369                node,
370                SpecState {
371                    element_type,
372                    spec,
373                    last_ready: previous,
374                    attachments: Vec::new(),
375                },
376            );
377        }
378        Ok(true)
379    }
380
381    pub(crate) fn remove_node(&mut self, node: NodeId) {
382        self.retention_revision = self.retention_revision.wrapping_add(1);
383        self.remove_consumer(node);
384        self.specs.remove(&node);
385    }
386
387    pub(crate) fn last_ready(&self, node: NodeId) -> Option<&MeasurementMetrics> {
388        self.specs.get(&node)?.last_ready.as_ref()
389    }
390
391    pub(crate) fn inline_attachments_match(
392        &self,
393        node: NodeId,
394        attachments: &[crate::InlineAttachmentInput],
395    ) -> bool {
396        self.specs
397            .get(&node)
398            .is_some_and(|state| state.attachments == attachments)
399    }
400
401    pub(crate) fn set_inline_attachments(
402        &mut self,
403        node: NodeId,
404        attachments: &[crate::InlineAttachmentInput],
405    ) {
406        self.specs
407            .get_mut(&node)
408            .expect("paragraph measurement spec")
409            .attachments = attachments.to_vec();
410    }
411
412    pub(crate) fn outstanding_requests(&self) -> Vec<MeasurementRequest> {
413        self.outstanding
414            .values()
415            .filter(|request| !request.consumers.is_empty())
416            .map(|request| request.request.clone())
417            .collect()
418    }
419
420    pub(crate) fn pending_count(&self) -> usize {
421        self.cache
422            .values()
423            .filter(|entry| {
424                !entry.consumers.is_empty() && matches!(entry.state, CachedState::Pending { .. })
425            })
426            .count()
427    }
428
429    pub(crate) fn unresolved_nodes(&self) -> Vec<NodeId> {
430        let mut nodes = BTreeSet::new();
431        for request in self.outstanding.values() {
432            nodes.extend(&request.consumers);
433        }
434        for entry in self.cache.values() {
435            if matches!(entry.state, CachedState::Pending { .. }) {
436                nodes.extend(&entry.consumers);
437            }
438        }
439        nodes.into_iter().collect()
440    }
441
442    pub(crate) fn begin_pass(&mut self) {
443        self.pass = PassState::default();
444    }
445
446    pub(crate) fn finish_pass(&mut self) -> Result<PassSummary, MeasurementError> {
447        if let Some(error) = self.pass.error.take() {
448            return Err(error);
449        }
450        Ok(PassSummary {
451            requests: std::mem::take(&mut self.pass.requests)
452                .into_values()
453                .collect(),
454            pending: self.pass.pending.len(),
455            blocking: self.pass.blocking,
456            provisional: self.pass.provisional,
457        })
458    }
459
460    pub(crate) fn apply_batch(
461        &mut self,
462        responses: &[MeasurementResponse],
463    ) -> Result<MeasurementApply, MeasurementError> {
464        let mut consumed = BTreeSet::new();
465        let mut pending_ids = BTreeSet::new();
466        let mut validated = Vec::with_capacity(responses.len());
467        let mut apply = MeasurementApply::default();
468        for response in responses {
469            let key = response.key();
470            let current = self.outstanding.get(&key).is_some_and(|outstanding| {
471                outstanding.request.environment_epoch == response.environment_epoch()
472                    && self.environment_epoch == Some(response.environment_epoch())
473            });
474            if !current || !consumed.insert(key) {
475                apply.stale += 1;
476                continue;
477            }
478            match response {
479                MeasurementResponse::Ready { metrics, .. } => {
480                    self.validate_metrics(key, metrics)?
481                }
482                MeasurementResponse::Pending {
483                    request_id,
484                    provisional,
485                    ..
486                } => {
487                    if self.pending.contains_key(request_id) || !pending_ids.insert(*request_id) {
488                        return Err(MeasurementError::DuplicateRequestId {
489                            request_id: *request_id,
490                        });
491                    }
492                    if let Some(metrics) = provisional {
493                        self.validate_metrics(key, metrics)?;
494                    }
495                }
496                MeasurementResponse::Unsupported { .. } => {}
497            }
498            validated.push(response);
499        }
500
501        if !validated.is_empty() {
502            self.retention_revision = self.retention_revision.wrapping_add(1);
503        }
504        let mut invalidated = BTreeSet::new();
505        for response in validated {
506            self.commit_response(response, &mut invalidated);
507            apply.applied += 1;
508        }
509        apply.invalidated_nodes = invalidated.into_iter().collect();
510        Ok(apply)
511    }
512
513    pub(crate) fn apply_ready(
514        &mut self,
515        ready: &MeasurementReady,
516    ) -> Result<DeferredMeasurementApply, MeasurementError> {
517        self.retention_revision = self.retention_revision.wrapping_add(1);
518        let Some(pending) = self.pending.get(&ready.request_id).cloned() else {
519            return Ok(DeferredMeasurementApply::IgnoredStale);
520        };
521        if pending.key != ready.key
522            || pending.environment_epoch != ready.environment_epoch
523            || self.environment_epoch != Some(ready.environment_epoch)
524        {
525            return Ok(DeferredMeasurementApply::IgnoredStale);
526        }
527        if self
528            .cache
529            .get(&pending.cache_key)
530            .is_some_and(|entry| !ready.metrics.matches_payload(&entry.payload))
531        {
532            return Err(MeasurementError::InvalidMetrics { key: ready.key });
533        }
534        let Some(entry) = self.cache.get_mut(&pending.cache_key) else {
535            return Ok(DeferredMeasurementApply::IgnoredStale);
536        };
537        if !matches!(
538            entry.state,
539            CachedState::Pending {
540                key,
541                request_id,
542                ..
543            } if key == ready.key && request_id == ready.request_id
544        ) {
545            return Ok(DeferredMeasurementApply::IgnoredStale);
546        }
547
548        let consumers = entry.consumers.clone();
549        entry.state = CachedState::Ready(ready.metrics.clone());
550        self.pending.remove(&ready.request_id);
551        self.remember_ready(&consumers, &ready.metrics);
552        Ok(DeferredMeasurementApply::Applied {
553            invalidated_nodes: consumers.into_iter().collect(),
554        })
555    }
556
557    fn commit_response(
558        &mut self,
559        response: &MeasurementResponse,
560        invalidated: &mut BTreeSet<NodeId>,
561    ) {
562        let key = response.key();
563        let outstanding = self
564            .outstanding
565            .remove(&key)
566            .expect("validated responses consume each outstanding request once");
567        self.outstanding_by_cache.remove(&outstanding.cache_key);
568        invalidated.extend(&outstanding.consumers);
569        let state = match response {
570            MeasurementResponse::Ready { metrics, .. } => {
571                self.remember_ready(&outstanding.consumers, metrics);
572                CachedState::Ready(metrics.clone())
573            }
574            MeasurementResponse::Pending {
575                request_id,
576                provisional,
577                ..
578            } => {
579                self.pending.insert(
580                    *request_id,
581                    PendingRequest {
582                        key,
583                        cache_key: outstanding.cache_key.clone(),
584                        environment_epoch: response.environment_epoch(),
585                    },
586                );
587                CachedState::Pending {
588                    key,
589                    request_id: *request_id,
590                    provisional: provisional.clone(),
591                }
592            }
593            MeasurementResponse::Unsupported { reason, .. } => CachedState::Unsupported(*reason),
594        };
595        self.cache.insert(
596            outstanding.cache_key,
597            CacheEntry {
598                key,
599                payload: outstanding.request.payload,
600                state,
601                consumers: outstanding.consumers,
602            },
603        );
604    }
605
606    fn validate_metrics(
607        &self,
608        key: MeasurementKey,
609        metrics: &MeasurementMetrics,
610    ) -> Result<(), MeasurementError> {
611        if self
612            .outstanding
613            .get(&key)
614            .is_some_and(|request| metrics.matches_payload(&request.request.payload))
615        {
616            Ok(())
617        } else {
618            Err(MeasurementError::InvalidMetrics { key })
619        }
620    }
621
622    fn remember_ready(&mut self, consumers: &BTreeSet<NodeId>, metrics: &MeasurementMetrics) {
623        for node in consumers {
624            self.specs
625                .get_mut(node)
626                .expect("measurement consumers retain their registered specs")
627                .last_ready = Some(metrics.clone());
628        }
629    }
630
631    fn remove_consumer(&mut self, node: NodeId) {
632        let Some(cache_keys) = self.consumer_keys.remove(&node) else {
633            return;
634        };
635        for cache_key in cache_keys {
636            let remove_cached = self.cache.get_mut(&cache_key).is_some_and(|entry| {
637                entry.consumers.remove(&node);
638                entry.consumers.is_empty()
639            });
640            if remove_cached {
641                let entry = self
642                    .cache
643                    .remove(&cache_key)
644                    .expect("checked cache entry remains present");
645                if let CachedState::Pending { request_id, .. } = entry.state {
646                    self.pending.remove(&request_id);
647                }
648                continue;
649            }
650
651            let Some(key) = self.outstanding_by_cache.get(&cache_key).copied() else {
652                continue;
653            };
654            let remove_outstanding = self.outstanding.get_mut(&key).is_some_and(|request| {
655                request.consumers.remove(&node);
656                request.consumers.is_empty()
657            });
658            if remove_outstanding {
659                self.outstanding.remove(&key);
660                self.outstanding_by_cache.remove(&cache_key);
661            }
662        }
663    }
664
665    fn remember_consumer(&mut self, node: NodeId, cache_key: CacheKey) {
666        self.consumer_keys.entry(node).or_default().push(cache_key);
667    }
668
669    fn cache_key(state: &SpecState, constraints: MeasureConstraints, epoch: u64) -> CacheKey {
670        CacheKey {
671            element_type: state.element_type,
672            kind: state.spec.payload.kind(),
673            content_hash: state.spec.content_hash,
674            style_hash: state.spec.style_hash,
675            environment_epoch: epoch,
676            constraints: constraints.into(),
677            inline_children: Vec::new(),
678            paragraph_node: None,
679        }
680    }
681
682    fn use_fallback(
683        &mut self,
684        policy: PendingMeasurePolicy,
685        last_ready: Option<&MeasurementMetrics>,
686        provider_provisional: Option<&MeasurementMetrics>,
687    ) -> LayoutSize {
688        if let Some(metrics) = provider_provisional {
689            self.pass.provisional = true;
690            return to_layout_size(metrics.size);
691        }
692        match policy {
693            PendingMeasurePolicy::Block => {
694                self.pass.blocking = true;
695                LayoutSize::default()
696            }
697            PendingMeasurePolicy::Placeholder(size) => {
698                self.pass.provisional = true;
699                to_layout_size(size)
700            }
701            PendingMeasurePolicy::RetainPrevious => {
702                if let Some(metrics) = last_ready {
703                    self.pass.provisional = true;
704                    to_layout_size(metrics.size)
705                } else {
706                    self.pass.blocking = true;
707                    LayoutSize::default()
708                }
709            }
710        }
711    }
712
713    fn allocate_key(&mut self) -> Result<MeasurementKey, MeasurementError> {
714        let key = MeasurementKey::new(self.next_key).ok_or(MeasurementError::KeyExhausted)?;
715        self.next_key = self.next_key.checked_add(1).unwrap_or(0);
716        Ok(key)
717    }
718}
719
720impl MeasurementCoordinator {
721    fn resolve_intrinsic(
722        &mut self,
723        node: NodeId,
724        constraints: LayoutMeasureRequest,
725        children: &[MeasuredInlineChild],
726    ) -> IntrinsicResult {
727        let Some(mut state) = self.specs.get(&node).cloned() else {
728            self.pass
729                .error
730                .get_or_insert(MeasurementError::MissingSpec { node });
731            return IntrinsicResult {
732                state: MeasurementState::Blocked,
733                ..IntrinsicResult::default()
734            };
735        };
736        if let MeasurementPayload::Text(payload) = &mut state.spec.payload {
737            if !state.attachments.is_empty() {
738                if state.attachments.len() != children.len()
739                    || state.attachments.iter().any(|attachment| {
740                        !children.iter().any(|child| child.node == attachment.node)
741                    })
742                {
743                    self.pass
744                        .error
745                        .get_or_insert(MeasurementError::MissingSpec { node });
746                    return IntrinsicResult {
747                        state: MeasurementState::Blocked,
748                        ..IntrinsicResult::default()
749                    };
750                }
751                payload.attachments = state
752                    .attachments
753                    .iter()
754                    .map(|attachment| {
755                        let child = children
756                            .iter()
757                            .find(|child| child.node == attachment.node)
758                            .expect("validated inline subtree");
759                        whisker_protocol::InlineAttachment {
760                            truncation: attachment.truncation,
761                            label: attachment.label.clone(),
762                            node: attachment.node,
763                            range: attachment.range,
764                            alignment: attachment.alignment,
765                            size: MeasuredSize::new(child.size.width, child.size.height),
766                            baseline: child.baseline,
767                        }
768                    })
769                    .collect();
770            }
771        }
772        let constraints = if state.spec.payload.kind() == MeasurementKind::Text {
773            MeasureConstraints {
774                available_space: [constraints.available_space[0], AvailableSpace::MaxContent],
775                ..constraints
776            }
777        } else {
778            constraints
779        };
780        let epoch = self.environment_epoch.unwrap_or(0);
781        let mut cache_key = Self::cache_key(&state, constraints, epoch);
782        if matches!(&state.spec.payload, MeasurementPayload::Text(text) if !text.runs.is_empty() || !text.attachments.is_empty())
783        {
784            cache_key.paragraph_node = Some(node);
785        }
786        cache_key.inline_children = children
787            .iter()
788            .map(|child| {
789                (
790                    child.node,
791                    child.size.width.to_bits(),
792                    child.size.height.to_bits(),
793                    child.baseline.to_bits(),
794                )
795            })
796            .collect();
797
798        if let Some(entry) = self.cache.get_mut(&cache_key) {
799            let added = entry.consumers.insert(node);
800            let cached = entry.state.clone();
801            let selection = entry.key;
802            if added {
803                self.remember_consumer(node, cache_key);
804            }
805            return match cached {
806                CachedState::Ready(metrics) => {
807                    self.specs
808                        .get_mut(&node)
809                        .expect("measurement node retains its registered spec")
810                        .last_ready = Some(metrics.clone());
811                    IntrinsicResult {
812                        size: to_layout_size(metrics.size),
813                        first_baseline: metrics.first_baseline,
814                        state: MeasurementState::Ready,
815                        selection: Some(selection),
816                        inline_placements: metrics.inline_placements,
817                    }
818                }
819                CachedState::Pending {
820                    request_id,
821                    provisional,
822                    ..
823                } => {
824                    self.pass.pending.insert(request_id);
825                    self.fallback_result(
826                        state.spec.pending_policy,
827                        state.last_ready.as_ref(),
828                        provisional.as_ref(),
829                    )
830                }
831                CachedState::Unsupported(reason) => {
832                    self.pass
833                        .error
834                        .get_or_insert(MeasurementError::Unsupported { node, reason });
835                    IntrinsicResult {
836                        state: MeasurementState::Blocked,
837                        ..IntrinsicResult::default()
838                    }
839                }
840            };
841        }
842
843        if let Some(key) = self.outstanding_by_cache.get(&cache_key).copied() {
844            let request = self
845                .outstanding
846                .get_mut(&key)
847                .expect("cache index points to an outstanding request");
848            let added = request.consumers.insert(node);
849            self.pass.requests.insert(key, request.request.clone());
850            if added {
851                self.remember_consumer(node, cache_key);
852            }
853            return self.fallback_result(
854                state.spec.pending_policy,
855                state.last_ready.as_ref(),
856                None,
857            );
858        }
859
860        let key = match self.allocate_key() {
861            Ok(key) => key,
862            Err(error) => {
863                self.pass.error.get_or_insert(error);
864                return IntrinsicResult {
865                    state: MeasurementState::Blocked,
866                    ..IntrinsicResult::default()
867                };
868            }
869        };
870        let request = MeasurementRequest {
871            key,
872            node,
873            element_type: state.element_type,
874            environment_epoch: epoch,
875            constraints,
876            payload: state.spec.payload.clone(),
877        };
878        self.outstanding_by_cache.insert(cache_key.clone(), key);
879        self.outstanding.insert(
880            key,
881            OutstandingRequest {
882                request: request.clone(),
883                cache_key: cache_key.clone(),
884                consumers: BTreeSet::from([node]),
885            },
886        );
887        self.remember_consumer(node, cache_key);
888        self.pass.requests.insert(key, request);
889        self.pass.issued = Some(key);
890        self.fallback_result(state.spec.pending_policy, state.last_ready.as_ref(), None)
891    }
892}
893
894/// Answers one Host request while Taffy waits, or `None` after recording why it could not.
895pub(crate) type ImmediateHost<'h> =
896    dyn FnMut(&MeasurementRequest) -> Option<MeasurementResponse> + 'h;
897
898/// Asks the Host for each uncached measurement as Taffy needs it, so one pass
899/// lays out with real sizes instead of blocking on a batch round trip.
900pub(crate) struct ImmediateMeasurer<'a, 'h> {
901    pub(crate) coordinator: &'a mut MeasurementCoordinator,
902    pub(crate) host: &'a mut ImmediateHost<'h>,
903}
904
905impl ImmediateMeasurer<'_, '_> {
906    fn resolve(
907        &mut self,
908        node: NodeId,
909        constraints: LayoutMeasureRequest,
910        children: &[MeasuredInlineChild],
911    ) -> IntrinsicResult {
912        let pass = &self.coordinator.pass;
913        let (blocking, provisional) = (pass.blocking, pass.provisional);
914        let result = self
915            .coordinator
916            .resolve_intrinsic(node, constraints, children);
917        let Some(key) = self.coordinator.pass.issued.take() else {
918            return result;
919        };
920        let request = self.coordinator.pass.requests[&key].clone();
921        let Some(response) = (self.host)(&request) else {
922            return result;
923        };
924        // The fallback above only stood in for this request, which now has an answer.
925        self.coordinator.pass.requests.remove(&key);
926        self.coordinator.pass.blocking = blocking;
927        self.coordinator.pass.provisional = provisional;
928        if let Err(error) = self
929            .coordinator
930            .apply_batch(std::slice::from_ref(&response))
931        {
932            self.coordinator.pass.error.get_or_insert(error);
933            return result;
934        }
935        self.coordinator
936            .resolve_intrinsic(node, constraints, children)
937    }
938}
939
940impl IntrinsicMeasurer for ImmediateMeasurer<'_, '_> {
941    fn measure(&mut self, node: NodeId, request: LayoutMeasureRequest) -> LayoutSize {
942        self.resolve(node, request, &[]).size
943    }
944
945    fn measure_detailed(&mut self, node: NodeId, request: LayoutMeasureRequest) -> IntrinsicResult {
946        self.resolve(node, request, &[])
947    }
948
949    fn measure_paragraph(
950        &mut self,
951        node: NodeId,
952        request: LayoutMeasureRequest,
953        children: &[MeasuredInlineChild],
954    ) -> IntrinsicResult {
955        self.resolve(node, request, children)
956    }
957}
958
959impl IntrinsicMeasurer for MeasurementCoordinator {
960    fn measure(&mut self, node: NodeId, request: LayoutMeasureRequest) -> LayoutSize {
961        self.resolve_intrinsic(node, request, &[]).size
962    }
963
964    fn measure_detailed(&mut self, node: NodeId, request: LayoutMeasureRequest) -> IntrinsicResult {
965        self.resolve_intrinsic(node, request, &[])
966    }
967
968    fn measure_paragraph(
969        &mut self,
970        node: NodeId,
971        request: LayoutMeasureRequest,
972        children: &[MeasuredInlineChild],
973    ) -> IntrinsicResult {
974        self.resolve_intrinsic(node, request, children)
975    }
976}
977
978impl MeasurementCoordinator {
979    pub(crate) fn selected(
980        &self,
981        node: NodeId,
982        selection: MeasurementKey,
983    ) -> Option<(&MeasurementPayload, &MeasurementMetrics)> {
984        self.consumer_keys.get(&node)?.iter().find_map(|key| {
985            let entry = self.cache.get(key).expect("retained measurement consumer");
986            if entry.key != selection {
987                return None;
988            }
989            match &entry.state {
990                CachedState::Ready(metrics) => Some((&entry.payload, metrics)),
991                _ => None,
992            }
993        })
994    }
995
996    fn fallback_result(
997        &mut self,
998        policy: PendingMeasurePolicy,
999        previous: Option<&MeasurementMetrics>,
1000        provisional: Option<&MeasurementMetrics>,
1001    ) -> IntrinsicResult {
1002        let size = self.use_fallback(policy, previous, provisional);
1003        let metrics = provisional.or_else(|| {
1004            (policy == PendingMeasurePolicy::RetainPrevious)
1005                .then_some(previous)
1006                .flatten()
1007        });
1008        let ready_fallback = provisional.is_some()
1009            || matches!(policy, PendingMeasurePolicy::Placeholder(_))
1010            || (policy == PendingMeasurePolicy::RetainPrevious && previous.is_some());
1011        IntrinsicResult {
1012            size,
1013            first_baseline: metrics.and_then(|metrics| metrics.first_baseline),
1014            state: if ready_fallback {
1015                MeasurementState::Provisional
1016            } else {
1017                MeasurementState::Blocked
1018            },
1019            selection: None,
1020            inline_placements: metrics
1021                .map_or_else(Vec::new, |metrics| metrics.inline_placements.clone()),
1022        }
1023    }
1024}
1025
1026fn to_layout_size(value: MeasuredSize) -> LayoutSize {
1027    LayoutSize::new(value.width, value.height)
1028}
1029
1030#[derive(Clone, Debug, PartialEq)]
1031pub(crate) struct PassSummary {
1032    pub(crate) requests: Vec<MeasurementRequest>,
1033    pub(crate) pending: usize,
1034    pub(crate) blocking: bool,
1035    pub(crate) provisional: bool,
1036}
1037
1038#[cfg(test)]
1039mod tests {
1040    use whisker_protocol::{
1041        CustomMeasurePayload, EmbeddedSurfaceMeasurePayload, LayoutRect, MeasureFontFamily,
1042        MeasureFontStyle, MeasureLineHeight, MeasureTextDirection, MeasureTextOverflow,
1043        MeasureTextWrap, MeasurementPayload, NativeControlMeasurePayload, PreparedContentId,
1044        ReplacedContentMeasurePayload, SurfaceId, TextMeasurePayload, TextMeasureStyle,
1045    };
1046
1047    use super::*;
1048
1049    fn node(value: u64) -> NodeId {
1050        NodeId::new(value).expect("node")
1051    }
1052
1053    fn element() -> ElementTypeId {
1054        ElementTypeId::new(1).expect("element")
1055    }
1056
1057    fn constraints(width: f32) -> MeasureConstraints {
1058        MeasureConstraints {
1059            known_dimensions: [None, Some(10.0)],
1060            available_space: [AvailableSpace::Definite(width), AvailableSpace::MaxContent],
1061        }
1062    }
1063
1064    fn spec(kind: MeasurementKind, policy: PendingMeasurePolicy) -> MeasurementSpec {
1065        MeasurementSpec {
1066            content_hash: 7,
1067            style_hash: 9,
1068            payload: payload(kind),
1069            pending_policy: policy,
1070        }
1071    }
1072
1073    fn payload(kind: MeasurementKind) -> MeasurementPayload {
1074        match kind {
1075            MeasurementKind::Text => MeasurementPayload::Text(TextMeasurePayload {
1076                runs: Vec::new(),
1077                attachments: Vec::new(),
1078                text: "payload".into(),
1079                style: TextMeasureStyle {
1080                    font_families: vec![MeasureFontFamily::System],
1081                    font_size: 14.0,
1082                    font_weight: 400,
1083                    font_style: MeasureFontStyle::Normal,
1084                    line_height: MeasureLineHeight::Normal,
1085                    letter_spacing: 0.0,
1086                    ..TextMeasureStyle::default()
1087                },
1088                locale: None,
1089                direction: MeasureTextDirection::Auto,
1090                alignment: whisker_protocol::MeasureTextAlignment::Start,
1091                indent: Default::default(),
1092                wrap: MeasureTextWrap::Wrap,
1093                word_break: Default::default(),
1094                max_lines: None,
1095                overflow: MeasureTextOverflow::Clip,
1096            }),
1097            MeasurementKind::ReplacedContent => {
1098                MeasurementPayload::ReplacedContent(ReplacedContentMeasurePayload::default())
1099            }
1100            MeasurementKind::NativeControl => {
1101                MeasurementPayload::NativeControl(NativeControlMeasurePayload {
1102                    control_type: 1,
1103                    version: 1,
1104                    state: vec![1],
1105                })
1106            }
1107            MeasurementKind::EmbeddedSurface => {
1108                MeasurementPayload::EmbeddedSurface(EmbeddedSurfaceMeasurePayload {
1109                    surface: SurfaceId::new(2).expect("child surface"),
1110                    preferred_size: None,
1111                })
1112            }
1113            MeasurementKind::Custom { version } => {
1114                MeasurementPayload::Custom(CustomMeasurePayload {
1115                    version,
1116                    data: whisker_protocol::WhiskerValue::Bytes(b"payload".to_vec()),
1117                })
1118            }
1119        }
1120    }
1121
1122    fn metrics(width: f32, height: f32) -> MeasurementMetrics {
1123        MeasurementMetrics {
1124            paragraph: None,
1125            inline_placements: Vec::new(),
1126            size: MeasuredSize::new(width, height),
1127            first_baseline: Some(6.0),
1128            last_baseline: Some(7.0),
1129            overflow: Some(LayoutRect {
1130                width,
1131                height,
1132                ..LayoutRect::default()
1133            }),
1134            prepared_content: PreparedContentId::new(3),
1135        }
1136    }
1137
1138    #[test]
1139    fn immediate_measurer_applies_answers_and_records_rejected_ones() {
1140        let mut coordinator = MeasurementCoordinator::default();
1141        coordinator.set_environment(1);
1142        coordinator
1143            .set_spec(
1144                node(1),
1145                element(),
1146                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1147            )
1148            .unwrap();
1149        let mut width = 30.0;
1150        let mut host = |request: &MeasurementRequest| {
1151            Some(MeasurementResponse::Ready {
1152                key: request.key,
1153                environment_epoch: request.environment_epoch,
1154                metrics: MeasurementMetrics::from_size(MeasuredSize::new(width, 10.0)),
1155            })
1156        };
1157        coordinator.begin_pass();
1158        let size = ImmediateMeasurer {
1159            coordinator: &mut coordinator,
1160            host: &mut host,
1161        }
1162        .measure(node(1), constraints(100.0));
1163        assert_eq!(size, LayoutSize::new(30.0, 10.0));
1164        assert!(coordinator.finish_pass().unwrap().requests.is_empty());
1165
1166        width = -1.0;
1167        let mut rejected = None;
1168        let mut host = |request: &MeasurementRequest| {
1169            rejected = Some(request.key);
1170            Some(MeasurementResponse::Ready {
1171                key: request.key,
1172                environment_epoch: request.environment_epoch,
1173                metrics: MeasurementMetrics::from_size(MeasuredSize::new(width, 10.0)),
1174            })
1175        };
1176        coordinator.begin_pass();
1177        ImmediateMeasurer {
1178            coordinator: &mut coordinator,
1179            host: &mut host,
1180        }
1181        .measure(node(1), constraints(50.0));
1182        assert_eq!(
1183            coordinator.finish_pass().map(|_| ()),
1184            Err(MeasurementError::InvalidMetrics {
1185                key: rejected.expect("the Host saw the request"),
1186            })
1187        );
1188    }
1189
1190    #[test]
1191    fn text_measurement_shares_intrinsic_height_constraints() {
1192        let mut coordinator = MeasurementCoordinator::default();
1193        coordinator.set_environment(1);
1194        let node = NodeId::new(1).unwrap();
1195        coordinator
1196            .set_spec(
1197                node,
1198                ElementTypeId::new(1).unwrap(),
1199                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1200            )
1201            .unwrap();
1202        coordinator.begin_pass();
1203        for height in [
1204            AvailableSpace::MinContent,
1205            AvailableSpace::MaxContent,
1206            AvailableSpace::Definite(16.0),
1207            AvailableSpace::Definite(20.0),
1208        ] {
1209            coordinator.measure(
1210                node,
1211                MeasureConstraints {
1212                    known_dimensions: [Some(100.0), None],
1213                    available_space: [AvailableSpace::Definite(100.0), height],
1214                },
1215            );
1216        }
1217        let pass = coordinator.finish_pass().unwrap();
1218        assert_eq!(pass.requests.len(), 1);
1219        assert_eq!(
1220            pass.requests[0].constraints.available_space[1],
1221            AvailableSpace::MaxContent
1222        );
1223    }
1224
1225    #[test]
1226    fn text_height_reuse_preserves_width_known_height_and_other_measurement_kinds() {
1227        let mut coordinator = MeasurementCoordinator::default();
1228        coordinator.set_environment(1);
1229        for (index, kind) in [
1230            MeasurementKind::Text,
1231            MeasurementKind::ReplacedContent,
1232            MeasurementKind::NativeControl,
1233            MeasurementKind::EmbeddedSurface,
1234            MeasurementKind::Custom { version: 1 },
1235        ]
1236        .into_iter()
1237        .enumerate()
1238        {
1239            let node = node(index as u64 + 1);
1240            coordinator
1241                .set_spec(
1242                    node,
1243                    element(),
1244                    Some(spec(kind, PendingMeasurePolicy::Block)),
1245                )
1246                .unwrap();
1247            coordinator.begin_pass();
1248            for width in [100.0, 101.0] {
1249                for known_height in [None, Some(20.0)] {
1250                    for height in [AvailableSpace::MaxContent, AvailableSpace::Definite(16.0)] {
1251                        coordinator.measure(
1252                            node,
1253                            MeasureConstraints {
1254                                known_dimensions: [Some(width), known_height],
1255                                available_space: [AvailableSpace::Definite(width), height],
1256                            },
1257                        );
1258                    }
1259                }
1260            }
1261            let pass = coordinator.finish_pass().unwrap();
1262            assert_eq!(
1263                pass.requests.len(),
1264                if kind == MeasurementKind::Text { 4 } else { 8 }
1265            );
1266            let responses = pass
1267                .requests
1268                .iter()
1269                .map(|request| MeasurementResponse::Ready {
1270                    key: request.key,
1271                    environment_epoch: 1,
1272                    metrics: metrics(100.0, 20.0),
1273                })
1274                .collect::<Vec<_>>();
1275            coordinator.apply_batch(&responses).unwrap();
1276            coordinator.begin_pass();
1277            let size = coordinator.measure(
1278                node,
1279                MeasureConstraints {
1280                    known_dimensions: [Some(100.0), None],
1281                    available_space: [
1282                        AvailableSpace::Definite(100.0),
1283                        AvailableSpace::Definite(16.0),
1284                    ],
1285                },
1286            );
1287            assert_eq!(size, LayoutSize::new(100.0, 20.0));
1288            assert!(coordinator.finish_pass().unwrap().requests.is_empty());
1289        }
1290    }
1291
1292    #[test]
1293    fn rich_preparations_are_isolated_per_node_and_reused_for_each_consumer() {
1294        for rich in [false, true] {
1295            let mut coordinator = MeasurementCoordinator::default();
1296            coordinator.set_environment(1);
1297            let mut value = spec(MeasurementKind::Text, PendingMeasurePolicy::Block);
1298            if rich && let MeasurementPayload::Text(text) = &mut value.payload {
1299                text.runs.push(whisker_protocol::TextMeasureRun {
1300                    range: whisker_protocol::TextByteRange {
1301                        start: 0,
1302                        end: text.text.len() as u32,
1303                    },
1304                    style: text.style.clone(),
1305                    alignment: whisker_protocol::InlineAlignment::Baseline,
1306                });
1307            }
1308            for id in [1, 2] {
1309                coordinator
1310                    .set_spec(node(id), element(), Some(value.clone()))
1311                    .unwrap();
1312            }
1313            coordinator.begin_pass();
1314            for id in [1, 2] {
1315                coordinator.measure(node(id), constraints(100.0));
1316            }
1317            let pass = coordinator.finish_pass().unwrap();
1318            assert_eq!(pass.requests.len(), if rich { 2 } else { 1 });
1319            for request in pass.requests {
1320                coordinator
1321                    .apply_batch(&[MeasurementResponse::Ready {
1322                        key: request.key,
1323                        environment_epoch: 1,
1324                        metrics: metrics(20.0, 10.0),
1325                    }])
1326                    .unwrap();
1327            }
1328            coordinator.begin_pass();
1329            for id in [1, 2] {
1330                assert_eq!(
1331                    coordinator.measure(node(id), constraints(100.0)),
1332                    LayoutSize::new(20.0, 10.0)
1333                );
1334            }
1335            assert!(coordinator.finish_pass().unwrap().requests.is_empty());
1336        }
1337    }
1338
1339    #[test]
1340    fn coordinator_deduplicates_caches_and_invalidates_environment() {
1341        let mut coordinator = MeasurementCoordinator::default();
1342        assert!(coordinator.set_environment(1).is_empty());
1343        assert!(coordinator.set_environment(1).is_empty());
1344        assert!(
1345            coordinator
1346                .set_spec(
1347                    node(1),
1348                    element(),
1349                    Some(spec(
1350                        MeasurementKind::Text,
1351                        PendingMeasurePolicy::Placeholder(MeasuredSize::new(2.0, 3.0)),
1352                    )),
1353                )
1354                .unwrap()
1355        );
1356        assert!(
1357            !coordinator
1358                .set_spec(
1359                    node(1),
1360                    element(),
1361                    Some(spec(
1362                        MeasurementKind::Text,
1363                        PendingMeasurePolicy::Placeholder(MeasuredSize::new(2.0, 3.0)),
1364                    )),
1365                )
1366                .unwrap()
1367        );
1368        coordinator
1369            .set_spec(
1370                node(2),
1371                element(),
1372                Some(spec(
1373                    MeasurementKind::Text,
1374                    PendingMeasurePolicy::Placeholder(MeasuredSize::new(2.0, 3.0)),
1375                )),
1376            )
1377            .unwrap();
1378
1379        coordinator.begin_pass();
1380        assert_eq!(
1381            coordinator.measure(node(1), constraints(100.0)),
1382            LayoutSize::new(2.0, 3.0)
1383        );
1384        assert_eq!(
1385            coordinator.measure(node(2), constraints(100.0)),
1386            LayoutSize::new(2.0, 3.0)
1387        );
1388        let pass = coordinator.finish_pass().unwrap();
1389        assert_eq!(pass.requests.len(), 1);
1390        assert!(pass.provisional);
1391        assert!(!pass.blocking);
1392
1393        let request = pass.requests[0].clone();
1394        let apply = coordinator
1395            .apply_batch(&[MeasurementResponse::Ready {
1396                key: request.key,
1397                environment_epoch: 1,
1398                metrics: metrics(20.0, 10.0),
1399            }])
1400            .unwrap();
1401        assert_eq!(apply.applied(), 1);
1402        assert_eq!(apply.stale(), 0);
1403        assert_eq!(apply.invalidated_nodes(), [node(1), node(2)]);
1404
1405        coordinator.begin_pass();
1406        assert_eq!(
1407            coordinator.measure(node(1), constraints(100.0)),
1408            LayoutSize::new(20.0, 10.0)
1409        );
1410        let pass = coordinator.finish_pass().unwrap();
1411        assert!(pass.requests.is_empty());
1412        assert!(!pass.provisional);
1413        assert_eq!(coordinator.last_ready(node(1)), Some(&metrics(20.0, 10.0)));
1414        assert_eq!(coordinator.pending_count(), 0);
1415
1416        assert_eq!(coordinator.set_environment(2), [node(1), node(2)]);
1417        coordinator.begin_pass();
1418        coordinator.measure(node(1), constraints(100.0));
1419        assert_eq!(coordinator.finish_pass().unwrap().requests.len(), 1);
1420    }
1421
1422    #[test]
1423    fn pending_completion_rejects_stale_and_validates_metrics() {
1424        let mut coordinator = MeasurementCoordinator::default();
1425        coordinator.set_environment(4);
1426        coordinator
1427            .set_spec(
1428                node(1),
1429                element(),
1430                Some(spec(
1431                    MeasurementKind::ReplacedContent,
1432                    PendingMeasurePolicy::Block,
1433                )),
1434            )
1435            .unwrap();
1436        coordinator.begin_pass();
1437        assert_eq!(
1438            coordinator.measure(node(1), constraints(80.0)),
1439            LayoutSize::default()
1440        );
1441        let pass = coordinator.finish_pass().unwrap();
1442        assert!(pass.blocking);
1443        let key = pass.requests[0].key;
1444        let request_id = MeasurementRequestId::new(11).expect("request");
1445        let apply = coordinator
1446            .apply_batch(&[MeasurementResponse::Pending {
1447                key,
1448                environment_epoch: 4,
1449                request_id,
1450                provisional: Some(metrics(8.0, 6.0)),
1451            }])
1452            .unwrap();
1453        assert_eq!(apply.applied(), 1);
1454
1455        coordinator.begin_pass();
1456        assert_eq!(
1457            coordinator.measure(node(1), constraints(80.0)),
1458            LayoutSize::new(8.0, 6.0)
1459        );
1460        let pass = coordinator.finish_pass().unwrap();
1461        assert_eq!(pass.pending, 1);
1462        assert!(pass.provisional);
1463
1464        let wrong = MeasurementReady {
1465            key,
1466            request_id,
1467            environment_epoch: 5,
1468            metrics: metrics(9.0, 7.0),
1469        };
1470        assert_eq!(
1471            coordinator.apply_ready(&wrong).unwrap(),
1472            DeferredMeasurementApply::IgnoredStale
1473        );
1474        let invalid = MeasurementReady {
1475            environment_epoch: 4,
1476            metrics: MeasurementMetrics::from_size(MeasuredSize::new(f32::NAN, 1.0)),
1477            ..wrong.clone()
1478        };
1479        assert_eq!(
1480            coordinator.apply_ready(&invalid),
1481            Err(MeasurementError::InvalidMetrics { key })
1482        );
1483        let ready = MeasurementReady {
1484            environment_epoch: 4,
1485            metrics: metrics(9.0, 7.0),
1486            ..wrong
1487        };
1488        assert_eq!(
1489            coordinator.apply_ready(&ready).unwrap(),
1490            DeferredMeasurementApply::Applied {
1491                invalidated_nodes: vec![node(1)]
1492            }
1493        );
1494        assert_eq!(
1495            coordinator.apply_ready(&ready).unwrap(),
1496            DeferredMeasurementApply::IgnoredStale
1497        );
1498    }
1499
1500    #[test]
1501    fn policies_errors_and_stale_batches_are_explicit() {
1502        let mut coordinator = MeasurementCoordinator::default();
1503        coordinator.set_environment(1);
1504        let mut invalid_payload = spec(MeasurementKind::NativeControl, PendingMeasurePolicy::Block);
1505        invalid_payload.payload = MeasurementPayload::NativeControl(NativeControlMeasurePayload {
1506            control_type: 1,
1507            version: 0,
1508            state: Vec::new(),
1509        });
1510        assert_eq!(
1511            coordinator.set_spec(node(1), element(), Some(invalid_payload)),
1512            Err(MeasurementError::InvalidPayload {
1513                node: node(1),
1514                error: MeasurementPayloadError::InvalidPayloadVersion,
1515            })
1516        );
1517        assert_eq!(
1518            coordinator.set_spec(
1519                node(1),
1520                element(),
1521                Some(spec(
1522                    MeasurementKind::NativeControl,
1523                    PendingMeasurePolicy::Placeholder(MeasuredSize::new(-1.0, 0.0)),
1524                )),
1525            ),
1526            Err(MeasurementError::InvalidPlaceholder { node: node(1) })
1527        );
1528
1529        coordinator.begin_pass();
1530        coordinator.measure(node(1), constraints(10.0));
1531        assert_eq!(
1532            coordinator.finish_pass(),
1533            Err(MeasurementError::MissingSpec { node: node(1) })
1534        );
1535
1536        coordinator
1537            .set_spec(
1538                node(1),
1539                element(),
1540                Some(spec(
1541                    MeasurementKind::EmbeddedSurface,
1542                    PendingMeasurePolicy::RetainPrevious,
1543                )),
1544            )
1545            .unwrap();
1546        coordinator.begin_pass();
1547        assert_eq!(
1548            coordinator.measure(node(1), constraints(10.0)),
1549            LayoutSize::default()
1550        );
1551        let request = coordinator.finish_pass().unwrap().requests.remove(0);
1552        let stale_key = MeasurementKey::new(999).expect("stale");
1553        let apply = coordinator
1554            .apply_batch(&[
1555                MeasurementResponse::Ready {
1556                    key: stale_key,
1557                    environment_epoch: 1,
1558                    metrics: metrics(1.0, 1.0),
1559                },
1560                MeasurementResponse::Ready {
1561                    key: request.key,
1562                    environment_epoch: 2,
1563                    metrics: metrics(1.0, 1.0),
1564                },
1565            ])
1566            .unwrap();
1567        assert_eq!(apply.stale(), 2);
1568
1569        assert_eq!(
1570            coordinator.apply_batch(&[MeasurementResponse::Ready {
1571                key: request.key,
1572                environment_epoch: 1,
1573                metrics: MeasurementMetrics::from_size(MeasuredSize::new(-1.0, 1.0)),
1574            }]),
1575            Err(MeasurementError::InvalidMetrics { key: request.key })
1576        );
1577        assert!(coordinator.outstanding.contains_key(&request.key));
1578
1579        coordinator
1580            .apply_batch(&[MeasurementResponse::Unsupported {
1581                key: request.key,
1582                environment_epoch: 1,
1583                reason: UnsupportedMeasurementReason::Element,
1584            }])
1585            .unwrap();
1586        coordinator.begin_pass();
1587        coordinator.measure(node(1), constraints(10.0));
1588        assert_eq!(
1589            coordinator.finish_pass(),
1590            Err(MeasurementError::Unsupported {
1591                node: node(1),
1592                reason: UnsupportedMeasurementReason::Element,
1593            })
1594        );
1595        assert!(coordinator.set_spec(node(1), element(), None).unwrap());
1596        assert!(!coordinator.set_spec(node(1), element(), None).unwrap());
1597        coordinator.remove_node(node(1));
1598    }
1599
1600    #[test]
1601    fn duplicate_pending_ids_are_transactionally_rejected() {
1602        let mut coordinator = MeasurementCoordinator::default();
1603        coordinator.set_environment(1);
1604        for value in 1..=2 {
1605            let mut value_spec = spec(
1606                MeasurementKind::Custom { version: 1 },
1607                PendingMeasurePolicy::Block,
1608            );
1609            value_spec.content_hash = value;
1610            coordinator
1611                .set_spec(node(value), element(), Some(value_spec))
1612                .unwrap();
1613        }
1614        coordinator.begin_pass();
1615        coordinator.measure(node(1), constraints(10.0));
1616        coordinator.measure(node(2), constraints(10.0));
1617        let requests = coordinator.finish_pass().unwrap().requests;
1618        let request_id = MeasurementRequestId::new(7).expect("request");
1619        let responses = requests
1620            .iter()
1621            .map(|request| MeasurementResponse::Pending {
1622                key: request.key,
1623                environment_epoch: 1,
1624                request_id,
1625                provisional: None,
1626            })
1627            .collect::<Vec<_>>();
1628        assert_eq!(
1629            coordinator.apply_batch(&responses),
1630            Err(MeasurementError::DuplicateRequestId { request_id })
1631        );
1632        assert!(coordinator.cache.is_empty());
1633        assert_eq!(coordinator.outstanding.len(), 2);
1634    }
1635
1636    #[test]
1637    fn batches_validate_before_commit_and_preserve_response_order() {
1638        let mut coordinator = MeasurementCoordinator::default();
1639        coordinator.set_environment(1);
1640        coordinator
1641            .set_spec(
1642                node(1),
1643                element(),
1644                Some(spec(
1645                    MeasurementKind::Custom { version: 1 },
1646                    PendingMeasurePolicy::Block,
1647                )),
1648            )
1649            .unwrap();
1650        coordinator.begin_pass();
1651        coordinator.measure(node(1), constraints(10.0));
1652        coordinator.measure(node(1), constraints(20.0));
1653        let requests = coordinator.finish_pass().unwrap().requests;
1654        let ready = |key, width| MeasurementResponse::Ready {
1655            key,
1656            environment_epoch: 1,
1657            metrics: metrics(width, 1.0),
1658        };
1659        let first = ready(requests[0].key, 10.0);
1660        let invalid = ready(requests[1].key, -1.0);
1661        assert!(coordinator.apply_batch(&[first.clone(), invalid]).is_err());
1662        assert_eq!(coordinator.outstanding.len(), 2);
1663        assert!(coordinator.cache.is_empty());
1664        assert!(coordinator.last_ready(node(1)).is_none());
1665
1666        let stale_epoch = MeasurementResponse::Ready {
1667            key: requests[0].key,
1668            environment_epoch: 0,
1669            metrics: metrics(-1.0, 1.0),
1670        };
1671        let applied = coordinator
1672            .apply_batch(&[
1673                stale_epoch,
1674                first,
1675                ready(requests[0].key, -1.0),
1676                ready(requests[1].key, 20.0),
1677            ])
1678            .unwrap();
1679        assert_eq!(applied.applied(), 2);
1680        assert_eq!(applied.stale(), 2);
1681        assert_eq!(applied.invalidated_nodes(), &[node(1)]);
1682        assert_eq!(coordinator.last_ready(node(1)), Some(&metrics(20.0, 1.0)));
1683    }
1684
1685    #[test]
1686    fn retained_previous_metrics_and_key_exhaustion_are_covered() {
1687        let mut coordinator = MeasurementCoordinator::default();
1688        coordinator.set_environment(1);
1689        coordinator
1690            .set_spec(
1691                node(1),
1692                element(),
1693                Some(spec(
1694                    MeasurementKind::Text,
1695                    PendingMeasurePolicy::RetainPrevious,
1696                )),
1697            )
1698            .unwrap();
1699        coordinator.begin_pass();
1700        coordinator.measure(node(1), constraints(10.0));
1701        let request = coordinator.finish_pass().unwrap().requests.remove(0);
1702        coordinator
1703            .apply_batch(&[MeasurementResponse::Ready {
1704                key: request.key,
1705                environment_epoch: 1,
1706                metrics: metrics(5.0, 4.0),
1707            }])
1708            .unwrap();
1709
1710        let mut changed = spec(MeasurementKind::Text, PendingMeasurePolicy::RetainPrevious);
1711        changed.content_hash = 99;
1712        coordinator
1713            .set_spec(node(1), element(), Some(changed))
1714            .unwrap();
1715        coordinator.begin_pass();
1716        assert_eq!(
1717            coordinator.measure(node(1), constraints(10.0)),
1718            LayoutSize::new(5.0, 4.0)
1719        );
1720        assert!(coordinator.finish_pass().unwrap().provisional);
1721
1722        let mut exhausted = MeasurementCoordinator::default();
1723        exhausted.set_environment(1);
1724        exhausted.next_key = 0;
1725        exhausted
1726            .set_spec(
1727                node(1),
1728                element(),
1729                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1730            )
1731            .unwrap();
1732        exhausted.begin_pass();
1733        exhausted.measure(node(1), constraints(10.0));
1734        assert_eq!(exhausted.finish_pass(), Err(MeasurementError::KeyExhausted));
1735    }
1736
1737    #[test]
1738    fn defensive_stale_entries_and_outstanding_cleanup_are_covered() {
1739        assert_eq!(
1740            AvailableSpaceKey::from(AvailableSpace::MinContent),
1741            AvailableSpaceKey::MinContent
1742        );
1743
1744        fn pending_coordinator() -> (MeasurementCoordinator, MeasurementReady, CacheKey) {
1745            let mut coordinator = MeasurementCoordinator::default();
1746            coordinator.set_environment(1);
1747            coordinator
1748                .set_spec(
1749                    node(1),
1750                    element(),
1751                    Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1752                )
1753                .unwrap();
1754            coordinator.begin_pass();
1755            coordinator.measure(node(1), constraints(10.0));
1756            let key = coordinator.finish_pass().unwrap().requests[0].key;
1757            let request_id = MeasurementRequestId::new(21).expect("request");
1758            coordinator
1759                .apply_batch(&[MeasurementResponse::Pending {
1760                    key,
1761                    environment_epoch: 1,
1762                    request_id,
1763                    provisional: None,
1764                }])
1765                .unwrap();
1766            let cache_key = coordinator
1767                .pending
1768                .get(&request_id)
1769                .expect("pending")
1770                .cache_key
1771                .clone();
1772            (
1773                coordinator,
1774                MeasurementReady {
1775                    key,
1776                    request_id,
1777                    environment_epoch: 1,
1778                    metrics: metrics(2.0, 2.0),
1779                },
1780                cache_key,
1781            )
1782        }
1783
1784        let (mut missing_cache, ready, cache_key) = pending_coordinator();
1785        missing_cache.cache.remove(&cache_key);
1786        assert_eq!(
1787            missing_cache.apply_ready(&ready).unwrap(),
1788            DeferredMeasurementApply::IgnoredStale
1789        );
1790
1791        let (mut wrong_state, ready, cache_key) = pending_coordinator();
1792        wrong_state.cache.get_mut(&cache_key).expect("cache").state =
1793            CachedState::Ready(metrics(1.0, 1.0));
1794        assert_eq!(
1795            wrong_state.apply_ready(&ready).unwrap(),
1796            DeferredMeasurementApply::IgnoredStale
1797        );
1798
1799        let (mut no_consumers, _, _) = pending_coordinator();
1800        no_consumers.set_spec(node(1), element(), None).unwrap();
1801        assert_eq!(no_consumers.pending_count(), 0);
1802        assert!(no_consumers.cache.is_empty());
1803        assert!(no_consumers.pending.is_empty());
1804        assert!(no_consumers.consumer_keys.is_empty());
1805
1806        let mut outstanding = MeasurementCoordinator::default();
1807        outstanding.set_environment(1);
1808        for value in 1..=2 {
1809            outstanding
1810                .set_spec(
1811                    node(value),
1812                    element(),
1813                    Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1814                )
1815                .unwrap();
1816        }
1817        outstanding.begin_pass();
1818        outstanding.measure(node(1), constraints(10.0));
1819        outstanding.measure(node(2), constraints(10.0));
1820        assert_eq!(outstanding.outstanding.len(), 1);
1821        outstanding.set_spec(node(1), element(), None).unwrap();
1822        assert_eq!(outstanding.outstanding.len(), 1);
1823        outstanding.set_spec(node(2), element(), None).unwrap();
1824        assert!(outstanding.outstanding.is_empty());
1825        assert!(outstanding.outstanding_by_cache.is_empty());
1826        assert!(outstanding.consumer_keys.is_empty());
1827
1828        let mut invalid_pending = MeasurementCoordinator::default();
1829        invalid_pending.set_environment(1);
1830        invalid_pending
1831            .set_spec(
1832                node(1),
1833                element(),
1834                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1835            )
1836            .unwrap();
1837        invalid_pending.begin_pass();
1838        invalid_pending.measure(node(1), constraints(10.0));
1839        let key = invalid_pending.finish_pass().unwrap().requests[0].key;
1840        assert_eq!(
1841            invalid_pending.apply_batch(&[MeasurementResponse::Pending {
1842                key,
1843                environment_epoch: 1,
1844                request_id: MeasurementRequestId::new(22).expect("request"),
1845                provisional: Some(MeasurementMetrics::from_size(MeasuredSize::new(
1846                    f32::NAN,
1847                    1.0,
1848                ))),
1849            }]),
1850            Err(MeasurementError::InvalidMetrics { key })
1851        );
1852    }
1853
1854    #[test]
1855    fn unused_ready_cache_entries_are_reclaimed_without_breaking_shared_entries() {
1856        let mut coordinator = MeasurementCoordinator::default();
1857        coordinator.set_environment(1);
1858        for value in 1..=2 {
1859            coordinator
1860                .set_spec(
1861                    node(value),
1862                    element(),
1863                    Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1864                )
1865                .unwrap();
1866        }
1867
1868        coordinator.begin_pass();
1869        coordinator.measure(node(1), constraints(10.0));
1870        coordinator.measure(node(2), constraints(10.0));
1871        let request = coordinator.finish_pass().unwrap().requests.remove(0);
1872        coordinator
1873            .apply_batch(&[MeasurementResponse::Ready {
1874                key: request.key,
1875                environment_epoch: 1,
1876                metrics: metrics(5.0, 4.0),
1877            }])
1878            .unwrap();
1879        assert_eq!(coordinator.cache.len(), 1);
1880
1881        coordinator
1882            .set_spec(
1883                node(3),
1884                element(),
1885                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1886            )
1887            .unwrap();
1888        coordinator.begin_pass();
1889        assert_eq!(
1890            coordinator.measure(node(3), constraints(10.0)),
1891            LayoutSize::new(5.0, 4.0)
1892        );
1893        assert!(coordinator.finish_pass().unwrap().requests.is_empty());
1894
1895        coordinator.remove_node(node(1));
1896        assert_eq!(coordinator.cache.len(), 1);
1897        assert!(!coordinator.consumer_keys.contains_key(&node(1)));
1898
1899        coordinator.remove_node(node(2));
1900        assert_eq!(coordinator.cache.len(), 1);
1901        coordinator.remove_node(node(3));
1902        assert!(coordinator.cache.is_empty());
1903        assert!(coordinator.consumer_keys.is_empty());
1904    }
1905
1906    #[test]
1907    fn removing_last_pending_consumer_makes_deferred_completion_stale() {
1908        let mut coordinator = MeasurementCoordinator::default();
1909        coordinator.set_environment(1);
1910        coordinator
1911            .set_spec(
1912                node(1),
1913                element(),
1914                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1915            )
1916            .unwrap();
1917        coordinator.begin_pass();
1918        coordinator.measure(node(1), constraints(10.0));
1919        let key = coordinator.finish_pass().unwrap().requests[0].key;
1920        let request_id = MeasurementRequestId::new(30).expect("request");
1921        coordinator
1922            .apply_batch(&[MeasurementResponse::Pending {
1923                key,
1924                environment_epoch: 1,
1925                request_id,
1926                provisional: None,
1927            }])
1928            .unwrap();
1929
1930        coordinator.remove_node(node(1));
1931        assert!(coordinator.pending.is_empty());
1932        assert!(coordinator.cache.is_empty());
1933        assert_eq!(
1934            coordinator
1935                .apply_ready(&MeasurementReady {
1936                    key,
1937                    request_id,
1938                    environment_epoch: 1,
1939                    metrics: metrics(5.0, 4.0),
1940                })
1941                .unwrap(),
1942            DeferredMeasurementApply::IgnoredStale
1943        );
1944    }
1945
1946    #[test]
1947    fn prepared_objects_follow_ready_pending_and_unsupported_cache_entries() {
1948        for response_kind in 0..4 {
1949            let mut coordinator = MeasurementCoordinator::default();
1950            coordinator.set_environment(1);
1951            coordinator
1952                .set_spec(
1953                    node(1),
1954                    element(),
1955                    Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
1956                )
1957                .unwrap();
1958            coordinator.begin_pass();
1959            coordinator.measure(node(1), constraints(100.0));
1960            let request = coordinator.finish_pass().unwrap().requests.remove(0);
1961            let response = match response_kind {
1962                0 => MeasurementResponse::Ready {
1963                    key: request.key,
1964                    environment_epoch: 1,
1965                    metrics: metrics(20.0, 10.0),
1966                },
1967                1 | 2 => MeasurementResponse::Pending {
1968                    key: request.key,
1969                    environment_epoch: 1,
1970                    request_id: MeasurementRequestId::new(1).unwrap(),
1971                    provisional: (response_kind == 1).then(|| metrics(20.0, 10.0)),
1972                },
1973                _ => MeasurementResponse::Unsupported {
1974                    key: request.key,
1975                    environment_epoch: 1,
1976                    reason: UnsupportedMeasurementReason::Element,
1977                },
1978            };
1979            coordinator.apply_batch(&[response]).unwrap();
1980            assert!(coordinator.selected(node(999), request.key).is_none());
1981            let (revision, retained) = coordinator.retained_content();
1982            let retained = retained.collect::<Vec<_>>();
1983            assert_eq!(!retained.is_empty(), response_kind < 2);
1984            assert!(
1985                retained
1986                    .iter()
1987                    .all(|id| *id == PreparedContentId::new(3).unwrap())
1988            );
1989            assert_eq!(
1990                coordinator.selected(node(1), request.key).is_some(),
1991                response_kind == 0
1992            );
1993            coordinator.remove_node(node(1));
1994            let (removed_revision, retained) = coordinator.retained_content();
1995            assert!(removed_revision > revision);
1996            assert_eq!(retained.count(), 0);
1997        }
1998    }
1999
2000    #[test]
2001    fn paragraph_measurement_rejects_missing_and_mismatched_inline_subtrees() {
2002        let mut coordinator = MeasurementCoordinator::default();
2003        let attachment = crate::InlineAttachmentInput {
2004            truncation: false,
2005            label: None,
2006            node: node(2),
2007            range: whisker_protocol::TextByteRange { start: 0, end: 3 },
2008            alignment: whisker_protocol::InlineAlignment::Baseline,
2009        };
2010        coordinator
2011            .set_spec(
2012                node(1),
2013                element(),
2014                Some(spec(MeasurementKind::Text, PendingMeasurePolicy::Block)),
2015            )
2016            .unwrap();
2017        coordinator.set_inline_attachments(node(1), &[attachment]);
2018        let other = MeasuredInlineChild {
2019            node: node(3),
2020            size: LayoutSize::new(10.0, 10.0),
2021            baseline: 8.0,
2022        };
2023        for children in [vec![], vec![other]] {
2024            coordinator.begin_pass();
2025            assert_eq!(
2026                coordinator
2027                    .measure_paragraph(node(1), constraints(100.0), &children)
2028                    .state,
2029                MeasurementState::Blocked
2030            );
2031            assert_eq!(
2032                coordinator.finish_pass(),
2033                Err(MeasurementError::MissingSpec { node: node(1) })
2034            );
2035        }
2036    }
2037}