1use std::{error::Error, fmt};
4
5use whisker_layout::LayoutSize;
6use whisker_protocol::{
7 MeasurementBatchError, MeasurementRequest, MeasurementResponse, NodeId, SurfaceId,
8 validate_measurement_batch,
9};
10
11use crate::{LayoutProgress, SurfaceEngine, SurfaceError};
12
13pub trait MeasurementProvider {
19 type Error;
21
22 fn measure_batch(
28 &mut self,
29 surface: SurfaceId,
30 requests: &[MeasurementRequest],
31 responses: &mut Vec<MeasurementResponse>,
32 ) -> Result<(), Self::Error>;
33 fn measures_synchronously(&self) -> bool {
36 false
37 }
38 fn retain_prepared_content(
40 &mut self,
41 _surface: SurfaceId,
42 _revision: u64,
43 _retained: &mut dyn Iterator<Item = whisker_protocol::PreparedContentId>,
44 ) {
45 }
46}
47
48#[derive(Clone, Copy, Debug, PartialEq, Eq)]
50pub struct LayoutOptions {
51 pub max_immediate_batches: usize,
53}
54
55impl Default for LayoutOptions {
56 fn default() -> Self {
57 Self {
58 max_immediate_batches: 32,
59 }
60 }
61}
62
63#[derive(Clone, Debug, PartialEq)]
65pub enum LayoutError<MeasurementError> {
66 Surface(SurfaceError),
68 Measurement(MeasurementError),
70 InvalidBatch(MeasurementBatchError),
72 BatchLimitExceeded {
74 limit: usize,
76 },
77}
78
79impl<MeasurementError: fmt::Debug> fmt::Display for LayoutError<MeasurementError> {
80 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
81 write!(formatter, "Whisker Host layout error: {self:?}")
82 }
83}
84
85impl<MeasurementError: Error + 'static> Error for LayoutError<MeasurementError> {
86 fn source(&self) -> Option<&(dyn Error + 'static)> {
87 match self {
88 Self::Surface(error) => Some(error),
89 Self::Measurement(error) => Some(error),
90 Self::InvalidBatch(_) | Self::BatchLimitExceeded { .. } => None,
91 }
92 }
93}
94
95impl<MeasurementError> From<SurfaceError> for LayoutError<MeasurementError> {
96 fn from(error: SurfaceError) -> Self {
97 Self::Surface(error)
98 }
99}
100
101impl SurfaceEngine {
102 pub fn drive_layout<Provider: MeasurementProvider>(
111 &mut self,
112 root: NodeId,
113 viewport: LayoutSize,
114 environment_epoch: u64,
115 provider: &mut Provider,
116 options: LayoutOptions,
117 ) -> Result<LayoutProgress, LayoutError<Provider::Error>> {
118 let mut batches = 0;
119 let surface = self.surface();
120 let synchronous = provider.measures_synchronously();
121 loop {
122 let mut failure = None;
123 let progress = if !synchronous {
124 self.compute_layout_with_measurements(root, viewport, environment_epoch)
125 } else {
126 let mut host = |request: &MeasurementRequest| {
127 if failure.is_some() {
128 return None;
129 }
130 let requests = std::slice::from_ref(request);
131 let mut responses = Vec::with_capacity(1);
132 if let Err(error) = provider.measure_batch(surface, requests, &mut responses) {
133 failure = Some(LayoutError::Measurement(error));
134 return None;
135 }
136 if let Err(error) = validate_measurement_batch(requests, &responses) {
137 failure = Some(LayoutError::InvalidBatch(error));
138 return None;
139 }
140 responses.pop()
141 };
142 self.compute_layout_using(root, viewport, environment_epoch, Some(&mut host))
143 };
144 if let Some(failure) = failure {
145 return Err(failure);
146 }
147 let progress = progress?;
148 if progress.requests().is_empty() {
149 self.synchronize_prepared_content(provider);
150 return Ok(progress);
151 }
152 if batches >= options.max_immediate_batches {
153 return Err(LayoutError::BatchLimitExceeded {
154 limit: options.max_immediate_batches,
155 });
156 }
157
158 let requests = progress.requests().to_vec();
159 let mut responses = Vec::with_capacity(requests.len());
160 provider
161 .measure_batch(self.surface(), &requests, &mut responses)
162 .map_err(LayoutError::Measurement)?;
163 validate_measurement_batch(&requests, &responses).map_err(LayoutError::InvalidBatch)?;
164 self.apply_measurement_responses(&responses)?;
165 batches += 1;
166 }
167 }
168}
169
170#[cfg(test)]
171mod tests {
172 use whisker_protocol::{
173 ApplyResult, ElementTypeId, MeasureFontFamily, MeasureFontStyle, MeasureLineHeight,
174 MeasureTextDirection, MeasureTextOverflow, MeasureTextWrap, MeasuredSize,
175 MeasurementMetrics, MeasurementPayload, MeasurementPayloadError, MeasurementRequestId,
176 MeasurementSpec, Operation, PendingMeasurePolicy, PreparedContentId,
177 ReplacedContentMeasurePayload, TextMeasurePayload, TextMeasureStyle,
178 };
179 use whisker_style::{ComputedLayoutStyle, SpecifiedStyle, StyleEnvironment, resolve_style};
180
181 use super::*;
182 use crate::{FrameSink, PlainTextInput, RecordingRenderer, SceneError};
183
184 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
185 enum TestHostError {
186 Failed,
187 }
188
189 impl fmt::Display for TestHostError {
190 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
191 formatter.write_str("test Host failed")
192 }
193 }
194
195 impl Error for TestHostError {}
196
197 #[derive(Clone, Copy)]
198 enum Reply {
199 Ready(MeasuredSize),
200 ReadyPreparedText,
201 InvalidMetrics,
202 Pending,
203 Missing,
204 Fail,
205 }
206
207 struct TestHost {
208 reply: Reply,
209 synchronous: bool,
210 calls: Vec<(SurfaceId, Vec<MeasurementRequest>)>,
211 }
212
213 impl TestHost {
214 fn new(reply: Reply) -> Self {
215 Self {
216 reply,
217 synchronous: false,
218 calls: Vec::new(),
219 }
220 }
221
222 fn synchronous(reply: Reply) -> Self {
223 Self {
224 synchronous: true,
225 ..Self::new(reply)
226 }
227 }
228 }
229
230 impl MeasurementProvider for TestHost {
231 type Error = TestHostError;
232
233 fn measures_synchronously(&self) -> bool {
234 self.synchronous
235 }
236
237 fn measure_batch(
238 &mut self,
239 surface: SurfaceId,
240 requests: &[MeasurementRequest],
241 responses: &mut Vec<MeasurementResponse>,
242 ) -> Result<(), Self::Error> {
243 assert!(responses.is_empty());
244 self.calls.push((surface, requests.to_vec()));
245 match self.reply {
246 Reply::Ready(size) => {
247 responses.extend(requests.iter().map(|request| MeasurementResponse::Ready {
248 key: request.key,
249 environment_epoch: request.environment_epoch,
250 metrics: MeasurementMetrics::from_size(size),
251 }))
252 }
253 Reply::ReadyPreparedText => responses.extend(requests.iter().map(|request| {
254 let MeasurementPayload::Text(payload) = &request.payload else {
255 panic!("plain-text Host received a non-text request");
256 };
257 let width = payload.text.chars().count() as f32 * 9.0;
258 MeasurementResponse::Ready {
259 key: request.key,
260 environment_epoch: request.environment_epoch,
261 metrics: MeasurementMetrics {
262 paragraph: None,
263 inline_placements: Vec::new(),
264 size: MeasuredSize::new(width, 21.0),
265 first_baseline: Some(15.0),
266 last_baseline: Some(15.0),
267 overflow: None,
268 prepared_content: Some(
269 PreparedContentId::new(request.key.get())
270 .expect("measurement keys are non-zero"),
271 ),
272 },
273 }
274 })),
275 Reply::InvalidMetrics => {
276 responses.extend(requests.iter().map(|request| MeasurementResponse::Ready {
277 key: request.key,
278 environment_epoch: request.environment_epoch,
279 metrics: MeasurementMetrics::from_size(MeasuredSize::new(-1.0, 0.0)),
280 }))
281 }
282 Reply::Pending => responses.extend(requests.iter().map(|request| {
283 MeasurementResponse::Pending {
284 key: request.key,
285 environment_epoch: request.environment_epoch,
286 request_id: MeasurementRequestId::new(request.key.get())
287 .expect("non-zero request key"),
288 provisional: None,
289 }
290 })),
291 Reply::Missing => {}
292 Reply::Fail => return Err(TestHostError::Failed),
293 }
294 Ok(())
295 }
296 }
297
298 struct BatchedHost(TestHost);
300
301 impl MeasurementProvider for BatchedHost {
302 type Error = TestHostError;
303
304 fn measure_batch(
305 &mut self,
306 surface: SurfaceId,
307 requests: &[MeasurementRequest],
308 responses: &mut Vec<MeasurementResponse>,
309 ) -> Result<(), Self::Error> {
310 self.0.measure_batch(surface, requests, responses)
311 }
312 }
313
314 fn id<T>(constructor: impl FnOnce(u64) -> Option<T>) -> T {
315 constructor(1).expect("non-zero test id")
316 }
317
318 fn text_spec() -> MeasurementSpec {
319 MeasurementSpec {
320 content_hash: 1,
321 style_hash: 2,
322 payload: MeasurementPayload::Text(TextMeasurePayload {
323 runs: Vec::new(),
324 attachments: Vec::new(),
325 text: "measure me".into(),
326 style: TextMeasureStyle {
327 font_families: vec![MeasureFontFamily::Named("Inter".into())],
328 font_size: 16.0,
329 font_weight: 500,
330 font_style: MeasureFontStyle::Normal,
331 line_height: MeasureLineHeight::LogicalPixels(20.0),
332 letter_spacing: 0.5,
333 ..TextMeasureStyle::default()
334 },
335 locale: Some("en-US".into()),
336 direction: MeasureTextDirection::LeftToRight,
337 alignment: whisker_protocol::MeasureTextAlignment::Start,
338 indent: Default::default(),
339 wrap: MeasureTextWrap::Wrap,
340 word_break: Default::default(),
341 max_lines: Some(2),
342 overflow: MeasureTextOverflow::Ellipsis,
343 }),
344 pending_policy: PendingMeasurePolicy::Block,
345 }
346 }
347
348 fn surface_with_text() -> (SurfaceEngine, NodeId) {
349 let mut surface = SurfaceEngine::new(id(SurfaceId::new));
350 let root = surface
351 .create_node(
352 ElementTypeId::new(1).expect("non-zero element type"),
353 ComputedLayoutStyle::default(),
354 )
355 .expect("create text node");
356 surface
357 .set_measurement(root, Some(text_spec()))
358 .expect("register text measurement");
359 (surface, root)
360 }
361
362 #[test]
363 fn synchronous_host_completes_text_layout_before_returning() {
364 let (mut surface, root) = surface_with_text();
365 let mut host = TestHost::new(Reply::Ready(MeasuredSize::new(48.0, 20.0)));
366 let progress = surface
367 .drive_layout(
368 root,
369 LayoutSize::new(100.0, 100.0),
370 7,
371 &mut host,
372 LayoutOptions::default(),
373 )
374 .expect("synchronous layout");
375
376 assert!(progress.has_layout());
377 assert!(progress.requests().is_empty());
378 assert!(!host.calls.is_empty());
379 assert!(host.calls.iter().all(|(id, requests)| {
380 *id == surface.surface()
381 && requests.iter().all(|request| {
382 request.payload.kind() == whisker_protocol::MeasurementKind::Text
383 })
384 }));
385 assert_eq!(
386 surface.last_measurement(root).map(|metrics| metrics.size),
387 Some(MeasuredSize::new(48.0, 20.0))
388 );
389 }
390
391 #[test]
392 fn synchronous_host_answers_each_request_inside_one_layout_pass() {
393 let (mut surface, root) = surface_with_text();
394 let mut host = TestHost::synchronous(Reply::Ready(MeasuredSize::new(48.0, 20.0)));
395 let progress = surface
396 .drive_layout(
397 root,
398 LayoutSize::new(100.0, 100.0),
399 7,
400 &mut host,
401 LayoutOptions {
402 max_immediate_batches: 0,
403 },
404 )
405 .expect("synchronous layout needs no batch round");
406
407 assert!(progress.has_layout());
408 assert!(progress.requests().is_empty());
409 assert!(!host.calls.is_empty());
410 assert!(host.calls.iter().all(|(_, requests)| requests.len() == 1));
411 assert_eq!(
412 surface.last_measurement(root).map(|metrics| metrics.size),
413 Some(MeasuredSize::new(48.0, 20.0))
414 );
415 }
416
417 #[test]
418 fn synchronous_host_pending_and_failure_match_batched_outcomes() {
419 let (mut surface, root) = surface_with_text();
420 let mut pending = TestHost::synchronous(Reply::Pending);
421 let progress = surface
422 .drive_layout(
423 root,
424 LayoutSize::new(100.0, 100.0),
425 1,
426 &mut pending,
427 LayoutOptions::default(),
428 )
429 .expect("pending layout is valid");
430 assert!(matches!(
431 progress,
432 LayoutProgress::Blocked { requests, pending: count }
433 if requests.is_empty() && count == pending.calls.len()
434 ));
435
436 let (mut surface, root) = surface_with_text();
437 let mut failed = TestHost::synchronous(Reply::Fail);
438 let error = surface
439 .drive_layout(
440 root,
441 LayoutSize::new(100.0, 100.0),
442 1,
443 &mut failed,
444 LayoutOptions::default(),
445 )
446 .expect_err("Host failure");
447 assert_eq!(error, LayoutError::Measurement(TestHostError::Failed));
448 assert_eq!(failed.calls.len(), 1);
449
450 let (mut surface, root) = surface_with_text();
451 let mut missing = TestHost::synchronous(Reply::Missing);
452 let error = surface
453 .drive_layout(
454 root,
455 LayoutSize::new(100.0, 100.0),
456 1,
457 &mut missing,
458 LayoutOptions::default(),
459 )
460 .expect_err("missing response");
461 assert_eq!(
462 error,
463 LayoutError::InvalidBatch(MeasurementBatchError::MissingResponseKey {
464 key: missing.calls[0].1[0].key,
465 })
466 );
467 }
468
469 #[test]
470 fn plain_text_reaches_final_snapshot_and_incremental_frame_with_mock_host() {
471 let resolved = resolve_style(&SpecifiedStyle::new(), None, StyleEnvironment::default())
472 .expect("default computed style");
473 let mut surface = SurfaceEngine::new(id(SurfaceId::new));
474 let root = surface
475 .create_node(
476 ElementTypeId::new(1).expect("text element type"),
477 resolved.computed().layout().clone(),
478 )
479 .expect("create text node");
480 let first_input = PlainTextInput::new("hello");
481 let missing = NodeId::new(99).expect("missing node");
482 assert_eq!(
483 surface.set_plain_text(missing, &first_input, resolved.computed(),),
484 Err(SurfaceError::Scene(SceneError::UnknownNode {
485 node: missing
486 }))
487 );
488 let mut invalid = first_input.clone();
489 invalid.locale = Some(String::new());
490 assert_eq!(
491 surface.set_plain_text(root, &invalid, resolved.computed()),
492 Err(SurfaceError::Measurement(
493 crate::MeasurementError::InvalidPayload {
494 node: root,
495 error: MeasurementPayloadError::InvalidLocale,
496 }
497 ))
498 );
499 assert!(
500 surface
501 .set_plain_text(root, &first_input, resolved.computed())
502 .expect("lower first text")
503 );
504 assert!(
505 !surface
506 .set_plain_text(root, &first_input, resolved.computed())
507 .expect("equal unmeasured text is idle")
508 );
509
510 let mut host = TestHost::new(Reply::ReadyPreparedText);
511 let progress = surface
512 .drive_layout(
513 root,
514 LayoutSize::new(200.0, 100.0),
515 3,
516 &mut host,
517 LayoutOptions::default(),
518 )
519 .expect("measure and finalize first text layout");
520 assert!(progress.has_layout());
521 let first_measure_batches = host.calls.len();
522 assert!(first_measure_batches > 0);
523 let first_prepared = surface
524 .last_measurement(root)
525 .and_then(|metrics| metrics.prepared_content)
526 .expect("final text measurement keeps prepared content");
527
528 let first_packet = surface
529 .prepare_frame(3)
530 .expect("prepare snapshot")
531 .expect("snapshot has text work")
532 .clone();
533 assert_eq!(
534 surface.set_plain_text(root, &first_input, resolved.computed()),
535 Err(SurfaceError::Scene(SceneError::FramePending))
536 );
537 assert!(matches!(
538 first_packet
539 .operations
540 .iter()
541 .find(|operation| matches!(operation, Operation::SetLayout { .. })),
542 Some(Operation::SetLayout { node, geometry })
543 if *node == root && geometry.border_box == whisker_protocol::LayoutRect {
544 x: 0.0,
545 y: 0.0,
546 width: 200.0,
547 height: 21.0,
548 }
549 ));
550 assert!(matches!(
551 first_packet
552 .operations
553 .iter()
554 .find(|operation| matches!(operation, Operation::SetText { .. })),
555 Some(Operation::SetText { node, content })
556 if *node == root
557 && content.payload.text == "hello"
558 && content.prepared_content == Some(first_prepared)
559 ));
560
561 let mut renderer = RecordingRenderer::new(surface.surface());
562 assert_eq!(
563 renderer.present(&first_packet),
564 Ok(ApplyResult::Accepted { revision: 1 })
565 );
566 surface.accept_pending(1).expect("accept snapshot");
567 assert_eq!(renderer.projection().node_count(), 1);
568
569 let second_input = PlainTextInput::new("hello world");
570 assert!(
571 surface
572 .set_plain_text(root, &second_input, resolved.computed())
573 .expect("lower changed text")
574 );
575 surface
576 .drive_layout(
577 root,
578 LayoutSize::new(200.0, 100.0),
579 3,
580 &mut host,
581 LayoutOptions::default(),
582 )
583 .expect("measure and finalize changed text layout");
584 let second_measure_batches = host.calls.len();
585 assert!(second_measure_batches > first_measure_batches);
586 let second_prepared = surface
587 .last_measurement(root)
588 .and_then(|metrics| metrics.prepared_content)
589 .expect("changed text keeps prepared content");
590 let delta = surface
591 .prepare_frame(3)
592 .expect("prepare delta")
593 .expect("changed text has work")
594 .clone();
595 assert!(matches!(
596 delta.operations.as_slice(),
597 [Operation::SetText { node: text_node, content }]
598 if *text_node == root
599 && content.payload.text == "hello world"
600 && content.prepared_content == Some(second_prepared)
601 ));
602 assert_eq!(
603 renderer.present(&delta),
604 Ok(ApplyResult::Accepted { revision: 2 })
605 );
606 surface.accept_pending(2).expect("accept delta");
607
608 assert!(
609 !surface
610 .set_plain_text(root, &second_input, resolved.computed())
611 .expect("equal text is idle")
612 );
613 surface
614 .drive_layout(
615 root,
616 LayoutSize::new(200.0, 100.0),
617 3,
618 &mut host,
619 LayoutOptions::default(),
620 )
621 .expect("equal text reuses retained layout");
622 assert_eq!(host.calls.len(), second_measure_batches);
623 assert_eq!(surface.prepare_frame(3).expect("idle prepare"), None);
624 }
625
626 #[test]
627 #[should_panic(expected = "plain-text Host received a non-text request")]
628 fn plain_text_test_host_rejects_non_text_requests() {
629 let mut surface = SurfaceEngine::new(id(SurfaceId::new));
630 let root = surface
631 .create_node(
632 ElementTypeId::new(1).expect("element type"),
633 ComputedLayoutStyle::default(),
634 )
635 .expect("create node");
636 surface
637 .set_measurement(
638 root,
639 Some(MeasurementSpec {
640 content_hash: 1,
641 style_hash: 1,
642 payload: MeasurementPayload::ReplacedContent(
643 ReplacedContentMeasurePayload::default(),
644 ),
645 pending_policy: PendingMeasurePolicy::Block,
646 }),
647 )
648 .expect("register replaced measurement");
649 let mut host = TestHost::new(Reply::ReadyPreparedText);
650 let _ = surface.drive_layout(
651 root,
652 LayoutSize::new(100.0, 100.0),
653 1,
654 &mut host,
655 LayoutOptions::default(),
656 );
657 }
658
659 #[test]
660 fn pending_host_returns_control_to_the_event_boundary() {
661 let (mut surface, root) = surface_with_text();
662 let mut host = BatchedHost(TestHost::new(Reply::Pending));
663 let progress = surface
664 .drive_layout(
665 root,
666 LayoutSize::new(100.0, 100.0),
667 1,
668 &mut host,
669 LayoutOptions::default(),
670 )
671 .expect("pending layout is valid");
672 assert_eq!(host.0.calls.len(), 1);
673 assert!(matches!(
674 progress,
675 LayoutProgress::Blocked { requests, pending }
676 if requests.is_empty() && pending == host.0.calls[0].1.len()
677 ));
678 }
679
680 #[test]
681 fn host_and_batch_failures_are_transactional_and_diagnostic() {
682 let (mut surface, root) = surface_with_text();
683 let mut failed = TestHost::new(Reply::Fail);
684 let error = surface
685 .drive_layout(
686 root,
687 LayoutSize::new(100.0, 100.0),
688 1,
689 &mut failed,
690 LayoutOptions::default(),
691 )
692 .expect_err("Host failure");
693 assert_eq!(error, LayoutError::Measurement(TestHostError::Failed));
694 assert!(error.source().is_some());
695 assert!(error.to_string().contains("Host"));
696 assert_eq!(TestHostError::Failed.to_string(), "test Host failed");
697
698 let mut missing = TestHost::new(Reply::Missing);
699 let error = surface
700 .drive_layout(
701 root,
702 LayoutSize::new(100.0, 100.0),
703 1,
704 &mut missing,
705 LayoutOptions::default(),
706 )
707 .expect_err("missing response");
708 assert_eq!(
709 error,
710 LayoutError::InvalidBatch(MeasurementBatchError::MissingResponseKey {
711 key: whisker_protocol::MeasurementKey::new(1).expect("first request key"),
712 })
713 );
714 assert!(error.source().is_none());
715
716 let mut invalid_metrics = TestHost::new(Reply::InvalidMetrics);
717 let error = surface
718 .drive_layout(
719 root,
720 LayoutSize::new(100.0, 100.0),
721 1,
722 &mut invalid_metrics,
723 LayoutOptions::default(),
724 )
725 .expect_err("invalid metrics");
726 assert_eq!(
727 error,
728 LayoutError::Surface(SurfaceError::Measurement(
729 crate::MeasurementError::InvalidMetrics {
730 key: whisker_protocol::MeasurementKey::new(1).expect("first request key"),
731 }
732 ))
733 );
734 }
735
736 #[test]
737 fn surface_failure_and_batch_limit_do_not_call_host() {
738 let mut empty = SurfaceEngine::new(id(SurfaceId::new));
739 let mut host = TestHost::new(Reply::Ready(MeasuredSize::default()));
740 let error = empty
741 .drive_layout(
742 id(NodeId::new),
743 LayoutSize::new(1.0, 1.0),
744 1,
745 &mut host,
746 LayoutOptions::default(),
747 )
748 .expect_err("unknown root");
749 assert_eq!(
750 error,
751 LayoutError::Surface(SurfaceError::Layout(
752 whisker_layout::LayoutError::UnknownNode(id(NodeId::new))
753 ))
754 );
755 assert!(error.source().is_some());
756
757 let (mut surface, root) = surface_with_text();
758 let error = surface
759 .drive_layout(
760 root,
761 LayoutSize::new(100.0, 100.0),
762 1,
763 &mut host,
764 LayoutOptions {
765 max_immediate_batches: 0,
766 },
767 )
768 .expect_err("zero batch guard");
769 assert_eq!(error, LayoutError::BatchLimitExceeded { limit: 0 });
770 assert!(error.source().is_none());
771 assert!(host.calls.is_empty());
772 }
773}