#[cfg(test)]
use std::cell::Cell as FlagCell;
use crate::compositor::animate::{AnimState, AnimationRuntime};
use crate::compositor::layout::Rect;
#[cfg(test)]
use crate::compositor::layout::cell::Cell;
use crate::compositor::layout::cell::CellBuffer;
use crate::compositor::scene::{DirtyRegions, NodeKind, Scene};
use crate::resource::{ResourceCategory, ResourceGovernor};
pub(crate) type SharedFrame = triomphe::Arc<CellBuffer>;
#[cfg(test)]
thread_local! {
static REJECT_FRAME_OWNER: FlagCell<bool> = const { FlagCell::new(false) };
}
#[cfg(test)]
fn frame_owner_rejected() -> bool {
REJECT_FRAME_OWNER.with(|site| site.replace(false))
}
#[cfg(not(test))]
fn frame_owner_rejected() -> bool {
false
}
pub struct Compositor {
width: u16,
height: u16,
last_output: Option<SharedFrame>,
last_output_background_offset: u16,
last_presented: Option<SharedFrame>,
last_presented_offset: u16,
pending_present_dirty: DirtyRegions,
last_focus_span: Option<FocusSpan>,
governor: ResourceGovernor,
}
pub(crate) struct PresentationCheckpoint {
last_presented: Option<SharedFrame>,
last_presented_offset: u16,
pending_present_dirty: DirtyRegions,
last_focus_span: Option<FocusSpan>,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct FocusSpan {
pub screen_row: u16,
pub buf_row: u16,
pub col_start: u16,
pub col_end: u16,
pub is_sticky: bool,
}
impl Compositor {
pub fn new(width: u16, height: u16) -> Self {
Self::with_governor(width, height, ResourceGovernor::new())
}
pub fn with_governor(width: u16, height: u16, governor: ResourceGovernor) -> Self {
Self {
width,
height,
last_output: None,
last_output_background_offset: 0,
last_presented: None,
last_presented_offset: 0,
pending_present_dirty: DirtyRegions::default(),
last_focus_span: None,
governor,
}
}
pub(crate) fn set_governor(&mut self, governor: ResourceGovernor) {
if self.governor.shares_budget_with(&governor) {
return;
}
self.last_output = None;
self.last_presented = None;
self.governor = governor;
self.pending_present_dirty.clear();
self.last_focus_span = None;
}
pub fn last_focus_span(&self) -> Option<FocusSpan> {
self.last_focus_span
}
pub fn set_last_focus_span(&mut self, span: Option<FocusSpan>) {
self.last_focus_span = span;
}
pub(crate) fn presentation_checkpoint(&self) -> PresentationCheckpoint {
PresentationCheckpoint {
last_presented: self.last_presented.clone(),
last_presented_offset: self.last_presented_offset,
pending_present_dirty: self.pending_present_dirty.clone(),
last_focus_span: self.last_focus_span,
}
}
pub(crate) fn restore_presentation(&mut self, checkpoint: PresentationCheckpoint) {
self.last_presented = checkpoint.last_presented;
self.last_presented_offset = checkpoint.last_presented_offset;
self.pending_present_dirty = checkpoint.pending_present_dirty;
self.last_focus_span = checkpoint.last_focus_span;
}
pub fn width(&self) -> u16 {
self.width
}
pub fn height(&self) -> u16 {
self.height
}
pub fn resize(&mut self, width: u16, height: u16) {
if width != self.width || height != self.height {
self.width = width;
self.height = height;
self.last_output = None;
self.last_presented = None;
self.pending_present_dirty.clear();
self.last_focus_span = None;
}
}
pub fn invalidate_cache(&mut self) {
self.last_output = None;
}
pub fn invalidate_presented(&mut self) {
self.last_presented = None;
self.last_focus_span = None;
}
pub fn composite(&mut self, scene: &Scene, anim_rt: &AnimationRuntime) -> Option<SharedFrame> {
self.composite_at(scene, anim_rt, 0)
}
pub fn composite_at(
&mut self,
scene: &Scene,
anim_rt: &AnimationRuntime,
viewport_offset: u16,
) -> Option<SharedFrame> {
let background_offset = if anim_rt
.animations
.iter()
.any(|anim| !matches!(anim.state(), AnimState::Waiting) && anim.background())
{
viewport_offset
} else {
0
};
let cache_valid = self
.last_output
.as_ref()
.map(|c| {
c.width == self.width
&& c.height == self.height
&& self.last_output_background_offset == background_offset
})
.unwrap_or(false);
if cache_valid
&& scene.invalidation.composite.is_empty()
&& let Some(cached) = self.last_output.as_ref()
{
self.pending_present_dirty.clear();
return Some(cached.clone());
}
self.pending_present_dirty.clear();
for rect in scene.invalidation.present.iter().copied() {
self.pending_present_dirty.add(rect);
}
if background_offset > 0 {
self.pending_present_dirty.add(Rect::new(
0,
background_offset,
self.width,
self.height.saturating_sub(background_offset),
));
}
let out = walk_at_governed(
scene,
anim_rt,
self.width,
self.height,
background_offset,
&self.governor,
);
if out.allocation_failed() {
return None;
}
if frame_owner_rejected() {
return None;
}
let out = SharedFrame::try_new(out).ok()?;
self.last_output_background_offset = background_offset;
self.last_output = Some(out.clone());
Some(out)
}
pub fn present_main<W: std::io::Write>(
&mut self,
out: &mut W,
frame: &SharedFrame,
viewport_offset: u16,
viewport_height: u16,
) -> std::io::Result<()> {
let can_diff = self
.last_presented
.as_ref()
.map(|p| {
p.width == frame.width
&& p.height == frame.height
&& self.last_presented_offset == viewport_offset
})
.unwrap_or(false);
if can_diff && let Some(prev) = self.last_presented.as_ref() {
let same_frame = SharedFrame::ptr_eq(prev, frame);
if !same_frame {
let dirty_scope: Option<&[Rect]> = if self.pending_present_dirty.is_empty() {
None
} else {
Some(self.pending_present_dirty.as_slice())
};
crate::compositor::present::render_diff(
out,
prev,
frame,
viewport_offset,
viewport_height,
dirty_scope,
)?;
}
} else {
crate::compositor::present::render_full(out, frame, viewport_offset, viewport_height)?;
self.last_focus_span = None;
}
self.last_presented = Some(frame.clone());
self.last_presented_offset = viewport_offset;
self.pending_present_dirty.clear();
Ok(())
}
}
pub fn walk_static(scene: &Scene, width: u16, height: u16) -> CellBuffer {
let empty = AnimationRuntime::empty();
walk_inner(
scene, &empty, width, height, 0, false,
)
}
pub(crate) fn walk_static_governed(
scene: &Scene,
width: u16,
height: u16,
governor: &ResourceGovernor,
) -> CellBuffer {
let empty = AnimationRuntime::empty();
walk_inner_with_governor(scene, &empty, width, height, 0, false, Some(governor))
}
pub(crate) fn walk_governed(
scene: &Scene,
anim_rt: &AnimationRuntime,
width: u16,
height: u16,
governor: &ResourceGovernor,
) -> CellBuffer {
walk_inner_with_governor(scene, anim_rt, width, height, 0, true, Some(governor))
}
pub fn walk(scene: &Scene, anim_rt: &AnimationRuntime, width: u16, height: u16) -> CellBuffer {
walk_at(scene, anim_rt, width, height, 0)
}
pub fn walk_at(
scene: &Scene,
anim_rt: &AnimationRuntime,
width: u16,
height: u16,
background_offset: u16,
) -> CellBuffer {
walk_inner(
scene,
anim_rt,
width,
height,
background_offset,
true,
)
}
fn walk_inner(
scene: &Scene,
anim_rt: &AnimationRuntime,
width: u16,
height: u16,
background_offset: u16,
include_anims: bool,
) -> CellBuffer {
walk_inner_with_governor(
scene,
anim_rt,
width,
height,
background_offset,
include_anims,
None,
)
}
fn walk_at_governed(
scene: &Scene,
anim_rt: &AnimationRuntime,
width: u16,
height: u16,
background_offset: u16,
governor: &ResourceGovernor,
) -> CellBuffer {
walk_inner_with_governor(
scene,
anim_rt,
width,
height,
background_offset,
true,
Some(governor),
)
}
fn walk_inner_with_governor(
scene: &Scene,
anim_rt: &AnimationRuntime,
width: u16,
height: u16,
background_offset: u16,
include_anims: bool,
governor: Option<&ResourceGovernor>,
) -> CellBuffer {
let transitioning_panels: std::collections::HashSet<crate::compositor::scene::NodeId> = anim_rt
.transition_animations
.iter()
.map(|t| t.target_node())
.collect();
let is_under_transitioning_panel = |node: &crate::compositor::scene::Node| -> bool {
if transitioning_panels.is_empty() {
return false;
}
let mut current = node.parent();
while let Some(parent_id) = current {
if transitioning_panels.contains(&parent_id) {
return true;
}
current = scene.get(parent_id).and_then(|p| p.parent());
}
false
};
let is_under_animation = |node: &crate::compositor::scene::Node| -> bool {
let mut current = node.parent();
while let Some(parent_id) = current {
let Some(parent) = scene.get(parent_id) else {
break;
};
if matches!(parent.kind(), NodeKind::Animation(_)) {
if !include_anims {
return true;
}
return parent.aml_id().is_some_and(|id| {
anim_rt
.animations
.iter()
.any(|animation| animation.id() == id)
});
}
current = parent.parent();
}
false
};
let allocation = match governor {
Some(governor) => {
CellBuffer::try_new_governed(width, height, governor, ResourceCategory::CompositorCells)
.map_err(|_| ())
}
None => CellBuffer::try_new(width, height).map_err(|_| ()),
};
let mut out = allocation.unwrap_or_else(|()| {
let mut fallback = CellBuffer::new(1, 1);
fallback.record_allocation_failure();
fallback
});
if out.allocation_failed() {
return out;
}
let mut phase_b: Vec<&crate::compositor::scene::Node> = Vec::new();
let mut phase_bp: Vec<&crate::compositor::scene::Node> = Vec::new();
let mut phase_d: Vec<&crate::compositor::scene::Node> = Vec::new();
for node in scene.iter_tree_order() {
if !node.visible() || node.buffer().is_none() {
continue;
}
match node.kind() {
NodeKind::Animation(_) => {}
NodeKind::LiveRegion(_) | NodeKind::Panel { .. } => phase_bp.push(node),
NodeKind::Overlay(data)
if !include_anims
&& matches!(
data.source,
crate::compositor::scene::OverlaySource::PageTransition
) => {}
NodeKind::Overlay(_) => phase_d.push(node),
_ => {
if !is_under_transitioning_panel(node) && !is_under_animation(node) {
phase_b.push(node);
}
}
}
}
if include_anims {
for anim in &anim_rt.animations {
if matches!(anim.state(), AnimState::Waiting) || !anim.background() {
continue;
}
let Some(node_id) = scene.find_by_aml_id(anim.id()) else {
continue;
};
let Some(src) = scene.buffer_of(node_id) else {
continue;
};
blit(src, &mut out, 0, background_offset);
}
}
for node in &phase_b {
blit_placed(node, &mut out);
}
for node in &phase_bp {
blit_placed(node, &mut out);
}
if include_anims {
for anim in &anim_rt.animations {
if matches!(anim.state(), AnimState::Waiting) || anim.background() {
continue;
}
let Some(node_id) = scene.find_by_aml_id(anim.id()) else {
continue;
};
let Some(node) = scene.get(node_id) else {
continue;
};
if !node.visible() {
continue;
}
let Some(src) = node.buffer() else { continue };
let rect = node.placement().rect;
let t = node.transform();
let tx = (rect.x as i32 + t.dx as i32).clamp(0, width as i32) as u16;
let ty = (rect.y as i32 + t.dy as i32).clamp(0, height as i32) as u16;
blit(src, &mut out, tx, ty);
}
}
if phase_d.len() > 1 {
phase_d.sort_by_key(|n| n.z_index());
}
for node in &phase_d {
blit_placed(node, &mut out);
}
out
}
fn blit_placed(node: &crate::compositor::scene::Node, out: &mut CellBuffer) {
let Some(src) = node.buffer() else { return };
let rect = node.placement().rect;
if rect.is_empty() {
return;
}
let t = node.transform();
let tx = (rect.x as i32 + t.dx as i32).clamp(0, out.width as i32) as u16;
let ty = (rect.y as i32 + t.dy as i32).clamp(0, out.height as i32) as u16;
blit(src, out, tx, ty);
}
fn blit(src: &CellBuffer, dst: &mut CellBuffer, dst_x: u16, dst_y: u16) {
let h = src.height.min(dst.height.saturating_sub(dst_y));
let w = src.width.min(dst.width.saturating_sub(dst_x));
for y in 0..h {
let Some(row) = src.row(y) else { continue };
for x in 0..w {
let Some(cell) = row.get(x as usize) else {
continue;
};
if cell.is_transparent() {
continue;
}
dst.set(dst_x + x, dst_y + y, cell.clone());
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::color::{NamedColor, ResolvedColor};
use crate::compositor::layout::cell::CellStyle;
#[test]
fn pending_present_dirty_union_is_allocation_free_and_reusable() {
let mut compositor = Compositor::new(20, 10);
compositor.pending_present_dirty.add(Rect::new(1, 2, 3, 2));
compositor.pending_present_dirty.add(Rect::new(10, 6, 2, 3));
assert_eq!(
compositor.pending_present_dirty.as_slice(),
&[Rect::new(1, 2, 11, 7)]
);
compositor.pending_present_dirty.clear();
assert!(compositor.pending_present_dirty.is_empty());
compositor.pending_present_dirty.add(Rect::new(4, 5, 1, 1));
assert_eq!(
compositor.pending_present_dirty.as_slice(),
&[Rect::new(4, 5, 1, 1)]
);
}
#[test]
fn blit_respects_transparency() {
let mut dst = CellBuffer::new(5, 1);
for x in 0..5 {
dst.put_char(x, 0, 'X', &CellStyle::default());
}
let mut src = CellBuffer::new(5, 1);
src.put_char(2, 0, 'O', &CellStyle::default());
blit(&src, &mut dst, 0, 0);
assert_eq!(
dst.get(0, 0).unwrap().ch,
'X',
"transparent should not overwrite"
);
assert_eq!(dst.get(1, 0).unwrap().ch, 'X');
assert_eq!(
dst.get(2, 0).unwrap().ch,
'O',
"non-transparent should overwrite"
);
assert_eq!(dst.get(3, 0).unwrap().ch, 'X');
assert_eq!(dst.get(4, 0).unwrap().ch, 'X');
}
#[test]
fn blit_clips_at_dst_bounds() {
let mut dst = CellBuffer::new(3, 1);
let mut src = CellBuffer::new(5, 1);
src.put_str(0, 0, "ABCDE", &CellStyle::default());
blit(&src, &mut dst, 1, 0);
assert_eq!(dst.get(0, 0).unwrap().ch, ' '); assert_eq!(dst.get(1, 0).unwrap().ch, 'A');
assert_eq!(dst.get(2, 0).unwrap().ch, 'B');
}
#[test]
fn blit_opaque_space_writes() {
let mut dst = CellBuffer::new(3, 1);
for x in 0..3 {
dst.put_char(x, 0, 'X', &CellStyle::default());
}
let mut src = CellBuffer::new(3, 1);
let bg_style = CellStyle {
bg: Some(ResolvedColor::Named(NamedColor::Blue)),
..Default::default()
};
src.put_char(1, 0, ' ', &bg_style);
blit(&src, &mut dst, 0, 0);
assert_eq!(dst.get(1, 0).unwrap().ch, ' ');
assert_eq!(
dst.get(1, 0).unwrap().style.bg,
Some(ResolvedColor::Named(NamedColor::Blue)),
"opaque space (space + bg) is not transparent and should overwrite",
);
}
#[test]
fn static_walk_excludes_animation_source_content() {
let src = r#"[page mode=screen cols=30 rows=6]
[box y=1 w=30 h=4 border=single]
[animate id="delayed" fps=12 autoplay=false]
[pre]SHOULD-NOT-LEAK[/pre]
[/animate]
[/box]
[/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _ = crate::compositor::layout::engine::layout_scene(
&mut scene,
30,
6,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let out = walk_static(&scene, 30, 6);
let mut rendered = String::new();
for y in 0..out.height {
for x in 0..out.width {
rendered.push(out.get(x, y).unwrap().ch);
}
}
assert!(
rendered.contains('┌'),
"static box chrome should remain visible"
);
assert!(
!rendered.contains("SHOULD-NOT-LEAK"),
"animation source content leaked into a static transition snapshot",
);
}
#[test]
fn compositor_resize_updates_dims() {
let mut c = Compositor::new(10, 5);
assert_eq!(c.width(), 10);
assert_eq!(c.height(), 5);
c.resize(20, 8);
assert_eq!(c.width(), 20);
assert_eq!(c.height(), 8);
}
fn simple_scene() -> (crate::compositor::scene::Scene, AnimationRuntime) {
let src = r#"[page mode=document][text]hello[/text][/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _lr = crate::compositor::layout::engine::layout_scene(
&mut scene,
40,
10,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
scene.invalidation.clear();
let anim_rt = AnimationRuntime::new(Vec::new());
(scene, anim_rt)
}
#[test]
fn governed_cache_tracks_unique_retained_frames_exactly() {
let (mut scene, anim_rt) = simple_scene();
let governor = ResourceGovernor::new();
let mut compositor = Compositor::with_governor(40, 10, governor.clone());
let frame_bytes = 40 * 10 * std::mem::size_of::<Cell>();
let first = compositor.composite(&scene, &anim_rt).unwrap();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes
);
compositor
.present_main(&mut Vec::new(), &first, 0, 10)
.unwrap();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes,
"output and presented aliases must be charged once",
);
scene
.invalidation
.mark_composite(crate::compositor::layout::Rect::new(0, 0, 1, 1));
let second = compositor.composite(&scene, &anim_rt).unwrap();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes * 2,
"old presented and new output are distinct retained buffers",
);
compositor
.present_main(&mut Vec::new(), &second, 0, 10)
.unwrap();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes * 2,
"an externally retained old frame must keep its own lease",
);
drop(first);
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes,
"the old frame releases its lease at its actual last owner",
);
compositor.invalidate_cache();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes,
"the presented baseline still owns the frame",
);
compositor.invalidate_presented();
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes,
"the caller still retains the second frame",
);
drop(second);
assert_eq!(governor.used(ResourceCategory::CompositorCells), 0);
}
#[test]
fn shared_frame_owner_rejection_preserves_the_exact_cached_frame() {
let (mut scene, anim_rt) = simple_scene();
let governor = ResourceGovernor::new();
let mut compositor = Compositor::with_governor(40, 10, governor.clone());
let frame_bytes = 40 * 10 * std::mem::size_of::<Cell>();
let previous = compositor.composite(&scene, &anim_rt).unwrap();
compositor
.present_main(&mut Vec::new(), &previous, 0, 10)
.unwrap();
scene.invalidation.mark_composite(Rect::new(0, 0, 1, 1));
REJECT_FRAME_OWNER.with(|site| site.set(true));
assert!(compositor.composite(&scene, &anim_rt).is_none());
assert!(SharedFrame::ptr_eq(
compositor.last_output.as_ref().unwrap(),
&previous,
));
assert!(SharedFrame::ptr_eq(
compositor.last_presented.as_ref().unwrap(),
&previous,
));
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
frame_bytes,
"the rejected candidate must release its cell lease",
);
let replacement = compositor.composite(&scene, &anim_rt).unwrap();
assert!(!SharedFrame::ptr_eq(&previous, &replacement));
drop(previous);
compositor.invalidate_cache();
compositor.invalidate_presented();
drop(replacement);
assert_eq!(governor.used(ResourceCategory::CompositorCells), 0);
}
#[test]
fn governed_cache_rejects_before_remote_sized_allocation() {
let (scene, anim_rt) = simple_scene();
let governor = ResourceGovernor::new();
let frame_bytes = 40 * 10 * std::mem::size_of::<Cell>();
let _pressure = governor
.reserve(
ResourceCategory::CompositorCells,
crate::resource::MAX_REMOTE_MEMORY - frame_bytes + 1,
)
.unwrap();
let mut compositor = Compositor::with_governor(40, 10, governor.clone());
assert!(compositor.composite(&scene, &anim_rt).is_none());
assert_eq!(
governor.used(ResourceCategory::CompositorCells),
crate::resource::MAX_REMOTE_MEMORY - frame_bytes + 1,
"failed admission must not leave a cache reservation",
);
}
#[test]
fn first_composite_walks_and_caches() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
assert!(c.last_output.is_none(), "cache starts empty");
let out = c.composite(&scene, &anim_rt).unwrap();
assert_eq!(out.width, 40);
assert!(c.last_output.is_some(), "first composite populates cache");
}
#[test]
fn clean_invalidation_returns_cached_frame() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let first = c.composite(&scene, &anim_rt).unwrap();
let second = c.composite(&scene, &anim_rt).unwrap();
assert_eq!(first.width, second.width);
assert_eq!(first.height, second.height);
for y in 0..first.height {
for x in 0..first.width {
assert_eq!(
first.get(x, y),
second.get(x, y),
"clean invalidation must produce identical cells at ({x},{y})",
);
}
}
}
#[test]
fn dirty_invalidation_walks_again() {
let (mut scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let _first = c.composite(&scene, &anim_rt).unwrap();
scene
.invalidation
.mark_composite(crate::compositor::layout::Rect::new(0, 0, 5, 1));
let _second = c.composite(&scene, &anim_rt).unwrap();
assert!(c.last_output.is_some());
}
#[test]
fn resize_invalidates_cache() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
c.composite(&scene, &anim_rt);
assert!(c.last_output.is_some());
c.resize(60, 10);
assert!(
c.last_output.is_none(),
"resize to different dims must drop cache"
);
c.composite(&scene, &anim_rt);
c.resize(60, 10);
assert!(
c.last_output.is_some(),
"resize to same dims must preserve cache"
);
}
#[test]
fn invalidate_cache_forces_walk() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
c.composite(&scene, &anim_rt);
assert!(c.last_output.is_some());
c.invalidate_cache();
assert!(c.last_output.is_none());
}
#[test]
fn present_main_first_frame_emits_full() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let frame = c.composite(&scene, &anim_rt).unwrap();
let mut out = Vec::new();
c.present_main(&mut out, &frame, 0, 10).unwrap();
assert!(!out.is_empty(), "first present must emit bytes");
assert!(out.windows(2).any(|w| w == b"\x1b["));
}
#[test]
fn present_main_idle_tick_emits_nothing() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let frame = c.composite(&scene, &anim_rt).unwrap();
let mut out1 = Vec::new();
c.present_main(&mut out1, &frame, 0, 10).unwrap();
assert!(!out1.is_empty());
let mut out2 = Vec::new();
c.present_main(&mut out2, &frame, 0, 10).unwrap();
assert!(
out2.is_empty(),
"idle re-present must emit zero bytes; got {} bytes",
out2.len()
);
}
#[test]
fn present_main_viewport_change_emits_full() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let frame = c.composite(&scene, &anim_rt).unwrap();
let mut _out1 = Vec::new();
c.present_main(&mut _out1, &frame, 0, 10).unwrap();
c.set_last_focus_span(Some(FocusSpan {
screen_row: 4,
buf_row: 4,
col_start: 2,
col_end: 8,
is_sticky: false,
}));
let mut out2 = Vec::new();
c.present_main(&mut out2, &frame, 2, 8).unwrap();
assert!(
!out2.is_empty(),
"viewport offset change must trigger full emit",
);
assert_eq!(
c.last_focus_span(),
None,
"full repaint must discard the focus overlay's old screen row",
);
}
#[test]
fn present_main_invalidate_presented_forces_full() {
let (scene, anim_rt) = simple_scene();
let mut c = Compositor::new(40, 10);
let frame = c.composite(&scene, &anim_rt).unwrap();
let mut out1 = Vec::new();
c.present_main(&mut out1, &frame, 0, 10).unwrap();
c.invalidate_presented();
let mut out2 = Vec::new();
c.present_main(&mut out2, &frame, 0, 10).unwrap();
assert!(
!out2.is_empty(),
"invalidate_presented must force next emit to be full",
);
assert!(
out2.windows(b"\x1b[2J".len())
.any(|window| window == b"\x1b[2J"),
"a scene-changing full repaint must clear retained terminal cells",
);
}
#[test]
fn render_diff_across_transition_end_emits_zero_bytes() {
use crate::compositor::layout::Rect;
use crate::compositor::layout::cell::CellStyle;
use crate::compositor::scene::OverlaySource;
let src = r#"[page mode=screen cols=10 rows=2][text]HELLO WRLD[/text][/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _ = crate::compositor::layout::engine::layout_scene(
&mut scene,
10,
2,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let anim_rt = AnimationRuntime::new(Vec::new());
let mut c = Compositor::new(10, 2);
let base_frame = c.composite(&scene, &anim_rt).unwrap();
let overlay_id = scene.insert_overlay(
i16::MAX,
OverlaySource::PageTransition,
Rect::new(0, 0, 10, 2),
);
{
let buf = scene.overlay_buffer_mut(overlay_id).unwrap();
for y in 0..2 {
for x in 0..10 {
if let Some(cell) = base_frame.get(x, y) {
buf.set(x, y, cell.clone());
} else {
buf.put_char(x, y, ' ', &CellStyle::default());
}
}
}
}
let frame1 = c.composite(&scene, &anim_rt).unwrap();
let mut out1 = Vec::new();
c.present_main(&mut out1, &frame1, 0, 2).unwrap();
assert!(!out1.is_empty(), "first present is always non-empty");
scene.remove_overlay(overlay_id);
let frame2 = c.composite(&scene, &anim_rt).unwrap();
let mut out2 = Vec::new();
c.present_main(&mut out2, &frame2, 0, 2).unwrap();
assert!(
out2.is_empty(),
"post-transition-end frame should diff to zero bytes when overlay content \
matched the underlying scene; got {} bytes (bypass path used to force \
full repaint here)",
out2.len(),
);
}
#[test]
fn live_region_overlays_its_children() {
let src = r#"[page mode=screen cols=20 rows=2]
[live src="atp://example.com" h=2][text]PLACEHOLDER[/text][/live]
[/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _lr = crate::compositor::layout::engine::layout_scene(
&mut scene,
20,
2,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let live_id = scene.find_by_aml_id("").unwrap_or_else(|| {
scene
.iter_tree_order()
.find(|n| matches!(n.kind(), NodeKind::LiveRegion(_)))
.map(|n| n.id())
.expect("scene has a LiveRegion node")
});
scene.allocate_buffer(live_id, 20, 2);
{
let buf = scene.live_buffer_mut(live_id).expect("live buffer");
buf.put_str(0, 0, "LIVE", &CellStyle::default());
}
let anim_rt = AnimationRuntime::new(Vec::new());
let out = walk(&scene, &anim_rt, 20, 2);
assert_eq!(
out.get(0, 0).unwrap().ch,
'L',
"subscription overlays placeholder"
);
assert_eq!(out.get(1, 0).unwrap().ch, 'I');
assert_eq!(out.get(2, 0).unwrap().ch, 'V');
assert_eq!(out.get(3, 0).unwrap().ch, 'E');
assert_eq!(
out.get(4, 0).unwrap().ch,
'E',
"transparent live cells let placeholder show through"
);
}
#[test]
fn overlay_paints_on_top_of_tree_order_nodes() {
use crate::compositor::layout::Rect;
use crate::compositor::scene::OverlaySource;
let src = r#"[page mode=screen cols=10 rows=2][text]BASE[/text][/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _lr = crate::compositor::layout::engine::layout_scene(
&mut scene,
10,
2,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let overlay_id = scene.insert_overlay(
i16::MAX,
OverlaySource::PageTransition,
Rect::new(0, 0, 10, 2),
);
{
let buf = scene.overlay_buffer_mut(overlay_id).unwrap();
buf.put_str(0, 0, "OVER", &CellStyle::default());
}
let anim_rt = AnimationRuntime::new(Vec::new());
let out = walk(&scene, &anim_rt, 10, 2);
assert_eq!(out.get(0, 0).unwrap().ch, 'O', "overlay wins col 0");
assert_eq!(out.get(1, 0).unwrap().ch, 'V');
assert_eq!(out.get(2, 0).unwrap().ch, 'E');
assert_eq!(out.get(3, 0).unwrap().ch, 'R');
}
#[test]
fn static_walk_excludes_page_transition_overlay() {
use crate::compositor::layout::Rect;
use crate::compositor::scene::OverlaySource;
let src = r#"[page mode=screen cols=10 rows=1][text]DESTINATION[/text][/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _ = crate::compositor::layout::engine::layout_scene(
&mut scene,
10,
1,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let overlay_id = scene.insert_overlay(
i16::MAX,
OverlaySource::PageTransition,
Rect::new(0, 0, 10, 1),
);
scene.overlay_buffer_mut(overlay_id).unwrap().put_str(
0,
0,
"OLD PAGE!!",
&CellStyle::default(),
);
let live = walk(&scene, &AnimationRuntime::empty(), 10, 1);
assert_eq!(live.get(0, 0).unwrap().ch, 'O', "normal walk shows overlay");
let panel_source = walk_static(&scene, 10, 1);
let text: String = (0..10)
.map(|x| panel_source.get(x, 0).unwrap().ch)
.collect();
assert_eq!(text, "DESTINATIO");
assert!(!text.contains("OLD"));
}
#[test]
fn overlay_transparent_cells_pass_through() {
use crate::compositor::layout::Rect;
use crate::compositor::scene::OverlaySource;
let src = r#"[page mode=screen cols=10 rows=1][text]ABCDEFGHIJ[/text][/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _lr = crate::compositor::layout::engine::layout_scene(
&mut scene,
10,
1,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let overlay_id = scene.insert_overlay(
i16::MAX,
OverlaySource::PageTransition,
Rect::new(0, 0, 10, 1),
);
{
let buf = scene.overlay_buffer_mut(overlay_id).unwrap();
*buf = CellBuffer::new(10, 1); buf.put_str(6, 0, "XY", &CellStyle::default());
}
let anim_rt = AnimationRuntime::new(Vec::new());
let out = walk(&scene, &anim_rt, 10, 1);
assert_eq!(
out.get(0, 0).unwrap().ch,
'A',
"base shows through transparent overlay"
);
assert_eq!(out.get(5, 0).unwrap().ch, 'F');
assert_eq!(
out.get(6, 0).unwrap().ch,
'X',
"overlay paints its opaque cells"
);
assert_eq!(out.get(7, 0).unwrap().ch, 'Y');
assert_eq!(out.get(8, 0).unwrap().ch, 'I');
assert_eq!(out.get(9, 0).unwrap().ch, 'J');
}
#[test]
fn panel_overlays_its_children() {
let src = r#"[page mode=screen cols=10 rows=2]
[panel id="p" state="a"]
[state name="a" x=0 y=0 w=10 h=2][text]AAAA[/text][/state]
[/panel]
[/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _lr = crate::compositor::layout::engine::layout_scene(
&mut scene,
10,
2,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let panel_id = scene.find_by_aml_id("p").expect("panel");
scene.allocate_buffer(panel_id, 10, 2);
{
let buf = scene.panel_buffer_mut(panel_id).expect("panel buffer");
buf.put_str(0, 0, "TRANS", &CellStyle::default());
}
let anim_rt = AnimationRuntime::new(Vec::new());
let out = walk(&scene, &anim_rt, 10, 2);
assert_eq!(out.get(0, 0).unwrap().ch, 'T');
assert_eq!(out.get(1, 0).unwrap().ch, 'R');
assert_eq!(out.get(2, 0).unwrap().ch, 'A');
assert_eq!(out.get(3, 0).unwrap().ch, 'N');
assert_eq!(out.get(4, 0).unwrap().ch, 'S');
}
#[test]
#[cfg_attr(miri, ignore = "tokio runtime needs kqueue, which Miri cannot emulate")]
fn from_scene_preserves_frame_descendant_placements() {
use crate::compositor::animate::AnimationRuntime;
let src = r#"[page mode=screen cols=20 rows=3]
[box y=1 w=20 h=2 border=none]
[animate id="tw" fps=4 autoplay=false]
[frame][pre]ROWZERO-A[/pre][/frame]
[frame][pre]ROWZERO-B[/pre][/frame]
[/animate]
[/box]
[/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let _ = crate::compositor::layout::engine::layout_scene(
&mut scene,
20,
3,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
);
let frame_desc: Vec<(
crate::compositor::scene::NodeId,
crate::compositor::layout::Rect,
)> = {
let mut out = Vec::new();
let frame_ids: Vec<crate::compositor::scene::NodeId> = scene
.iter_tree_order()
.filter(|n| {
matches!(n.kind(),
NodeKind::Flow(f) if f.source == crate::compositor::scene::FlowSource::Frame)
})
.map(|n| n.id())
.collect();
for fid in frame_ids {
let mut stack = vec![fid];
while let Some(id) = stack.pop() {
if let Some(n) = scene.get(id) {
out.push((id, n.placement().rect));
stack.extend(n.children().iter().copied());
}
}
}
out
};
let rt = tokio::runtime::Builder::new_current_thread()
.build()
.unwrap();
let _anim_rt = rt.block_on(AnimationRuntime::from_scene(
&mut scene,
crate::color::ColorSupport::Truecolor,
crate::compositor::layout::text::WidthConfig::default(),
None,
));
for (id, before) in frame_desc {
let after = scene.get(id).map(|n| n.placement().rect).unwrap_or(before);
assert_eq!(
after, before,
"node {id:?} placement changed from {:?} to {:?} — from_scene clobbered a frame descendant",
before, after,
);
}
}
#[test]
#[cfg_attr(miri, ignore = "tokio runtime needs kqueue, which Miri cannot emulate")]
fn typewriter_paints_at_animation_rect_not_row_zero() {
use crate::compositor::animate::{AnimState, AnimationRuntime};
use crate::compositor::scene::{Patch, PatchApplier};
let src = r#"[page mode=screen cols=30 rows=6]
[panel id="p" state="hidden"]
[state name="hidden"][/state]
[state name="visible"]
[box y=1 w=30 h=4 border=none]
[animate id="tw" fps=12 autoplay=false]
[frame][pre]AAAA[/pre][/frame]
[frame][pre]BBBB[/pre][/frame]
[frame][pre]CCCC[/pre][/frame]
[/animate]
[/box]
[/state]
[/panel]
[/page]"#;
let mut scanner = crate::scanner::Scanner::new(src.as_bytes()).unwrap();
let tokens = scanner.scan_all().unwrap();
let doc = crate::parser::parse(tokens).document.unwrap();
let mut scene = crate::compositor::scene::build::from_document(&doc);
let color = crate::color::ColorSupport::Truecolor;
let wcfg = crate::compositor::layout::text::WidthConfig::default();
let _ = crate::compositor::layout::engine::layout_scene(&mut scene, 30, 6, color, wcfg);
let panel_id = scene.find_by_aml_id("p").unwrap();
let visible_state = {
let panel = scene.get(panel_id).unwrap();
let NodeKind::Panel { states, .. } = panel.kind() else {
unreachable!()
};
*states
.iter()
.find(|&&s| scene.get(s).and_then(|n| n.aml_id()) == Some("visible"))
.unwrap()
};
PatchApplier::apply(
&mut scene,
Patch::SetPanelActive {
panel: panel_id,
active: visible_state,
},
);
let mut page_buf = CellBuffer::new(30, 6);
crate::compositor::layout::engine::relayout_in_place(
&mut scene,
&mut page_buf,
panel_id,
color,
wcfg,
);
let placed: Vec<_> = scene.iter_placed().collect();
for p in &placed {
if let Some(nid) = scene.find_by_aml_id(&p.id)
&& !p.rect.is_empty()
{
scene.allocate_buffer(nid, p.rect.w, p.rect.h);
}
}
let rt = tokio::runtime::Builder::new_current_thread()
.build()
.unwrap();
let mut anim_rt = rt.block_on(AnimationRuntime::from_scene(&mut scene, color, wcfg, None));
let anim_id = scene.find_by_aml_id("tw").unwrap();
let anim_rect = scene.get(anim_id).unwrap().placement().rect;
assert!(
anim_rect.y >= 1,
"typewriter should sit inside the box, got {anim_rect:?}",
);
let anim_row = anim_rect.y;
anim_rt.trigger_start("tw");
let base = std::time::Instant::now();
for i in 0..3 {
let now = base + std::time::Duration::from_millis(200 * (i + 1));
anim_rt.tick(&mut scene, now, 0, 6);
}
anim_rt.paint_into_scene(&mut scene);
let tw_state = anim_rt
.animations
.iter()
.find(|a| a.id() == "tw")
.map(|a| a.state())
.unwrap();
assert!(
!matches!(tw_state, AnimState::Waiting),
"typewriter should have left Waiting after trigger + ticks, got {tw_state:?}",
);
let out = walk(&scene, &anim_rt, 30, 6);
for x in 0..30 {
let ch = out.get(x, 0).map(|c| c.ch).unwrap_or(' ');
assert!(
ch == ' ' || ch == '\0',
"col {x} of row 0 should be empty, got {:?}",
ch,
);
}
let row: String = (0..30)
.map(|x| out.get(x, anim_row).map(|c| c.ch).unwrap_or(' '))
.collect();
assert!(
row.contains('B') || row.contains('C'),
"row {anim_row} should show an advanced frame letter, got {:?}",
row,
);
}
}