compose_rust/

renderer.rs

use crate::drawing::DrawList;
use crate::protocol::{BatchEncoder, Mutation, PropertyValue, ProtocolError};
use crate::schema::{PropertyKind, WidgetKind};
use dioxus_core::{
    AttributeValue, ElementId, Template, TemplateAttribute, TemplateNode, WriteMutations,
};
use std::collections::HashMap;

/// The inclusive range of design-property tags. Extension properties follow this range.
const FIRST_OPTIONAL_PROPERTY: u16 = PropertyKind::TypeRole as u16;
const LAST_OPTIONAL_PROPERTY: u16 = PropertyKind::Variant as u16;

/// The bit that tracks whether a node has ever carried a list of text runs.
///
/// Outside the range above and kept separately, because widening that range swallowed
/// values where zero means zero: a picker whose minimum really is 0 stopped sending it
/// and got the Renderer's default instead. A list of runs has no such value. Empty and
/// absent are the same state, so the first empty one is worth no record.
const SPANS_BIT: u32 = 63;

#[derive(Clone, Copy, Debug)]
struct Handler {
    id: u64,
    element: ElementId,
    node_id: u32,
    name: &'static str,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum PathTarget {
    Node(u32),
    /// A template's dynamic child: the node it hangs under, and the marker standing in
    /// its place until its content arrives.
    Slot {
        parent: u32,
        marker: u32,
    },
}

/// One position among a parent's children.
///
/// The Renderer counts only the nodes it drew, so the index an Insert carries is the
/// number of drawn siblings that come first. A placeholder and a template's unfilled
/// dynamic child are both positions nothing is drawn for, and keeping them here is what
/// lets the content that arrives later take the position it was promised rather than the
/// end of the list.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Slot {
    /// A node the Renderer drew.
    Node(u32),
    /// A Dioxus placeholder, named by the element it was created for. Placeholders all
    /// carry node id 0, so the element is the only thing that tells two of them apart.
    Hole(usize),
    /// A template's dynamic child, from the moment the template is built until the
    /// content of that child arrives.
    Pending(u32),
}

#[derive(Debug)]
struct StackNode {
    node_id: u32,
    /// The element this entry was created for, when it is a placeholder.
    ///
    /// A placeholder is not a node in the Compose tree, so every one of them carries node
    /// id 0. Two placeholders on screen at once still stand in two different places, and
    /// the element is what tells them apart.
    element: Option<ElementId>,
    paths: HashMap<Vec<u8>, PathTarget>,
}

/// How many Modifier slots a node has. The slot numbers are assigned in `set_modifier`,
/// and this is one past the last of them.
const MODIFIER_SLOTS: usize = 14;

/// Node id 0 is the "no node" sentinel: a Dioxus placeholder, which draws nothing and
/// takes no slot in the Compose tree.
const PLACEHOLDER_NODE: u32 = 0;

/// `dioxus-core` mutation sink that writes the Compose wire protocol directly.
pub struct ComposeRenderer {
    encoder: BatchEncoder,
    next_node_id: u32,
    next_handler_id: u64,
    nodes: Vec<Option<u32>>,
    handlers: Vec<Handler>,
    /// Which parent each drawn node hangs under.
    parents: HashMap<u32, u32>,
    /// Which parent each placeholder stands under, keyed by its element rather than by a
    /// node id.
    ///
    /// Placeholders all share node id 0, so keying them by node id made every one of them
    /// overwrite the last: a branch that filled in was then attached to whichever other
    /// placeholder had been seen most recently, which put a subtree under a stranger and,
    /// when that stranger was its own descendant, left the parent chain with no root.
    placeholders: HashMap<usize, u32>,
    /// What stands under each parent, in order.
    ///
    /// An index is read off this list rather than remembered from the Insert that put a
    /// node there. Removing a sibling moves everything after it, so a remembered index is
    /// only right until the next removal: a menu whose entries came and went handed the
    /// next set of entries the position the old last entry had held, and they piled up
    /// past the end of the list instead of taking its place.
    children: HashMap<u32, Vec<Slot>>,
    /// The next marker to stand in a template's dynamic child.
    next_marker: u32,
    /// Which design properties a node has actually been given, one bit per tag.
    optional_props: HashMap<u32, u64>,
    /// A border arrives as a width and a colour in separate attributes; this holds
    /// whichever came first until the pair can be written as one modifier.
    pending_borders: HashMap<u32, (Option<f32>, Option<crate::Paint>)>,
    /// Which attribute last wrote each of a node's Modifier slots, or `""` for a slot
    /// nothing has written.
    ///
    /// Two things need the owner rather than a "written" bit. Clearing a slot that was
    /// never written would cost a mutation on the first frame of every widget, for a
    /// Modifier nobody asked for. And some slots have two attributes that can fill them,
    /// `shape_role` and `corner_radius` for the shape, `padding_role` and `padding` for
    /// the padding: the one left unset arrives as an empty attribute, and without the
    /// owner it would clear the modifier its partner had just written, which is how a
    /// rounded container came out square.
    modifier_slots: HashMap<u32, [&'static str; MODIFIER_SLOTS]>,
    /// Which application token each observed node was given, for reading a report back.
    size_tokens: HashMap<u32, u32>,
    stack: Vec<StackNode>,
    error: Option<ProtocolError>,
}

impl Default for ComposeRenderer {
    fn default() -> Self {
        Self::new()
    }
}

impl ComposeRenderer {
    /// The application's name for an observed node, if that node is observed.
    pub(crate) fn size_token(&self, node_id: u32) -> Option<u32> {
        self.size_tokens.get(&node_id).copied()
    }

    pub fn new() -> Self {
        Self {
            encoder: BatchEncoder::with_capacity(16 * 1024, 4 * 1024, 256),
            next_node_id: 1,
            next_handler_id: 1,
            nodes: Vec::with_capacity(256),
            handlers: Vec::with_capacity(64),
            parents: HashMap::with_capacity(256),
            placeholders: HashMap::with_capacity(16),
            children: HashMap::with_capacity(256),
            next_marker: 1,
            optional_props: HashMap::with_capacity(64),
            pending_borders: HashMap::with_capacity(16),
            modifier_slots: HashMap::with_capacity(64),
            // Empty until a screen asks, which is the point: a tree that observes nothing
            // allocates nothing here.
            size_tokens: HashMap::new(),
            stack: Vec::with_capacity(64),
            error: None,
        }
    }

    /// The batch arena, so a runtime that reads Host memory through a mapped view can be
    /// handed one.
    pub fn arena(&self) -> (*const u8, usize) {
        self.encoder.arena()
    }

    pub fn begin_frame(&mut self) {
        self.encoder.clear();
        self.error = None;
    }

    pub fn finish_frame(&mut self) -> Result<&[u8], ProtocolError> {
        if let Some(error) = self.error.take() {
            return Err(error);
        }
        self.encoder.finish()
    }

    pub fn handler(&self, handler_id: u64) -> Option<(ElementId, u32, &'static str)> {
        self.handlers
            .iter()
            .find(|handler| handler.id == handler_id)
            .map(|handler| (handler.element, handler.node_id, handler.name))
    }

    pub fn set_text(
        &mut self,
        element: ElementId,
        text: &str,
        selection: Option<crate::Selection>,
    ) {
        let Some(node_id) = self.node(element) else {
            return;
        };
        self.write(Mutation::SetText {
            node_id,
            text,
            selection,
        });
    }

    /// The root theme record. Written once per rebuild, never per frame.
    pub fn set_theme(&mut self, theme: crate::schema::Theme) {
        self.write(Mutation::SetTheme(theme));
    }

    /// The root window record. Written once per rebuild, never per frame.
    pub fn set_window(&mut self, window: crate::schema::Window) {
        self.write(Mutation::SetWindow(window));
    }

    pub fn set_text_node(&mut self, node_id: u32, text: &str, selection: Option<crate::Selection>) {
        self.write(Mutation::SetText {
            node_id,
            text,
            selection,
        });
    }

    /// Copies one asset into the batch. The bytes ride behind the records, and the
    /// Renderer takes its own copy inside the call that carries them.
    pub fn register_asset(&mut self, asset_id: u32, kind: crate::schema::AssetKind, bytes: &[u8]) {
        self.write(Mutation::RegisterAsset {
            asset_id,
            kind,
            bytes,
        });
    }

    pub fn release_asset(&mut self, asset_id: u32) {
        self.write(Mutation::ReleaseAsset { asset_id });
    }

    /// Writes one transient message into the batch.
    ///
    /// It names no node, because a message is not in the tree: it is a sentence with a
    /// lifetime, and that lifetime belongs to the Renderer.
    pub fn show_message(
        &mut self,
        handler_id: u64,
        text: &str,
        action: &str,
        duration: crate::schema::MessageDuration,
    ) {
        self.write(Mutation::ShowMessage {
            handler_id,
            text,
            action,
            duration,
        });
    }

    /// Append the streamed tail to a Text node without resending its whole value.
    pub fn append_text_node(&mut self, node_id: u32, text: &str) {
        self.write(Mutation::AppendText { node_id, text });
    }

    /// Turns a Modifier attribute written in `rsx!` into one slot of the node's chain.
    ///
    /// The Renderer applies the chain in list order, exactly as hand-written Compose does,
    /// so the slot an attribute occupies decides what the result looks like. Padding
    /// before a background is a margin; after it, it insets the content. Fixing the slots
    /// here means `Card { background: .., padding: 16.0 }` behaves the way the person who
    /// wrote it expects, whichever order they happened to type the attributes in.
    ///
    /// The order below reads outside in: how big the widget is, what shape it is, what
    /// fills it, what outlines it, what lifts it, what responds to a press, and finally
    /// how far its content sits inside all of that.
    ///
    /// A `false` or absent value writes `Empty` into the slot rather than dropping the
    /// mutation, because a slot that keeps its old value would leave the removed modifier
    /// applied.
    fn modifier_for(
        &mut self,
        element: ElementId,
        node_id: u32,
        name: &'static str,
        value: &AttributeValue,
    ) -> Option<Option<(u16, crate::Modifier)>> {
        use crate::Modifier;

        // Slot assignments. Append only: an existing slot never changes meaning, because a
        // node keeps whatever a slot held until something overwrites it.
        const WEIGHT: u16 = 0;
        const FILL_MAX_WIDTH: u16 = 1;
        const FILL_MAX_HEIGHT: u16 = 2;
        const WIDTH: u16 = 3;
        const HEIGHT: u16 = 4;
        const SHAPE: u16 = 5;
        const BACKGROUND: u16 = 6;
        const BORDER: u16 = 7;
        const ELEVATION: u16 = 8;
        const CLICKABLE: u16 = 9;
        const PADDING: u16 = 10;
        const OBSERVE_SIZE: u16 = 11;
        const MOTION: u16 = 12;
        const MATERIAL: u16 = 13;

        let float = |value: &AttributeValue| match value {
            AttributeValue::Float(number) => Some(*number as f32),
            AttributeValue::Int(number) => Some(*number as f32),
            _ => None,
        };
        let integer = |value: &AttributeValue| match value {
            AttributeValue::Int(number) => Some(*number),
            AttributeValue::Float(number) => Some(*number as i64),
            _ => None,
        };

        let slot_of = |name: &str| match name {
            "weight" => Some(WEIGHT),
            "fill_max_width" => Some(FILL_MAX_WIDTH),
            "fill_max_height" => Some(FILL_MAX_HEIGHT),
            "width" => Some(WIDTH),
            "height" => Some(HEIGHT),
            "shape_role" | "corner_radius" => Some(SHAPE),
            "background" => Some(BACKGROUND),
            "border_width" | "border_color" => Some(BORDER),
            "elevation" => Some(ELEVATION),
            "onclickable" => Some(CLICKABLE),
            "padding" | "padding_role" => Some(PADDING),
            "observe_size" => Some(OBSERVE_SIZE),
            "motion" => Some(MOTION),
            "material" => Some(MATERIAL),
            _ => None,
        };
        let slot = slot_of(name)?;

        // An unset Modifier attribute is not a property, so it must not fall through to
        // set_property and be rejected as an unknown one. It only produces a mutation if
        // this slot already holds something, because clearing a slot that was never
        // written would cost a mutation on the first frame of every widget.
        if matches!(value, AttributeValue::None) {
            let owners = self
                .modifier_slots
                .entry(node_id)
                .or_insert([""; MODIFIER_SLOTS]);
            // Only the attribute that wrote the slot may clear it. `corner_radius` being
            // unset says nothing about the `shape_role` sitting in the same slot.
            if owners[slot as usize] != name {
                return Some(None);
            }
            owners[slot as usize] = "";
            return Some(Some((slot, crate::Modifier::Empty)));
        }
        self.modifier_slots
            .entry(node_id)
            .or_insert([""; MODIFIER_SLOTS])[slot as usize] = name;

        match name {
            // The token is the application's name for this node, and it stays here: what
            // the Renderer reports back is its own node id, so the pairing has to be
            // remembered at the moment the two are both in hand.
            "observe_size" => {
                let token = u32::try_from(integer(value)?).ok()?;
                self.size_tokens.insert(node_id, token);
                Some(Some((slot, Modifier::ObserveSize { token })))
            }
            "fill_max_width" | "fill_max_height" => {
                let AttributeValue::Bool(enabled) = value else {
                    return Some(None);
                };
                Some(Some((
                    slot,
                    if !enabled {
                        Modifier::Empty
                    } else if slot == FILL_MAX_WIDTH {
                        Modifier::FillMaxWidth
                    } else {
                        Modifier::FillMaxHeight
                    },
                )))
            }
            "weight" => Some(Some((WEIGHT, Modifier::Weight(float(value)?)))),
            "width" => Some(Some((WIDTH, Modifier::Width(float(value)?)))),
            "height" => Some(Some((HEIGHT, Modifier::Height(float(value)?)))),
            "padding" => Some(Some((PADDING, Modifier::Padding(float(value)?)))),
            "padding_role" => Some(Some((
                PADDING,
                Modifier::PaddingRole(
                    crate::SpaceRole::try_from(u16::try_from(integer(value)?).ok()?).ok()?,
                ),
            ))),
            "elevation" => Some(Some((ELEVATION, Modifier::Elevation(float(value)?)))),
            "corner_radius" => {
                let radius = float(value)?;
                Some(Some((
                    SHAPE,
                    Modifier::Shape {
                        top_start: radius,
                        top_end: radius,
                        bottom_end: radius,
                        bottom_start: radius,
                    },
                )))
            }
            // The node says how important its changes are. Which curve and how many
            // milliseconds that means is the design system's answer, and it is never
            // asked here.
            "motion" => Some(Some((
                MOTION,
                Modifier::Motion(
                    crate::MotionRole::try_from(u16::try_from(integer(value)?).ok()?).ok()?,
                ),
            ))),
            // What the surface is made of. Blur, tone or a flat fill is the running
            // design system's answer, and the node does not get to ask for one of them.
            "material" => Some(Some((
                MATERIAL,
                Modifier::Material(
                    crate::MaterialRole::try_from(u16::try_from(integer(value)?).ok()?).ok()?,
                ),
            ))),
            "shape_role" => Some(Some((
                SHAPE,
                Modifier::ShapeRole(
                    crate::ShapeRole::try_from(u16::try_from(integer(value)?).ok()?).ok()?,
                ),
            ))),
            // Colour crosses as the bits of a Paint, so a role and a literal colour take
            // the same path and there is one wire representation of colour.
            "background" => Some(Some((
                BACKGROUND,
                Modifier::Background(crate::Paint::from_bits(integer(value)? as u64)?),
            ))),
            // A border needs a width and a colour, which arrive as two attributes. The
            // half that arrives first is remembered so the pair can be written as one
            // modifier, whichever order Dioxus hands them over in.
            "border_width" | "border_color" => {
                let pending = self.pending_borders.entry(node_id).or_default();
                if name == "border_width" {
                    pending.0 = Some(float(value)?);
                } else {
                    pending.1 = Some(crate::Paint::from_bits(integer(value)? as u64)?);
                }
                let (Some(width), Some(paint)) = (pending.0, pending.1) else {
                    return Some(None);
                };
                Some(Some((BORDER, Modifier::Border { width, paint })))
            }
            "onclickable" => {
                let AttributeValue::Listener(_) = value else {
                    return Some(None);
                };
                let handler_id = self.next_handler_id;
                self.next_handler_id += 1;
                self.handlers.push(Handler {
                    id: handler_id,
                    element,
                    node_id,
                    name,
                });
                Some(Some((CLICKABLE, Modifier::Clickable { handler_id })))
            }
            _ => None,
        }
    }

    fn write(&mut self, mutation: Mutation<'_>) {
        if self.error.is_none() {
            if let Err(error) = self.encoder.encode(&mutation) {
                self.error = Some(error);
            }
        }
    }

    fn allocate_node(&mut self, widget: WidgetKind) -> u32 {
        let id = self.next_node_id;
        self.next_node_id = self.next_node_id.checked_add(1).unwrap_or(1);
        self.write(Mutation::Create {
            node_id: id,
            widget,
        });
        id
    }

    fn map_node(&mut self, element: ElementId, node_id: u32) {
        if self.nodes.len() <= element.0 {
            self.nodes.resize(element.0 + 1, None);
        }
        self.nodes[element.0] = Some(node_id);
    }

    fn node(&self, element: ElementId) -> Option<u32> {
        self.nodes.get(element.0).copied().flatten()
    }

    fn build_template_node(
        &mut self,
        node: &TemplateNode,
        path: &mut Vec<u8>,
        paths: &mut HashMap<Vec<u8>, PathTarget>,
    ) -> Option<u32> {
        match node {
            TemplateNode::Element {
                tag,
                attrs,
                children,
                ..
            } => {
                let widget = match widget_kind(tag) {
                    Ok(widget) => widget,
                    Err(error) => {
                        self.error = Some(error);
                        return None;
                    }
                };
                let node_id = self.allocate_node(widget);
                paths.insert(path.clone(), PathTarget::Node(node_id));
                for attribute in *attrs {
                    if let TemplateAttribute::Static { name, value, .. } = attribute {
                        self.set_property(node_id, name, &AttributeValue::Text((*value).into()));
                    }
                }
                for (index, child) in children.iter().enumerate() {
                    path.push(index as u8);
                    match child {
                        TemplateNode::Dynamic { .. } => {
                            let marker = self.reserve_slot(node_id);
                            paths.insert(
                                path.clone(),
                                PathTarget::Slot {
                                    parent: node_id,
                                    marker,
                                },
                            );
                        }
                        _ => {
                            if let Some(child_id) = self.build_template_node(child, path, paths) {
                                let end = self.end_of(node_id);
                                self.insert_node(node_id, child_id, end, None);
                            }
                        }
                    }
                    path.pop();
                }
                Some(node_id)
            }
            TemplateNode::Text { text } => {
                let node_id = self.allocate_node(WidgetKind::Text);
                self.write(Mutation::SetProp {
                    node_id,
                    property: PropertyKind::Text,
                    value: PropertyValue::String(text),
                });
                paths.insert(path.clone(), PathTarget::Node(node_id));
                Some(node_id)
            }
            TemplateNode::Dynamic { .. } => None,
        }
    }

    /// Role tag 0 means "not sent", so a design property at its neutral value
    /// produces no record at all. A property that was set and then cleared still sends
    /// its zero once, which is what tells the Renderer to drop the override.
    fn should_write_optional_property(
        &mut self,
        node_id: u32,
        property: PropertyKind,
        neutral: bool,
    ) -> bool {
        let tag = property as u16;
        let index = if (FIRST_OPTIONAL_PROPERTY..=LAST_OPTIONAL_PROPERTY).contains(&tag) {
            u32::from(tag - FIRST_OPTIONAL_PROPERTY)
        } else if property == PropertyKind::Spans {
            SPANS_BIT
        } else {
            return true;
        };
        let bit = 1_u64 << index;
        let seen = self.optional_props.get(&node_id).copied().unwrap_or(0);
        if neutral {
            if seen & bit == 0 {
                return false;
            }
            self.optional_props.insert(node_id, seen & !bit);
        } else if seen & bit == 0 {
            self.optional_props.insert(node_id, seen | bit);
        }
        true
    }

    fn set_property(&mut self, node_id: u32, name: &str, value: &AttributeValue) {
        let Some(property) = property_kind(name) else {
            // dioxus-core has no fallible WriteMutations methods. Preserve the
            // protocol error and surface it when the batch is finalized.
            self.error = Some(ProtocolError::InvalidProperty(0));
            return;
        };
        let value = match value {
            AttributeValue::Text(value) => PropertyValue::String(value),
            AttributeValue::Float(value) => PropertyValue::Float(*value as f32),
            AttributeValue::Int(value) => PropertyValue::Integer(*value),
            AttributeValue::Bool(value) => PropertyValue::Bool(*value),
            AttributeValue::None => PropertyValue::None,
            // A drawing command list is the one value that is neither a number nor text.
            // dioxus-core compares it before calling here, so an unchanged list never
            // reaches this point and costs no record.
            AttributeValue::Any(value) => {
                let any = value.as_any();
                if let Some(list) = any.downcast_ref::<DrawList>() {
                    PropertyValue::Bytes(list.as_bytes())
                } else if let Some(spans) = any.downcast_ref::<crate::spans::TextSpans>() {
                    // Runs inside a string travel the same way a drawing does, and for the
                    // same reason: a list that has not changed compares equal before it
                    // reaches here and costs no record at all.
                    PropertyValue::Bytes(spans.as_bytes())
                } else {
                    return;
                }
            }
            AttributeValue::Listener(_) => return,
        };
        let neutral = matches!(
            value,
            PropertyValue::None | PropertyValue::Integer(0) | PropertyValue::Float(0.0)
        );
        if !self.should_write_optional_property(node_id, property, neutral) {
            return;
        }
        self.write(Mutation::SetProp {
            node_id,
            property,
            value,
        });
    }

    /// One past the last position under `parent`.
    fn end_of(&self, parent: u32) -> usize {
        self.children.get(&parent).map_or(0, Vec::len)
    }

    /// Stands a marker in a template's dynamic child until its content arrives, and says
    /// which marker it was.
    fn reserve_slot(&mut self, parent: u32) -> u32 {
        let marker = self.next_marker;
        self.next_marker = self.next_marker.checked_add(1).unwrap_or(1);
        self.children
            .entry(parent)
            .or_default()
            .push(Slot::Pending(marker));
        marker
    }

    /// Where the given slot stands: the parent it hangs under and its position in that
    /// parent's list.
    fn locate(&self, slot: Slot) -> Option<(u32, usize)> {
        let parent = match slot {
            Slot::Node(node_id) => *self.parents.get(&node_id)?,
            Slot::Hole(element) => *self.placeholders.get(&element)?,
            Slot::Pending(_) => return None,
        };
        let position = self
            .children
            .get(&parent)?
            .iter()
            .position(|standing| *standing == slot)?;
        Some((parent, position))
    }

    /// How many drawn nodes stand before `position` under `parent`, which is the index
    /// the Renderer understands.
    fn drawn_before(&self, parent: u32, position: usize) -> u32 {
        self.children.get(&parent).map_or(0, |list| {
            list.iter()
                .take(position)
                .filter(|slot| matches!(slot, Slot::Node(_)))
                .count() as u32
        })
    }

    /// Takes the slot out of wherever it stands, and says where that was.
    fn detach(&mut self, slot: Slot) -> Option<(u32, usize)> {
        let (parent, position) = self.locate(slot)?;
        if let Some(list) = self.children.get_mut(&parent) {
            list.remove(position);
        }
        Some((parent, position))
    }

    /// Puts the slot under `parent` at `position`, and says which position it took.
    fn attach(&mut self, parent: u32, slot: Slot, position: usize) -> usize {
        let mut position = position;
        if let Some((from, was_at)) = self.detach(slot) {
            if from == parent && was_at < position {
                position -= 1;
            }
        }
        let list = self.children.entry(parent).or_default();
        let position = position.min(list.len());
        list.insert(position, slot);
        match slot {
            Slot::Node(node_id) => {
                self.parents.insert(node_id, parent);
            }
            Slot::Hole(element) => {
                self.placeholders.insert(element, parent);
            }
            Slot::Pending(_) => {}
        }
        position
    }

    /// Forgets a node and everything under it, as the Renderer does when it is removed.
    /// The caller has already taken the node out of its parent's list.
    fn forget(&mut self, node_id: u32) {
        self.parents.remove(&node_id);
        for slot in self.children.remove(&node_id).unwrap_or_default() {
            match slot {
                Slot::Node(child) => self.forget(child),
                Slot::Hole(element) => {
                    self.placeholders.remove(&element);
                }
                Slot::Pending(_) => {}
            }
        }
    }

    fn insert_stack(&mut self, parent: u32, position: usize, count: usize) {
        let start = self.stack.len().saturating_sub(count);
        let nodes: Vec<_> = self.stack.drain(start..).collect();
        let mut at = position;
        for node in nodes {
            at = self.insert_node(parent, node.node_id, at, node.element) + 1;
        }
    }

    /// Puts one entry under `parent` at `position` and tells the Renderer about it,
    /// unless nothing is drawn for it. Says which position it took.
    fn insert_node(
        &mut self,
        parent: u32,
        node_id: u32,
        position: usize,
        element: Option<ElementId>,
    ) -> usize {
        if node_id == PLACEHOLDER_NODE {
            // Nothing is drawn for a placeholder, so nothing is sent. It still holds its
            // position here, so the branch that fills it in takes that position rather
            // than the end of the list.
            let Some(element) = element else {
                return position;
            };
            return self.attach(parent, Slot::Hole(element.0), position);
        }
        let moving = self.parents.contains_key(&node_id);
        let at = self.attach(parent, Slot::Node(node_id), position);
        let index = self.drawn_before(parent, at);
        self.write(if moving {
            Mutation::Move {
                parent_id: parent,
                node_id,
                index,
            }
        } else {
            Mutation::Insert {
                parent_id: parent,
                node_id,
                index,
            }
        });
        at
    }

    /// Where the given element stands: its own position, or its placeholder's.
    fn slot_of(&self, id: ElementId) -> Option<(u32, usize)> {
        match self.node(id) {
            Some(PLACEHOLDER_NODE) | None => self.locate(Slot::Hole(id.0)),
            Some(node_id) => self.locate(Slot::Node(node_id)),
        }
    }
}

impl WriteMutations for ComposeRenderer {
    fn append_children(&mut self, id: ElementId, m: usize) {
        if let Some(parent) = self.node(id) {
            let end = self.end_of(parent);
            self.insert_stack(parent, end, m);
        }
    }

    fn assign_node_id(&mut self, path: &'static [u8], id: ElementId) {
        if let Some(PathTarget::Node(node_id)) = self
            .stack
            .last()
            .and_then(|loaded| loaded.paths.get(path))
            .copied()
        {
            self.map_node(id, node_id);
        }
    }

    fn create_placeholder(&mut self, id: ElementId) {
        // A Dioxus placeholder is not materialized in the Compose tree. It is
        // represented by its eventual insertion position.
        self.map_node(id, PLACEHOLDER_NODE);
        self.stack.push(StackNode {
            node_id: PLACEHOLDER_NODE,
            element: Some(id),
            paths: HashMap::new(),
        });
    }

    fn create_text_node(&mut self, value: &str, id: ElementId) {
        let node_id = self.allocate_node(WidgetKind::Text);
        self.map_node(id, node_id);
        self.write(Mutation::SetProp {
            node_id,
            property: PropertyKind::Text,
            value: PropertyValue::String(value),
        });
        self.stack.push(StackNode {
            node_id,
            element: None,
            paths: HashMap::new(),
        });
    }

    fn load_template(&mut self, template: Template, index: usize, id: ElementId) {
        let mut paths = HashMap::new();
        let mut path = Vec::new();
        if let Some(root) = self.build_template_node(&template.roots[index], &mut path, &mut paths)
        {
            self.map_node(id, root);
            self.stack.push(StackNode {
                node_id: root,
                element: None,
                paths,
            });
        }
    }

    fn replace_node_with(&mut self, id: ElementId, m: usize) {
        if let Some(node_id) = self.node(id) {
            let target = self.slot_of(id);
            if node_id == PLACEHOLDER_NODE {
                self.detach(Slot::Hole(id.0));
                self.placeholders.remove(&id.0);
            } else {
                self.detach(Slot::Node(node_id));
                self.write(Mutation::Remove { node_id });
                self.forget(node_id);
            }
            // The slot has just been taken out, so what replaces it goes in at the
            // position it held.
            if let Some((parent, position)) = target {
                self.insert_stack(parent, position, m);
                return;
            }
        }
        let keep_from = self.stack.len().saturating_sub(m);
        self.stack.drain(..keep_from);
    }

    fn replace_placeholder_with_nodes(&mut self, path: &'static [u8], m: usize) {
        let parent_position = self.stack.len().saturating_sub(m + 1);
        let target = self
            .stack
            .get(parent_position)
            .and_then(|loaded| loaded.paths.get(path))
            .copied();
        if let Some(PathTarget::Slot { parent, marker }) = target {
            let Some(position) = self
                .children
                .get(&parent)
                .and_then(|list| list.iter().position(|slot| *slot == Slot::Pending(marker)))
            else {
                return;
            };
            if let Some(list) = self.children.get_mut(&parent) {
                list.remove(position);
            }
            self.insert_stack(parent, position, m);
        }
    }

    fn insert_nodes_after(&mut self, id: ElementId, m: usize) {
        if let Some((parent, position)) = self.slot_of(id) {
            self.insert_stack(parent, position + 1, m);
        }
    }

    fn insert_nodes_before(&mut self, id: ElementId, m: usize) {
        if let Some((parent, position)) = self.slot_of(id) {
            self.insert_stack(parent, position, m);
        }
    }

    fn set_attribute(
        &mut self,
        name: &'static str,
        _namespace: Option<&'static str>,
        value: &AttributeValue,
        id: ElementId,
    ) {
        if let Some(node_id) = self.node(id) {
            if let Some(slot) = self.modifier_for(id, node_id, name, value) {
                if let Some((index, modifier)) = slot {
                    self.write(Mutation::SetModifier {
                        node_id,
                        index,
                        modifier,
                    });
                }
                return;
            }
            self.set_property(node_id, name, value);
        }
    }

    fn set_node_text(&mut self, value: &str, id: ElementId) {
        if let Some(node_id) = self.node(id) {
            self.write(Mutation::SetProp {
                node_id,
                property: PropertyKind::Text,
                value: PropertyValue::String(value),
            });
        }
    }

    fn create_event_listener(&mut self, name: &'static str, id: ElementId) {
        let Some(node_id) = self.node(id) else {
            return;
        };
        let handler_id = self.next_handler_id;
        self.next_handler_id += 1;
        self.handlers.push(Handler {
            id: handler_id,
            element: id,
            node_id,
            name,
        });
        if let Some(property) = event_property(name) {
            self.write(Mutation::SetProp {
                node_id,
                property,
                value: PropertyValue::Integer(handler_id as i64),
            });
        }
    }

    fn remove_event_listener(&mut self, name: &'static str, id: ElementId) {
        let Some(position) = self
            .handlers
            .iter()
            .position(|handler| handler.element == id && handler.name == name)
        else {
            return;
        };
        self.handlers.swap_remove(position);
        if let (Some(node_id), Some(property)) = (self.node(id), event_property(name)) {
            self.write(Mutation::SetProp {
                node_id,
                property,
                value: PropertyValue::None,
            });
        }
    }

    fn remove_node(&mut self, id: ElementId) {
        self.detach(Slot::Hole(id.0));
        self.placeholders.remove(&id.0);
        if let Some(node_id) = self.node(id) {
            if node_id != PLACEHOLDER_NODE {
                self.detach(Slot::Node(node_id));
                self.write(Mutation::Remove { node_id });
                self.forget(node_id);
            }
        }
        if let Some(slot) = self.nodes.get_mut(id.0) {
            *slot = None;
        }
        self.handlers.retain(|handler| handler.element != id);
    }

    fn push_root(&mut self, id: ElementId) {
        if let Some(node_id) = self.node(id) {
            self.stack.push(StackNode {
                node_id,
                element: Some(id),
                paths: HashMap::new(),
            });
        }
    }
}

fn widget_kind(name: &str) -> Result<WidgetKind, ProtocolError> {
    WidgetKind::from_name(name).map_err(|()| ProtocolError::InvalidWidget(0))
}

fn property_kind(name: &str) -> Option<PropertyKind> {
    PropertyKind::from_name(name).ok()
}

fn event_property(name: &str) -> Option<PropertyKind> {
    match name {
        "click" | "onclick" => Some(PropertyKind::OnClick),
        "valuechange" | "onvaluechange" => Some(PropertyKind::OnValueChange),
        "submit" | "onsubmit" => Some(PropertyKind::OnSubmit),
        "focuslost" | "onfocuslost" => Some(PropertyKind::OnFocusLost),
        "keydown" | "onkeydown" => Some(PropertyKind::OnKeyDown),
        "rangerequest" | "onrangerequest" => Some(PropertyKind::OnRangeRequested),
        "dismiss" | "ondismiss" => Some(PropertyKind::OnDismiss),
        "filesentered" | "onfilesentered" => Some(PropertyKind::OnFilesEntered),
        "filesdropped" | "onfilesdropped" => Some(PropertyKind::OnFilesDropped),
        "change" | "onchange" => Some(PropertyKind::OnValueChange),
        _ => None,
    }
}

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

    fn app() -> Element {
        rsx! {
            Column {
                Text { text: "zero" }
                TextField { placeholder: "type" }
                Button { text: "increment", on_click: move |_| {} }
            }
        }
    }

    #[test]
    /// The M0 screen written as `rsx!` produces the same tree the protocol describes.
    ///
    /// Named after the requirement now. It was the only test standing behind that
    /// requirement and it did not say so, so counting the tests named for each one
    /// reported none and the requirement read as unimplemented.
    fn fr6_an_rsx_component_builds_the_same_tree() {
        let mut dom = VirtualDom::new(app);
        let mut renderer = ComposeRenderer::new();
        dom.rebuild(&mut renderer);
        let decoded = crate::protocol::decode_batch(renderer.finish_frame().unwrap()).unwrap();
        eprintln!("{decoded:#?}");
        assert!(decoded.iter().any(|mutation| matches!(
            mutation,
            Mutation::Create {
                widget: WidgetKind::Column,
                ..
            }
        )));
        assert!(decoded.iter().any(|mutation| matches!(
            mutation,
            Mutation::Create {
                widget: WidgetKind::TextField,
                ..
            }
        )));
        assert_eq!(
            decoded
                .iter()
                .filter(|mutation| matches!(mutation, Mutation::Insert { .. }))
                .count(),
            3
        );
    }
}