//! Nodes to markup.
//!
//! Every function here takes a piece of [`quasi_router`]'s screen tree and
//! pushes markup onto a buffer. Nothing returns a `Result`: a description that
//! exists is renderable by construction, which is the property the owned mirror
//! in `quasi-router` was built to have.
//!
//! # Where the htmx goes in
//!
//! In exactly one function, [`action_attrs`]. An [`Action`] is a method, a path
//! and some params, and turning that into `hx-get` / `hx-post` / `hx-vals` is
//! the whole of what "htmx is the transport" means in code. Nothing else in
//! this file knows the word htmx, so decision 13's claim that the transport is
//! replaceable is a claim about one function rather than about the crate.
//!
//! `hx-target` is emitted for one case and only one: [`Action::replaces`], set
//! when a control calls a route the description layer does not serve. Decision 7
//! puts the target on the response, where `quasi-http` sets `HX-Retarget` from
//! [`Response::Fragment`](quasi_router::Response::Fragment), because the router
//! is the only party that knows what it just changed, and a control that also
//! named a target would be a second party deciding one thing. That reasoning
//! assumes the responder is described. A plain API route is not, cannot name a
//! region, and leaves the answer to land wherever the transport defaults, which
//! for htmx is inside the pressed button. See `Action::replaces` for the whole
//! of it.

use std::collections::HashMap;
use std::fmt::Write as _;

use makeover_layout as layout;
// `Tone::token` is the trait method, and `data-tone` is spelled from it rather
// than from a match here, so a tone added upstream cannot be named two ways.
use makeover_layout::Intent as _;
use makeover_webview::figure::figure_html_into;
use makeover_webview::form::{Filling, Markup, Value, escape_into, field_html_into};
// `class`, `option_class` and the two part-class mappings below are makeover's,
// not copies of it. They were copies until makeover-webview 0.27.0 made them
// public: the prefix helper was byte-identical, and the row and cell part names
// were a second spelling of a list whose own doc comment carries an obligation
// to be grepped on upgrade. A second spelling is a second place to forget, and
// the selector names had already drifted.
use makeover_webview::{Emit, class, option_class};
// `Cell` is a name both crates use: makeover's is the emitted table cell, ours
// is the described one. Aliased rather than qualified at the call site, so the
// two never read as the same type.
use makeover_webview::list::{
    Cell as Emitted, cell_part_class, cells_html_into, part_class, push_column_classes,
};
use makeover_webview::meter::meter_html_into;
use makeover_webview::placeholder::placeholder_html_into;
use quasi_router::screen::{Act, Cell, Cells, Destination, Field, Node, Row, Slot, Tag};
use quasi_router::{Action, Method, Params};

/// Write one prefixed class name onto a buffer the caller already has.
///
/// The two halves are escaped separately rather than joined and escaped once.
/// That is the same bytes -- escaping is per character and has no context to
/// carry across the seam -- for none of the allocations. Every class of every
/// element went through a `format!` and then a second `String` before this
/// existed, which measured as most of the emitter's allocation count.
///
/// Escaped at all because a prefix is host configuration reaching an attribute
/// value. It is a `&'static str` and every real one is identity under this, so
/// the cost is a scan; what it buys is that the one string here that did not
/// come from this crate cannot end the attribute.
pub(crate) fn class_into(name: &str, opts: &Emit, out: &mut String) {
    escape_into(opts.class_prefix, out);
    escape_into(name, out);
}

/// Write a `class="..."` attribute, prefixed.
fn class_attr(names: &[&str], opts: &Emit, out: &mut String) {
    out.push_str(" class=\"");
    for (i, name) in names.iter().enumerate() {
        if i > 0 {
            out.push(' ');
        }
        class_into(name, opts, out);
    }
    out.push('"');
}

/// Write the attribute naming a tone, if the tone is worth naming.
///
/// [`Tone::Neutral`] writes nothing: ordinary content is the default, and an
/// attribute meaning "nothing unusual" is an attribute on every element in the
/// document.
///
/// An attribute and not a class, which is the correction. This emitted
/// `tone-info`, `tone-success`, `tone-warning` and `tone-danger` as classes, and
/// makeover has never defined one of them: its whole vocabulary keys tone off
/// `data-tone`, from `.badge[data-tone="danger"]` to the progress fill to a
/// figure's value. So every toned thing a description produced arrived with a
/// class no stylesheet in the tree had heard of, which is why the SSH-keys tab's
/// Remove button came out the same colour as everything else.
fn tone_attr(tone: layout::Tone, out: &mut String) {
    if matches!(tone, layout::Tone::Neutral) {
        return;
    }
    out.push_str(" data-tone=\"");
    out.push_str(tone.token());
    out.push('"');
}

/// How a picture sits in its box, where it is not the default.
///
/// `tone_attr`'s shape and for its reason: `Natural` is what an `<img>` does
/// with no rule at all, so saying it would be a stylesheet hook that changes
/// nothing. The two that need a rule get one.
fn fit_attr(fit: layout::Fit, out: &mut String) {
    let value = match fit {
        layout::Fit::Natural => return,
        layout::Fit::Cover => "cover",
        layout::Fit::Contain => "contain",
        // `Fit` is `#[non_exhaustive]`, so a member added upstream lands here
        // rather than failing the build. Drawing it as natural is the safe
        // read: the picture is whole and its own shape, which is wrong about
        // the box and never wrong about the content.
        _ => return,
    };
    out.push_str(" data-fit=\"");
    out.push_str(value);
    out.push('"');
}

/// What goes back in the box, for a form being offered again after a refusal.
///
/// `1c4a66a4`. The description carries the value as a string, because that is
/// what came off the wire; the kind is what says how to read it. A checkbox is
/// carried by presence the way HTML submits one, so any value means ticked and
/// nothing means not.
///
/// A [`layout::FieldKind::Secret`] is emitted empty whatever it holds. That is
/// the third refusal of the same thing and none of the three is redundant:
/// `Field::value` will not store one, `makeover_webview::form` will not write
/// one into an `<input type="password">`, and this one stands between them
/// because `Field::value` is a public field that a struct literal reaches past.
fn refill(field: &Field) -> Value<'_> {
    if field.kind == layout::FieldKind::Secret {
        return Value::Absent;
    }
    match field.value.as_deref() {
        None => Value::Absent,
        Some(_) if field.kind == layout::FieldKind::Checkbox => Value::On(true),
        Some(value) => Value::Text(value),
    }
}

/// One field, with whatever `1c4a66a4` and `14612ed8` added around it.
///
/// The field's own markup is makeover-webview's, unchanged. A second field
/// emitter here is the divergence phase A existed to end, and it would be the
/// same anatomy with a different escaping story.
///
/// A [`Field::changes`] is a wrapper rather than attributes on the control,
/// because the control is emitted by makeover-webview and there is no seam to
/// put them through. That turns out to be the better shape anyway: the `change`
/// event bubbles, so one element around the group catches it whichever of the
/// input, select or textarea forms the field took, and `hx-include` finds the
/// control back without this having to know which it was.
fn field_group_html(field: &Field, morphs: bool, opts: &Emit, out: &mut String) {
    let filling = Filling::of(refill(field));
    let writes = field.changes.as_ref();

    if let Some(action) = writes {
        out.push_str("<div");
        class_attr(&["field-writes"], opts, out);
        action_attrs(action, Fires::ChangeInside, None, morphs, None, out);
        out.push('>');
    }

    field.with_layout(|borrowed| {
        field_html_into(&borrowed, &filling, opts, out);
    });

    if writes.is_some() {
        out.push_str("</div>");
    }
}

/// Markdown source into markup, for [`Node::Rich`].
///
/// The strict preset, which is a deliberate difference from the
/// `render_standard` goingson's own JS calls: standard lets sanitised raw HTML
/// through, and a shared renderer taking text a user typed should be the safer
/// of the two by default. What it costs is angle brackets in a description
/// rendering as text rather than as markup, which is the outcome
/// [`Node::Text`] would have given anyway.
///
/// Unconditional. This sat behind a default-on `rich` feature until markdown
/// was made standard, and turning the feature off did not remove a cost so much
/// as produce a renderer that draws `**bold**` at the user. Markdown is what
/// these descriptions are made of, so rendering it is part of being a renderer
/// rather than an extra somebody opts into.
fn rich_html(source: &str) -> String {
    docengine::render_strict(source)
}

/// JSON-encode a string into an attribute value, both rules in one pass.
///
/// Small enough to own. Pulling in a JSON crate to write object literals of
/// strings would be the larger decision, and the encoder a renderer needs is
/// this: the six characters JSON requires escaped, plus a `\u00XX` form for the
/// rest of the C0 range.
///
/// The HTML escaping is applied here rather than by the caller, which is what
/// lets the payload go straight into `out`. Building the object and then
/// escaping the whole of it allocated a `String` for each, per action, and
/// there was nothing in between to look at.
///
/// The two rules compose in this order and only this order. JSON runs first, so
/// a quote in the text becomes `\"` and then `\&quot;`; the backslash JSON adds
/// is not a character HTML encodes, and the quote HTML encodes is not one JSON
/// would look at twice. The structural quotes the object needs are written as
/// `&quot;` directly, because they are markup rather than content.
fn json_string_attr(text: &str, out: &mut String) {
    out.push_str("&quot;");
    for ch in text.chars() {
        match ch {
            // JSON first, then the HTML form of what it produced.
            '"' => out.push_str("\\&quot;"),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            c if (c as u32) < 0x20 => {
                let _ = write!(out, "\\u{:04x}", c as u32);
            }
            // The rest of what an attribute value cannot carry. JSON has no
            // opinion on any of these, so this arm is HTML's alone and matches
            // `escape_into` character for character.
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '\'' => out.push_str("&#39;"),
            c => out.push(c),
        }
    }
    out.push_str("&quot;");
}

/// The params as an `hx-vals` object, written into the attribute they land in.
fn json_object_attr(params: &Params, out: &mut String) {
    out.push('{');
    for (i, (name, value)) in params.iter().enumerate() {
        if i > 0 {
            out.push(',');
        }
        json_string_attr(name, out);
        out.push(':');
        json_string_attr(value, out);
    }
    out.push('}');
}

/// What makes a control call its action.
///
/// Here rather than at the call sites because every `hx-` attribute this crate
/// emits has to come out of one function, which is decision 13's claim that the
/// transport is replaceable and is asserted by a test.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Fires<'a> {
    /// The user activating the control. htmx's default for a button or a link.
    Click,
    /// The control's own value changing. What a checkbox that is itself the
    /// write does.
    Change,
    /// The value of a control *inside* this element changing.
    ///
    /// A field group, whose control is emitted by makeover-webview and has no
    /// seam to hang attributes on. The `change` event bubbles, so the wrapper
    /// catches it whichever of input, select or textarea the field turned out to
    /// be, and the value is found back rather than assumed.
    ChangeInside,
    /// A key pressed anywhere in the document.
    ///
    /// What a [`Chrome`](quasi_router::Chrome) binding is: it belongs to no
    /// element, so it listens on the body rather than on itself. The string is
    /// the filter over `KeyboardEvent`, built by `crate::chrome` because
    /// reading a key name is the host's job.
    Key(&'a str),
    /// The user clicking the element, but not a control inside it.
    ///
    /// `022f0c59`. A table row carries its `activate` on the row itself, unlike
    /// a list row, which hangs it on the primary text and so has never had this
    /// problem. Once a cell can hold a control, a click on that control bubbles
    /// to the row and htmx fires both: pressing Remove would delete the key and
    /// open it. The filter is on the row rather than a `stopPropagation` on the
    /// button because the row is the element making the wrong assumption, and a
    /// button that swallows events breaks anything else listening above it.
    ClickBeside,
}

/// The transport attributes for one action.
///
/// # The two bags land in two places, and that is the point
///
/// An action carries what the control sends (`params`) and the view it was
/// offered under (`carried`), and htmx has a slot for each: the address takes
/// the view, `hx-vals` takes the payload. So a write to a filtered list emits
/// `hx-post="/problems/{id}/status?status=Open"` with
/// `hx-vals='{"status":"Dismissed"}'`, and the two `status` values never meet.
///
/// Until 2026-08-10 both bags were one and both went through `hx-vals`, which
/// could hold neither. `hx-vals` is a JSON object literal, so two entries under
/// one name emitted a duplicate key and every parser kept the last — inverting
/// [`Params::get`]'s first-wins rule the moment a value crossed the wire, and
/// silently dropping every repeat that [`Params::get_all`] exists to carry.
/// Folding the view into the address fixes both: a query string repeats a name
/// happily, and it is the half that wanted to be in the URL anyway.
///
/// Nothing here concatenates a `?`. [`quasi_http::route_url`] does that, in one
/// place, with a real encoder, because hand-built query strings are where
/// escaping bugs live.
pub(crate) fn action_attrs(
    action: &Action,
    fires: Fires,
    confirm: Option<&str>,
    morphs: bool,
    gathers: Option<&str>,
    out: &mut String,
) {
    // An external destination is not htmx's business: nothing swaps, no route
    // is called, and the browser follows a normal link. `rel` rather than
    // trust: a new tab with `window.opener` left intact hands the other page a
    // handle on this one.
    if let Destination::External(url) = &action.destination {
        out.push_str(" href=\"");
        escape_into(url, out);
        out.push_str("\" target=\"_blank\" rel=\"noopener noreferrer\"");
        return;
    }

    // The address, built once. The `href` below and the verb further down are
    // the same string whenever both are emitted -- a read of a route names one
    // place -- and building it twice was a `String` per link on every screen
    // made mostly of links.
    let url = quasi_http::route_url(action.destination.as_str(), &action.carried);

    // A read of a route this app answers is a link, and it gets the address as
    // well as the transport. htmx uses `hx-get` and prevents the default, so
    // the `href` is what everything else uses: middle-click, copy-link, a
    // crawler, and the page with JS off. The parameters are folded into it
    // because a link to a filtered list that drops the filter is a different
    // place, and `hx-vals` below carries the same ones down htmx's path.
    if matches!(action.destination, Destination::Route(_)) && !action.method.mutates() {
        out.push_str(" href=\"");
        escape_into(&url, out);
        out.push('"');
    }

    // Everything the screen's selection has ticked, gathered by the selector
    // the caller built. `5f2b8753`: this is the whole of what the per-app JS
    // used to do, and it is declarative because a checkbox already submits its
    // own name and value -- all that was missing was something saying which
    // boxes belong together.
    //
    // Here rather than in `act_html` because it is htmx, and htmx entering this
    // crate anywhere else is what the architectural test forbids.
    if let Some(selector) = gathers {
        out.push_str(" hx-include=\"");
        escape_into(selector, out);
        out.push('"');
    }

    // Where the answer goes, when the responder is not ours to ask. Emitted
    // before the verb so the attributes read in the order they are reasoned
    // about: where it lands, then what is sent.
    if let Some(region) = &action.replaces {
        out.push_str(" hx-target=\"#");
        escape_into(region, out);
        out.push('"');
    }

    // The answer is a file the reader keeps, not a view. On a link the browser
    // does the whole job from the attribute, so nothing else is needed and the
    // control still works with JS off. On a write it cannot: a response has to
    // be performed before it can be saved, so this is a named hook the host
    // acts on, in the same spirit as `data-act` and for the same reason it is an
    // attribute rather than a class. The host handles one attribute instead of
    // a per-button behaviour named by a class and two positional arguments.
    if let Some(filename) = &action.saves {
        if is_link(action) {
            out.push_str(" download=\"");
        } else {
            out.push_str(" data-saves=\"");
        }
        escape_into(filename, out);
        out.push('"');
    }

    let verb = match action.method {
        Method::Get => " hx-get=\"",
        Method::Post => " hx-post=\"",
        Method::Delete => " hx-delete=\"",
        Method::Put => " hx-put=\"",
    };
    out.push_str(verb);
    escape_into(&url, out);
    out.push('"');

    if !action.params.is_empty() {
        out.push_str(" hx-vals=\"");
        json_object_attr(&action.params, out);
        out.push('"');
    }

    // Named even where it matches htmx's own default for the element, so the
    // markup says what it does rather than resting on a default holding.
    match fires {
        Fires::Click => {}
        // `data-act` and not the class, so the filter does not depend on
        // `Emit::class_prefix` and does not break when a host sets one. Same
        // reasoning as `data-menu` on a row's menu.
        Fires::ClickBeside => out.push_str(concat!(
            " hx-trigger=\"click[!event.target.closest(",
            "&#39;[data-act]&#39;)]\""
        )),
        Fires::Change => out.push_str(" hx-trigger=\"change\""),
        Fires::Key(filter) => {
            // `from:body`, because the element is hidden and never focused: a
            // trigger on itself would wait for a keystroke it can never
            // receive.
            out.push_str(" hx-trigger=\"keydown[");
            escape_into(filter, out);
            out.push_str("] from:body\"");
        }
        Fires::ChangeInside => {
            out.push_str(" hx-trigger=\"change\"");
            out.push_str(" hx-include=\"find input, find select, find textarea\"");
        }
    }

    // Asking before acting is transport here, same as the verb: htmx gates the
    // request on it. That is also why it lands in this function rather than
    // beside the label — every `hx-` attribute this crate emits comes from one
    // place, or swapping htmx for fixi stops being a one-function change.
    if let Some(prompt) = confirm {
        out.push_str(" hx-confirm=\"");
        escape_into(prompt, out);
        out.push('"');
    }

    if morphs {
        // Decision 7's slack: a morph preserves focus, scroll and input state
        // through a swap, so a whole-Screen answer stops being destructive.
        out.push_str(" hx-swap=\"morph\"");
    }
}

/// Whether an action is somewhere to go rather than something to do.
///
/// Two ways to be a link. An external destination leaves. A read of a route
/// this app answers is also a link: it has an address, it can be visited
/// directly, and nothing changes because it was.
///
/// A write is never a link however it is spelled, which is the whole of the
/// other side. An anchor is something a browser may prefetch and a crawler will
/// follow, and neither is allowed to delete a task.
const fn is_link(action: &Action) -> bool {
    action.destination.is_external() || !action.method.mutates()
}

/// The element a control becomes.
///
/// A link is an anchor and a write is a button, and a button that navigates is
/// a button lying to everything that reads the page: middle-click, copy-link,
/// a crawler and a screen reader included. This keyed on external-or-not until
/// the read case was separated out, which made every internal navigation a
/// control that only worked by running JavaScript first.
///
/// Branching on the [`Destination`] variant and never on the shape of the
/// string is the rule `Destination`'s own docs set. "Starts with https" is how a
/// route named `/https-setup` ends up opening a browser.
const fn control_tag(action: &Action) -> (&'static str, &'static str) {
    if is_link(action) {
        ("<a", "</a>")
    } else {
        ("<button type=\"button\"", "</button>")
    }
}

/// A control that calls a route.
pub(crate) fn act_html(act: &Act, morphs: bool, opts: &Emit, out: &mut String) {
    // The commit control for a staged selection gathers every tick on the
    // screen. One selector rather than a name per box: a screen holds one set
    // (`Screen::selection`), so the class the ticks already carry is what they
    // have in common. Built here because it needs `Emit`, which the transport
    // function does not take -- a host setting `class_prefix` moves the class
    // and the selector together.
    //
    // Built inside the `map` and not before it: staged selections are rare and
    // every other control on the screen was paying for two `String`s it then
    // dropped. `class` rather than `class_into` because what is wanted here is
    // a value, and a selector is the one place this crate holds one.
    let gathers = act
        .over
        .as_ref()
        .map(|_| format!(".{}", class("row-select", opts)));
    let gathers = gathers.as_deref();
    // `button`, which is makeover's name for this and carries its whole
    // interactive set: the raised bevel, the hover fill, the pressed inset, the
    // focus ring and the disabled treatment. This emitted `act`, a second name
    // for the same thing that no stylesheet in the tree defined, so a described
    // control rendered as unstyled text. There was never a concept here that
    // `button` was not already the word for.
    let (open, close) = control_tag(&act.action);
    out.push_str(open);
    class_attr(&["button"], opts, out);
    tone_attr(act.tone, out);
    // Named rather than found by class, so anything binding to "this is a
    // control" survives a host setting `Emit::class_prefix`. `Fires::ClickBeside`
    // is the first reader; a table row uses it to tell its own click apart from
    // a press on a button sitting inside one of its cells.
    out.push_str(" data-act");

    match act.state {
        Some(layout::State::Disabled) => {
            // Disabled and emitting no transport, rather than disabled and
            // still carrying the address. A control that stops answering input
            // should also stop being a request waiting to be re-enabled from
            // the console.
            //
            // An anchor has no `disabled`, and omitting the href is what
            // actually stops it: an `<a>` without one is not a link, so it
            // drops out of the tab order on its own. `aria-disabled` is what
            // says why, since a bare span-shaped anchor says nothing.
            if is_link(&act.action) {
                out.push_str(" aria-disabled=\"true\"");
            } else {
                out.push_str(" disabled");
            }
        }
        // No `autofocus` arm. A description does not state focus: the browser
        // owns reach and focus here, which is what `makeover-layout` 0.19.0
        // settled by removing the member this used to read.
        //
        // `State` is `#[non_exhaustive]`, so a member added upstream lands
        // here. Emitting the transport is the right default for anything that
        // is not a suppression: a state this renderer has not learned yet
        // should leave the control working, not silently inert.
        _ => action_attrs(
            &act.action,
            Fires::Click,
            act.confirm.as_deref(),
            morphs,
            gathers,
            out,
        ),
    }

    // The confirmation rides with the transport, in `action_attrs`. The key does
    // not: `accesskey` is plain HTML and no part of htmx. It is emitted even
    // though a browser makes little of it, because a key is the affordance in a
    // terminal and this is the nearest honest thing a page has.
    if let Some(key) = &act.key {
        out.push_str(" accesskey=\"");
        escape_into(key, out);
        out.push('"');
    }

    out.push('>');
    escape_into(&act.label, out);
    out.push_str(close);
}

/// One row of a list.
fn row_html(row: &Row, morphs: bool, opts: &Emit, out: &mut String) {
    let mut classes = vec!["row"];
    if row.current {
        classes.push("row-current");
    }
    if row.selected == Some(true) {
        classes.push("row-selected");
    }

    out.push_str("<li");
    class_attr(&classes, opts, out);
    if row.current {
        // `current` is what the detail side is showing: a current item within a
        // set rather than a pressed control, and rather than anything the user
        // ticked. That distinction is why the description carries two fields.
        out.push_str(" aria-current=\"true\"");
    }
    out.push('>');

    // The tick, when the row is selectable at all. A real checkbox rather than
    // a styled span: it is the one control here the browser already gets right,
    // including the label association, the space key and the mixed state a
    // screen reader announces.
    if let Some(ticked) = row.selected {
        out.push_str("<input type=\"checkbox\"");
        class_attr(&["row-select"], opts, out);
        if ticked {
            out.push_str(" checked");
        }
        // What the tick contributes to the screen's selection, under the one
        // name a handler reads it back by. `5f2b8753`: the app used to bind
        // this itself, gathering the checked boxes in JS, because nothing in
        // the description said what the ticks were for.
        //
        // Named rather than left to the browser's `on`, which is what a
        // checkbox with no value submits. `on` says a box was checked and not
        // which one.
        if let Some(value) = &row.value {
            out.push_str(" name=\"");
            escape_into(quasi_router::Node::TICKED, out);
            out.push_str("\" value=\"");
            escape_into(value, out);
            out.push('"');
        }
        // A tick with no route is local state until something submits it, which
        // is what a bulk checkbox is; the app binds those itself. A tick with
        // one is the write, which is `14612ed8`, and htmx's own default trigger
        // for an input is `change` — named anyway, so the markup says what it
        // does rather than relying on a default holding.
        if let Some(action) = &row.toggle {
            action_attrs(action, Fires::Change, None, morphs, None, out);
        }
        out.push_str(" aria-label=\"Select\">");
    }

    // A span per run of consecutive parts sharing a role, rather than a fixed
    // sequence of members. The old shape drew primary, secondary, meta, bar,
    // tokens, actions in that order however the description was built; the run
    // draws what it was given where it was put, and a row with a tag between
    // two facts now says so.
    //
    // Consecutive same-role parts share one wrapping span for the reason a
    // cell's tokens do: the part class carries the gap between siblings, so a
    // span each would space two badges as though they were unrelated.
    let mut rest = row.parts.as_slice();
    while let Some(head) = rest.first() {
        let role = head.role;
        let taken = rest.iter().take_while(|part| part.role == role).count();
        let (group, tail) = rest.split_at(taken);
        row_part_html(row, role, group, morphs, opts, out);
        rest = tail;
    }

    // After the run, because a menu is not on the line: it is the set of things
    // that can be done to the row, and it renders as a container the host opens
    // its own way. A webview hangs a context menu off it, a touch host an action
    // sheet, a terminal a key-driven list; all three read the same acts.
    if !row.menu.is_empty() {
        out.push_str("<div");
        class_attr(&["row-menu"], opts, out);
        // Named rather than hidden by class, so the host's own menu code has
        // something to bind to that does not depend on how it is styled.
        out.push_str(" data-menu=\"row\" hidden>");
        for act in &row.menu {
            act_html(act, morphs, opts, out);
        }
        out.push_str("</div>");
    }

    out.push_str("</li>");
}

/// One run of consecutive row parts sharing a role.
fn row_part_html(
    row: &Row,
    role: layout::RowPart,
    group: &[quasi_router::Part],
    morphs: bool,
    opts: &Emit,
    out: &mut String,
) {
    // The primary is a control when selecting the row does something, and plain
    // text when it does not. Emitting a button either way would give a screen
    // reader an affordance that answers nothing. `activate` stayed a field
    // through the run migration, so this is still the row's own answer rather
    // than something recomputed from a part.
    let activates = role == layout::RowPart::Primary && row.activate.is_some();

    let close = if let (true, Some(action)) = (activates, row.activate.as_ref()) {
        let (open, close) = control_tag(action);
        out.push_str(open);
        class_attr(&["row-activate"], opts, out);
        action_attrs(action, Fires::Click, None, morphs, None, out);
        out.push('>');
        close
    } else {
        out.push_str("<span");
        class_attr(&[part_class(role)], opts, out);
        out.push('>');
        "</span>"
    };

    for part in group {
        row_inline_html(&part.node, morphs, opts, out);
    }

    out.push_str(close);
}

/// One leaf inside a row's run.
///
/// Markdown is the one place a run entry is not just `node_html`. A
/// [`Node::Rich`] standing on its own is a block and renders as one; inside a
/// row it goes through docengine's `phrase` preset instead, which is markdown
/// with no block structure at all and no links, keeping the inline emphasis. A
/// heading, a list and a quote each contribute their words without claiming a
/// block of a row that has no room for one, and not even a paragraph survives.
///
/// Links go because a row usually carries [`Row::activate`], so the row itself
/// is already a target and an anchor inside it is a second target inside the
/// first: ambiguous to click, worse to reach by keyboard, and pointing
/// somewhere a one-line summary cannot usefully send anyone. Their text stays.
///
/// This is the renderer deciding, which is the point of the description
/// carrying the kind rather than a flattened string. A terminal renderer facing
/// the same source can emit bold instead, and one that wants neither can call
/// `docengine::render_plain`. None of them has to be told by the screen author
/// which to do.
fn row_inline_html(node: &Node, morphs: bool, opts: &Emit, out: &mut String) {
    match node {
        Node::Text { text, .. } => escape_into(text, out),
        Node::Rich { source } => out.push_str(&docengine::render_phrase(source)),
        Node::Token(tag) => tag_html(tag, morphs, opts, out),
        Node::Act(act) => act_html(act, morphs, opts, out),
        Node::Meter(meter) => meter_html_into(&meter.as_layout(), opts, out),
        // Every other leaf the model admits into a run. A link in a row and a
        // figure in a row were the two gaps the enumeration left open and could
        // not close without a `RowPart` variant each; here they arrive by
        // already being leaves.
        //
        // No fills: a bespoke region is a block and cannot reach a run, which
        // is what the containment bound guarantees.
        other => node_html(other, morphs, opts, &HashMap::new(), out),
    }
}

/// One cell's inline run.
///
/// A part per inline rather than a part per cell, which is the half of the
/// containment model this crate had to learn. Before it, a cell was four
/// members and this function was a fixed sequence: the value or the link, then
/// the tokens strip, then the actions strip. The run says the order itself, so
/// a cell holding a tag between two words draws that way instead of hoisting
/// the tag to the end.
///
/// Consecutive tokens and consecutive acts still share one wrapping strip.
/// `cell-tokens` and `cell-actions` carry the gap between siblings, so a span
/// each would space them as though they were unrelated, and the common case --
/// a status column of three badges -- is exactly the consecutive one.
///
/// Writes into a buffer the caller owns rather than answering with one. The
/// caller is [`cells_row_html`], which needs every cell of a row to exist at
/// once because `cells_html` takes them together -- but needs that only within
/// the row, so the buffers are reused down the table and a fresh `String` per
/// cell per row was the emitter's largest remaining cost.
fn cell_run_html(cell: &Cell, morphs: bool, opts: &Emit, out: &mut String) {
    // A cell that is one piece of text says so on the container through
    // `CellPart::Value`, so a wrapper span here would say nothing the container
    // has not. Anything else names its parts inside, or the content colour on
    // the cell reaches the tokens and the controls beside the text -- the drift
    // makeover-layout 0.14.0 named and makeover-webview 0.25.0 stopped
    // emitting.
    if let [Node::Text { text, .. }] = cell.parts.as_slice() {
        escape_into(text, out);
        return;
    }

    let mut rest = cell.parts.as_slice();
    while let Some((head, tail)) = rest.split_first() {
        match head {
            Node::Text { text, .. } => {
                out.push_str("<span");
                class_attr(&[cell_part_class(layout::CellPart::Value)], opts, out);
                out.push('>');
                escape_into(text, out);
                out.push_str("</span>");
                rest = tail;
            }
            // The row is a `div` and not an anchor even when it activates, so
            // this nests nothing: the href lands on the row element as an
            // attribute htmx reads, and the only `<a>` in the row is the one a
            // cell asked for.
            //
            // `data-act` for the same reason a button carries it. The row's
            // `ClickBeside` filter keys on that attribute, so without it a click
            // on the title would follow the link and open the row underneath.
            Node::Link { text, action } => {
                let (open, close) = control_tag(action);
                out.push_str(open);
                class_attr(&[cell_part_class(layout::CellPart::Link)], opts, out);
                out.push_str(" data-act");
                action_attrs(action, Fires::Click, None, morphs, None, out);
                out.push('>');
                escape_into(text, out);
                out.push_str(close);
                rest = tail;
            }
            Node::Token(_) => {
                let run = rest.iter().take_while(|p| matches!(p, Node::Token(_)));
                out.push_str("<span");
                class_attr(&[cell_part_class(layout::CellPart::Tokens)], opts, out);
                out.push('>');
                let mut taken = 0;
                for part in run {
                    if let Node::Token(tag) = part {
                        tag_html(tag, morphs, opts, out);
                    }
                    taken += 1;
                }
                out.push_str("</span>");
                rest = &rest[taken..];
            }
            // Deliberately not `row-actions`. That was a hover-reveal rule
            // until makeover-webview 0.23.0 retired it, and it is a list row's
            // class besides: `cell-actions` is the table's own, and it carries
            // no colour so a button here is not painted as text.
            Node::Act(_) => {
                let run = rest.iter().take_while(|p| matches!(p, Node::Act(_)));
                out.push_str("<span");
                class_attr(&[cell_part_class(layout::CellPart::Actions)], opts, out);
                out.push('>');
                let mut taken = 0;
                for part in run {
                    if let Node::Act(act) = part {
                        act_html(act, morphs, opts, out);
                    }
                    taken += 1;
                }
                out.push_str("</span>");
                rest = &rest[taken..];
            }
            // Every other leaf the model now admits into a run. A meter and a
            // figure in a cell were the two gaps the enumeration left open and
            // could not close without a member each; here they arrive by
            // already being leaves.
            other => {
                // No fills: a bespoke region is a block and cannot reach a run,
                // which the containment bound is what guarantees.
                node_html(other, morphs, opts, &HashMap::new(), out);
                rest = tail;
            }
        }
    }
}

/// The buffers a table's rows take turns in.
///
/// `cells_html` takes a row's cells together, so the markup of every cell in one
/// row has to exist at once. Nothing says it has to be new: cleared and
/// refilled, these keep the capacity the first row bought, and a table's second
/// row onwards writes into memory that already exists.
///
/// [`Emitted`] is not here, because it borrows from `filled` and a struct
/// holding both would be self-referential. It is a `Vec` per row and stays one.
#[derive(Default)]
struct RowBuffers {
    /// One cell's markup each, in column order.
    filled: Vec<String>,
    /// Which cells are a single piece of text, which is what earns the
    /// container the part class.
    parts: Vec<Option<layout::CellPart>>,
}

/// One row of a table.
///
/// Takes the columns already borrowed rather than the described ones. They are
/// the same for every row of the table, and this built the borrowed list again
/// per row until the emitter's allocations were counted.
fn cells_row_html(
    cells: &Cells,
    columns: &[layout::Column<'_>],
    buffers: &mut RowBuffers,
    morphs: bool,
    opts: &Emit,
    out: &mut String,
) {
    let mut classes = vec!["table-row"];
    if cells.current {
        // `table-row-current`, matching `row-current` on a list row. It was
        // `table-row-selected` while the field was, so the class said one thing
        // and the `aria-current` two lines down said the other.
        classes.push("table-row-current");
    }

    out.push_str("<div role=\"row\"");
    class_attr(&classes, opts, out);
    if cells.current {
        out.push_str(" aria-current=\"true\"");
    }
    if let Some(action) = &cells.activate {
        // Any control in any cell, which is acts and links plus the chips that
        // answer a click. A badge is not one and does not earn the filter. The
        // walk moved onto `Cell` with the run, so this reads the description's
        // answer rather than recomputing it from members.
        let carries_control = cells.values.iter().any(Cell::carries_control);
        let fires = if carries_control {
            Fires::ClickBeside
        } else {
            Fires::Click
        };
        action_attrs(action, fires, None, morphs, None, out);
    }
    out.push('>');

    // The cell contents are escaped here and handed over as Markup, which is
    // makeover-webview's contract: it owns the structure, the caller owns what
    // goes in. Ours is text from a description plus, since `022f0c59`, whatever
    // controls the cell carries, and `cells_html` is what knows the column
    // classes and the narrowing.
    let RowBuffers { filled, parts } = buffers;
    filled.truncate(cells.values.len());
    for (at, cell) in cells.values.iter().enumerate() {
        match filled.get_mut(at) {
            Some(buffer) => buffer.clear(),
            None => filled.push(String::new()),
        }
        cell_run_html(cell, morphs, opts, &mut filled[at]);
    }
    // The container says what the cell is only when the cell is nothing but one
    // piece of text, which is the case where a wrapper span would say nothing
    // the container has not already said. Anything else names its parts inside
    // -- the anchor is a `cell-link`, the strips are `cell-tokens` and
    // `cell-actions` -- because a colour on the container would reach all of
    // them, and that is the drift makeover-layout 0.14.0 named.
    parts.clear();
    parts.extend(cells.values.iter().map(|cell| {
        matches!(cell.parts.as_slice(), [Node::Text { .. }]).then_some(layout::CellPart::Value)
    }));
    let emitted: Vec<Emitted<'_>> = columns
        .iter()
        .zip(filled.iter())
        .zip(parts.iter().copied())
        .map(|((column, value), part)| Emitted {
            column: column.name,
            part,
            content: Markup(value),
        })
        .collect();
    cells_html_into(columns, &emitted, opts, out);

    out.push_str("</div>");
}

/// One thing on a screen.
pub(crate) fn node_html(
    node: &Node,
    morphs: bool,
    opts: &Emit,
    fills: &HashMap<String, String>,
    out: &mut String,
) {
    match node {
        Node::Heading { level, text } => {
            let tag = match level {
                layout::Heading::Page => "h1",
                layout::Heading::Section => "h2",
                layout::Heading::Subsection => "h3",
            };
            out.push('<');
            out.push_str(tag);
            class_attr(&["heading"], opts, out);
            out.push('>');
            escape_into(text, out);
            out.push_str("</");
            out.push_str(tag);
            out.push('>');
        }

        Node::Text { text, tone } => {
            out.push_str("<p");
            class_attr(&["text"], opts, out);
            tone_attr(*tone, out);
            out.push('>');
            escape_into(text, out);
            out.push_str("</p>");
        }

        Node::StandIn {
            state,
            message,
            act,
        } => {
            // The markup is makeover-webview's, unchanged, for the reason every
            // other emitter here defers to it: the CSS that has to match it is
            // emitted there too. The way out arrives as `Markup` because a
            // button is an address and no crate down there names one.
            let mut way_out = String::new();
            if let Some(act) = act {
                act_html(act, morphs, opts, &mut way_out);
            }
            placeholder_html_into(
                *state,
                message,
                (!way_out.is_empty()).then_some(Markup(way_out.as_str())),
                opts,
                out,
            );
        }

        Node::Rich { source } => {
            out.push_str("<div");
            class_attr(&["rich"], opts, out);
            out.push('>');
            out.push_str(&rich_html(source));
            out.push_str("</div>");
        }

        Node::Act(act) => act_html(act, morphs, opts, out),

        // Text that goes somewhere. `control_tag` picks the anchor or the
        // button from the method, the same way a cell link already did, and
        // `link` is the class makeover names it with.
        Node::Link { text, action } => {
            let (open, close) = control_tag(action);
            out.push_str(open);
            class_attr(&["link"], opts, out);
            out.push_str(" data-act");
            action_attrs(action, Fires::Click, None, morphs, None, out);
            out.push('>');
            escape_into(text, out);
            out.push_str(close);
        }

        Node::Token(tag) => tag_html(tag, morphs, opts, out),

        // One figure, through the same emitter the strip uses. What differs is
        // that nothing wraps it: the run it sits in is already the grouping.
        Node::Figure(figure) => {
            figure_html_into(&figure.as_layout(), opts, out);
        }

        Node::Image(picture) => {
            // A captioned picture is a `<figure>`, which is what the element is
            // for and what the shipped carousel already writes by hand. An
            // uncaptioned one is the bare `<img>`: wrapping it would put a
            // grouping element around a group of one.
            let captioned = picture.caption.is_some();
            if captioned {
                out.push_str("<figure");
                class_attr(&["picture"], opts, out);
                out.push('>');
            }

            out.push_str("<img");
            class_attr(&["picture-img"], opts, out);
            out.push_str(" src=\"");
            // Escaped as an attribute and otherwise untouched, the treatment
            // every app-supplied string gets here. No scheme guard: quoting is
            // what stops an attribute breaking out, and unlike `href` an `src`
            // has no scheme that executes -- `javascript:` in an `<img src>` is
            // a broken picture, not a script.
            escape_into(&picture.src, out);
            out.push_str("\" alt=\"");
            escape_into(&picture.alt, out);
            out.push('"');

            // The picture's own dimensions, which is how the browser holds its
            // place. With `height: auto` set by makeover, these two attributes
            // give the box an aspect ratio before a byte arrives, so the space
            // is right at any width and nothing below moves when the image
            // lands. Omitted when the app does not know them -- an invented
            // size would reserve the wrong room, which is worse than none.
            if let Some(e) = picture.intrinsic {
                let _ = write!(out, " width=\"{}\" height=\"{}\"", e.width, e.height);
            }

            // 0.21.0 wrote `loading="lazy"` for every picture and that was
            // wrong for anything on screen at first paint: deferring what is
            // already needed saves nothing and lands its arrival later, so the
            // page moves more rather than less. The description says which it
            // is now, and eager is the default.
            if matches!(picture.loading, layout::Loading::Lazy) {
                out.push_str(" loading=\"lazy\"");
            }
            fit_attr(picture.fit, out);
            out.push('>');

            if let Some(caption) = &picture.caption {
                out.push_str("<figcaption");
                class_attr(&["picture-caption"], opts, out);
                out.push('>');
                escape_into(caption, out);
                out.push_str("</figcaption></figure>");
            }
        }

        Node::Notice { kind, tone, text } => {
            out.push_str("<div");
            class_attr(
                &[match kind {
                    layout::Notice::Toast => "toast",
                    layout::Notice::Banner => "banner",
                }],
                opts,
                out,
            );
            tone_attr(*tone, out);
            // A danger or warning notice interrupts; anything else waits for a
            // pause. The description already says which through its tone, so
            // the renderer does not need a second field to be told.
            let assertive = matches!(tone, layout::Tone::Danger | layout::Tone::Warning);
            if assertive {
                out.push_str(" role=\"alert\"");
            } else {
                out.push_str(" role=\"status\" aria-live=\"polite\"");
            }
            out.push('>');
            escape_into(text, out);
            out.push_str("</div>");
        }

        Node::Field(field) => field_group_html(field, morphs, opts, out),

        Node::Form {
            action,
            submit,
            fields,
        } => {
            out.push_str("<form");
            class_attr(&["form"], opts, out);
            action_attrs(action, Fires::Click, None, morphs, None, out);
            out.push('>');
            for field in fields {
                field_group_html(field, morphs, opts, out);
            }
            out.push_str("<button type=\"submit\"");
            class_attr(&["button", "act-submit"], opts, out);
            out.push('>');
            escape_into(submit, out);
            out.push_str("</button></form>");
        }

        Node::List { rows, more } => {
            out.push_str("<ul");
            class_attr(&["list"], opts, out);
            out.push('>');
            for row in rows {
                row_html(row, morphs, opts, out);
            }
            out.push_str("</ul>");

            // Outside the list, because it is not one of the things in it. A
            // renderer that wanted numbered pages instead would put them here
            // too; what the description said is that there is more and how to
            // ask, and this is one host's answer to that.
            if let Some(rest) = more {
                out.push_str("<div");
                class_attr(&["rest"], opts, out);
                out.push('>');

                let (open, close) = control_tag(&rest.action);
                out.push_str(open);
                class_attr(&["button", "rest-more"], opts, out);
                action_attrs(&rest.action, Fires::Click, None, morphs, None, out);
                out.push('>');
                match rest.remaining {
                    Some(n) => {
                        out.push_str("Show more (");
                        let _ = write!(out, "{n}");
                        out.push_str(" remaining)");
                    }
                    None => out.push_str("Show more"),
                }
                out.push_str(close);
                out.push_str("</div>");
            }
        }

        Node::Timeline {
            track,
            entries,
            focus,
        } => {
            // The axis first, then the things on it. Two children of one
            // positioned box, so the entries resolve their percentages against
            // the same height the slots fill.
            out.push_str("<div");
            class_attr(&["track"], opts, out);
            // The focus travels as data rather than as a scroll offset: the app
            // knows the interesting hour, the host decides how to get there.
            // goingson's JS hardcodes `targetHour = 9` inside its renderer,
            // which is the arrangement this replaces.
            if let Some(minute) = focus {
                let _ = write!(out, " data-focus=\"{minute}\"");
            }
            out.push('>');

            // The ruler. Slots are the grid the eye reads against; a tick every
            // `tick` minutes carries the label. Both are the axis describing
            // itself, so neither is an entry and neither is addressable.
            let slots = track.slots();
            let tick_every = if track.slot == 0 || track.tick == 0 {
                0
            } else {
                track.tick / track.slot
            };
            for slot in 0..slots {
                out.push_str("<div");
                class_attr(&["track-slot"], opts, out);
                out.push('>');
                if tick_every > 0 && slot % tick_every == 0 {
                    let minute = track.span.from() + slot * track.slot;
                    out.push_str("<span");
                    class_attr(&["track-tick"], opts, out);
                    out.push('>');
                    // Wall clock, wrapped, so a span running past midnight
                    // labels 02:00 rather than 26:00. The wrap is presentation:
                    // `Span` deliberately counts past 1440 so it needs no date,
                    // and how that reads to a person is this renderer's call.
                    let _ = write!(out, "{:02}:{:02}", (minute / 60) % 24, minute % 60);
                    out.push_str("</span>");
                }
                out.push_str("</div>");
            }

            // Lanes. Overlapping entries sit side by side, and which lane each
            // takes is worked out here rather than described, because it is a
            // fact about how wide the box is and not about the day. The
            // description said when things happen; `Placement::overlaps` turns
            // that into who collides.
            //
            // Greedy first-fit against the entries already placed, which is the
            // standard day-view packing: an entry takes the lowest lane no
            // occupant of which it overlaps. O(n^2) in the worst case and n is a
            // day's worth of appointments, so the clever interval graph is not
            // worth its own bugs here.
            let mut lanes: Vec<usize> = Vec::with_capacity(entries.len());
            for (i, entry) in entries.iter().enumerate() {
                let mut lane = 0;
                loop {
                    let taken = entries[..i]
                        .iter()
                        .zip(&lanes)
                        .any(|(other, &l)| l == lane && entry.overlaps(other));
                    if !taken {
                        break;
                    }
                    lane += 1;
                }
                lanes.push(lane);
            }
            // One width for the whole track rather than per collision cluster.
            // Per-cluster is denser and is a layout decision this renderer can
            // revisit without the description changing, which is the point of
            // it being here.
            let width = lanes.iter().copied().max().map_or(1, |m| m + 1);

            for (entry, lane) in entries.iter().zip(&lanes) {
                let at = track.fraction(entry.placement.at());
                let end = track.fraction(entry.placement.end());
                out.push_str("<div");
                class_attr(&["track-entry"], opts, out);
                // The only inline style this crate writes, and it carries no
                // colour, no size and no opinion: four numbers makeover's rules
                // read. A stylesheet cannot hold these, because they are the
                // data.
                let _ = write!(
                    out,
                    " style=\"--track-at:{:.4}%;--track-for:{:.4}%;--track-lane:{lane};--track-lanes:{width}\"",
                    at * 100.0,
                    (end - at) * 100.0
                );
                out.push('>');
                row_html(&entry.row, morphs, opts, out);
                out.push_str("</div>");
            }

            out.push_str("</div>");
        }

        Node::Table { columns, rows } => {
            let borrowed: Vec<layout::Column<'_>> = columns
                .iter()
                .map(quasi_router::screen::Column::as_layout)
                .collect();
            // No CSS travels with the table, and none can. A described table's
            // columns are known here rather than at build time, so a track list
            // would have to be emitted per table: a `<style>` element beside it,
            // which needs `style-src 'unsafe-inline'`, or a head block, which a
            // fragment swap does not carry. makeover's stylesheet lays the table
            // out with `display: table` instead, aligning columns across rows
            // knowing nothing about how many there are, and hides a dropped
            // column by the drop class its cells carry. The markup owes the
            // cells and headings those classes and nothing more.
            out.push_str("<div role=\"table\"");
            class_attr(&["table"], opts, out);
            out.push('>');

            out.push_str("<div role=\"row\"");
            class_attr(&["table-head"], opts, out);
            out.push('>');
            for (column, described) in borrowed.iter().zip(columns) {
                out.push_str("<span role=\"columnheader\"");
                // The heading carries the same classes its column's cells do,
                // or the header and the body disagree about which column just
                // dropped and every heading below the cut sits over the wrong
                // values. `column_classes` is makeover's, so the two lists
                // cannot be assembled differently in two places.
                out.push_str(" class=\"");
                class_into("table-heading", opts, out);
                out.push(' ');
                // Not escaped, unlike every other app-supplied string here.
                // makeover reduces a column name to identifier characters
                // rather than escaping it (0.41.0), because the same name is
                // written into a CSS selector by `narrowing_css` and an escaped
                // one would be safe in the attribute and unmatchable from the
                // stylesheet. Escaping the result again would encode nothing
                // and is the one way this heading could stop matching the cells
                // below it.
                push_column_classes(out, column, opts);
                out.push('"');
                // `aria-sort` is what a table actually says about its order;
                // the caret in `state_rules` is this renderer's expression of
                // the same fact for everyone not using a screen reader.
                if let Some(sort) = column.sorted {
                    out.push_str(" aria-sort=\"");
                    out.push_str(sort.as_str());
                    out.push('"');
                }
                if column.sortable {
                    out.push_str(" data-sortable");
                }
                out.push('>');
                match &described.reorder {
                    // A button inside the header cell rather than attributes on
                    // the cell itself: `role="columnheader"` is not a control,
                    // and a screen reader offered a press on something that
                    // announces itself as a heading has been lied to.
                    Some(action) => {
                        let (open, close) = control_tag(action);
                        out.push_str(open);
                        class_attr(&["table-sort"], opts, out);
                        action_attrs(action, Fires::Click, None, morphs, None, out);
                        out.push('>');
                        escape_into(column.name, out);
                        out.push_str(close);
                    }
                    None => escape_into(column.name, out),
                }
                out.push_str("</span>");
            }
            out.push_str("</div>");

            let mut buffers = RowBuffers::default();
            for cells in rows {
                cells_row_html(cells, &borrowed, &mut buffers, morphs, opts, out);
            }
            out.push_str("</div>");
        }

        Node::Select {
            kind,
            options,
            chosen,
            action,
        } => select_html(
            *kind,
            options,
            chosen.as_deref(),
            action.as_ref(),
            morphs,
            opts,
            out,
        ),

        // The trough and its tones are makeover-webview's, unchanged, for the
        // same reason the field markup is: a second emitter here would be the
        // same anatomy with a different escaping story, and the CSS it has to
        // match is emitted there too.
        Node::Meter(meter) => meter_html_into(&meter.as_layout(), opts, out),

        // The strip and its tones are makeover-webview's too, and the actions
        // are this crate's: a figure that answers a click becomes a control
        // wrapped round the emitted markup rather than a second figure emitter
        // that knows about routes.
        Node::Stats { figures } => {
            out.push_str("<div");
            class_attr(&["figures"], opts, out);
            out.push('>');
            for (figure, action) in figures {
                match action {
                    Some(action) => {
                        let (open, close) = control_tag(action);
                        out.push_str(open);
                        class_attr(&["figure-act"], opts, out);
                        action_attrs(action, Fires::Click, None, morphs, None, out);
                        out.push('>');
                        figure_html_into(&figure.as_layout(), opts, out);
                        out.push_str(close);
                    }
                    None => figure_html_into(&figure.as_layout(), opts, out),
                }
            }
            out.push_str("</div>");
        }

        Node::Region(slot) => slot_html(slot, morphs, opts, fills, out),
    }
}

/// A small labelled thing sitting inside something else.
///
/// Took eight arguments, one per field of `Node::Token`, until the payload
/// became [`Tag`] so a row could carry one. The `too_many_arguments` allow went
/// with them.
fn tag_html(tag: &Tag, morphs: bool, opts: &Emit, out: &mut String) {
    let Tag {
        kind,
        label,
        tone,
        latched,
        action,
    } = tag;
    let (kind, tone, latched) = (*kind, *tone, *latched);
    let action = action.as_ref();

    let mut classes = vec![match kind {
        layout::Token::Badge => "badge",
        layout::Token::Chip { .. } => "chip",
    }];
    // `latched`, which is what makeover styles: `.chip.latched` is the pressed
    // depth a chip holds itself down with. This said `chip-latched`, a third
    // name for it, and a latched chip therefore looked exactly like an
    // unlatched one.
    if latched {
        classes.push("latched");
    }

    // A badge answers no click, so it is not a button however it is styled.
    // The description says which through the kind, which is the whole reason
    // the two are separate members rather than one with a flag.
    let interactive = kind.interactive() && action.is_some();
    let close = if interactive {
        // An interactive tag whose destination leaves the app is an anchor, for
        // the reason `control_tag` gives. A tag that answers nothing stays a
        // span either way.
        let (open, close) = action.map_or(("<span", "</span>"), control_tag);
        out.push_str(open);
        close
    } else {
        out.push_str("<span");
        "</span>"
    };
    class_attr(&classes, opts, out);
    tone_attr(tone, out);

    if interactive {
        // `data-act` for the same reason a button carries it: a chip that
        // answers a click is a control, and a table row filtering its own
        // trigger has to be able to tell one apart from its own text. A badge
        // never gets it, because a badge answers nothing.
        out.push_str(" data-act");
        if latched {
            // A chip standing for a filter is on or off, and its latched class
            // carries that fact visually through Depth::pressed either way.
            // Which word says it depends on what the chip turned out to be:
            // aria-pressed is a button's state and means nothing on an anchor,
            // and a link that is the view you are looking at is the one thing
            // aria-current exists to say.
            if action.is_some_and(is_link) {
                out.push_str(" aria-current=\"true\"");
            } else {
                out.push_str(" aria-pressed=\"true\"");
            }
        }
        if let Some(action) = action {
            action_attrs(action, Fires::Click, None, morphs, None, out);
        }
    }

    out.push('>');
    escape_into(label, out);
    if matches!(kind, layout::Token::Chip { removable: true }) {
        out.push_str("<span");
        class_attr(&["chip-remove"], opts, out);
        out.push_str(" aria-hidden=\"true\"></span>");
    }
    out.push_str(close);
}

/// A control that picks between things.
///
/// # Which element carries the kind
///
/// The option does, because that is what makeover styles: `selector_rules`
/// writes the depth, the focus ring and the chosen state for `.tab`,
/// `.segment` and `.toggle`, and each of those is the thing that gets picked
/// rather than the thing holding them. This emitted `tabs` / `segmented` /
/// `option` and put `toggle` on the wrapping div, so every described selector
/// came out flat, and a toggle group took the bevel meant for its buttons. The
/// fourth instance of the gap the SSH-keys tab found three of, and the reason
/// `every_class_this_renderer_emits_is_one_makeover_defines` now enumerates
/// instead of remembering.
///
/// The group keeps one name, `selector`, and says which kind it is in
/// `data-selector`. An attribute for the same reason `data-tone` is one: the
/// group is a spacing question, spacing is `makeover-geometry`'s, and a class
/// there would read as the styling hook the option's class actually is.
fn select_html(
    kind: layout::Selector,
    options: &[(quasi_router::screen::Choice, Option<Action>)],
    chosen: Option<&str>,
    action: Option<&Action>,
    morphs: bool,
    opts: &Emit,
    out: &mut String,
) {
    out.push_str("<div");
    class_attr(&["selector"], opts, out);
    out.push_str(" data-selector=\"");
    out.push_str(option_class(kind));
    out.push('"');
    // Tabs are navigation between panes, which is a tablist. The other two pick
    // a value and are a group of buttons.
    if matches!(kind, layout::Selector::Tabs) {
        out.push_str(" role=\"tablist\"");
    } else {
        out.push_str(" role=\"group\"");
    }
    out.push('>');

    for (option, own) in options {
        let picked = chosen.is_some_and(|value| value == option.value);
        // `chosen` is makeover's name for this, the way `latched` is on a chip.
        let mut classes = vec![option_class(kind)];
        if picked {
            classes.push("chosen");
        }

        // An option naming its own route is a link when that route is a read,
        // for the reason every other read here is: middle-click, copy-link, a
        // crawler and the page with JS off. A tab panel is fetched with a GET,
        // so a tab strip is fifteen links rather than fifteen buttons.
        let (open, close) = own
            .as_ref()
            .map_or(("<button type=\"button\"", "</button>"), |action| {
                control_tag(action)
            });
        out.push_str(open);
        class_attr(&classes, opts, out);
        if matches!(kind, layout::Selector::Tabs) {
            out.push_str(" role=\"tab\" aria-selected=\"");
            out.push_str(if picked { "true\"" } else { "false\"" });
        } else if picked {
            out.push_str(" aria-pressed=\"true\"");
        }

        // The option's own route wins, and there is nothing to substitute into
        // it: it already names the panel. The strip's action is the fallback,
        // and it is the one that needs the picked value, because it is one
        // route standing for all the options.
        if let Some(own) = own {
            action_attrs(own, Fires::Click, None, morphs, None, out);
        } else if let Some(action) = action {
            // The picked value travels under one name, decided once in
            // `Node::SELECTED`, rather than agreed per screen between a
            // renderer and a handler.
            let carrying = action.clone().with(Node::SELECTED, option.value.clone());
            action_attrs(&carrying, Fires::Click, None, morphs, None, out);
        }

        out.push('>');
        escape_into(&option.label, out);
        out.push_str(close);
    }

    out.push_str("</div>");
}

/// A region the answer changed without being aimed at it.
///
/// The second half of the transport, and the reason this file's htmx test
/// names two functions rather than one. [`action_attrs`] says where a control
/// sends and where the answer lands; this says where a piece of the answer
/// lands that no control asked for. Both are the same fact — how htmx is told
/// to put markup somewhere — and a transport swapped for fixi moves both, which
/// is what decision 13's claim needs.
///
/// # Why `innerHTML:` and not a bare `true`
///
/// A bare `hx-swap-oob="true"` replaces the element carrying the matching id
/// outright, and the element in the document is [`slot_html`]'s `<div>` with
/// the region's classes on it. Replacing it with what is emitted here would
/// strip them, so the region would keep its contents and lose its layout.
/// Addressing the swap by selector instead puts the markup *inside* the slot
/// and leaves the wrapper alone, which is what [`Serves::fragment`] already
/// means for the targeted region. The wrapper emitted here is htmx's envelope
/// and never reaches the document.
///
/// [`Serves::fragment`]: quasi_http::Serves::fragment
pub(crate) fn oob_html(
    region: &str,
    node: &Node,
    morphs: bool,
    opts: &Emit,
    fills: &HashMap<String, String>,
    out: &mut String,
) {
    out.push_str("<div hx-swap-oob=\"innerHTML:#");
    // Escaped as an attribute, and otherwise untouched for `slot_html`'s
    // reason: this has to match the id that function emitted, and a slot id is
    // the address the description chose.
    escape_into(region, out);
    out.push_str("\">");
    node_html(node, morphs, opts, fills, out);
    out.push_str("</div>");
}

/// Write a `class="..."` attribute, prefixed, plus `current` if it is the one.
///
/// `current` is written bare rather than through [`class_attr`], because
/// `showing_rules` writes `.showing-frame:not(.current)` and the state half of
/// that pair does not move under a prefix. Same shape as makeover's `chosen`
/// and `latched`: the thing is prefixed, the state qualifying it is not.
fn frame_class_attr(current: bool, opts: &Emit, out: &mut String) {
    out.push_str(" class=\"");
    class_into("showing-frame", opts, out);
    if current {
        out.push_str(" current");
    }
    out.push('"');
}

/// The chrome for a region showing one child at a time.
///
/// Derived, once, for every widget there will ever be. Nothing here reads
/// [`quasi_router::RegionKind::Widget`]'s name, and that is the point of the
/// whole design: a carousel, a tab group and a disclosure are one region that
/// shows some of its children, and which idiom comes out falls out of what the
/// children carry rather than out of what the assembly is called.
///
/// # The three shapes, and what picks between them
///
/// - Children carrying labels get a strip of them, which is
///   [`layout::Selector::Tabs`] markup verbatim. A tab strip is already a
///   described thing here; deriving a second spelling of one would be this
///   renderer inventing a name makeover would then not style, which is the
///   SSH-keys bug with extra steps.
/// - One dismissible child with a name gets that name as a control, which is a
///   summary line that opens.
/// - Anything else gets previous, position, next.
///
/// # Why these controls are not links
///
/// A control here calls no route, because the description names none: what
/// changes is which of several children already in the document is showing, and
/// a round trip to reveal bytes the reader has downloaded is worse on every one
/// of the three MNW galleries this was measured against. So the controls carry
/// `data-shows` and whatever binds the region binds them, the same relationship
/// `data-act` and `data-bespoke` already have with their host.
///
/// That leaves route-bound movement available and unbuilt. A description that
/// wanted a real fragment request would carry an [`Action`], the controls would
/// become links through [`control_tag`] exactly as a selector's options do, and
/// nothing here would have to change shape. Nothing asks for it today.
fn showing_html(slot: &Slot, opts: &Emit, out: &mut String) {
    let labels = slot.labels();
    let current = slot.current();
    let total = slot.body.len();

    // A named single child that can close is a disclosure, and the check comes
    // first because such a child is also a labelled one: a strip of one tab is
    // not what a summary line is.
    if slot.showing.dismissible()
        && total == 1
        && let [label] = labels.as_slice()
    {
        out.push_str("<button type=\"button\"");
        // `button`, which is makeover's name for a control and carries its whole
        // interactive set. `act_html` learned this the expensive way.
        class_attr(&["button"], opts, out);
        out.push_str(" data-shows=\"0\" aria-expanded=\"");
        out.push_str(if current.is_some() {
            "true\""
        } else {
            "false\""
        });
        out.push('>');
        escape_into(label, out);
        out.push_str("</button>");
        return;
    }

    if !labels.is_empty() {
        let tab = option_class(layout::Selector::Tabs);
        out.push_str("<div");
        class_attr(&["selector"], opts, out);
        out.push_str(" data-selector=\"");
        out.push_str(tab);
        out.push_str("\" role=\"tablist\">");
        for (at, label) in labels.iter().enumerate() {
            let picked = current == Some(at);
            out.push_str("<button type=\"button\" class=\"");
            class_into(tab, opts, out);
            if picked {
                out.push_str(" chosen");
            }
            let _ = write!(out, "\" data-shows=\"{at}\" role=\"tab\" aria-selected=\"");
            out.push_str(if picked { "true\"" } else { "false\"" });
            out.push('>');
            escape_into(label, out);
            out.push_str("</button>");
        }
        out.push_str("</div>");
        return;
    }

    // Previous, position, next. In flow, under the content, nothing overlaid:
    // a terminal cannot honestly overlay anything, and the dot strip this
    // replaces had no form at all past a handful of children -- two of the
    // three galleries it shipped on are creator uploads of arbitrary length.
    out.push_str("<div");
    class_attr(&["showing"], opts, out);
    out.push('>');

    out.push_str("<button type=\"button\"");
    class_attr(&["button"], opts, out);
    out.push_str(" data-shows=\"previous\">Prev</button>");

    out.push('<');
    out.push_str("span");
    class_attr(&["showing-position"], opts, out);
    // Zero when a dismissible region is closed, which is a true statement about
    // how many of its children are showing and needs no glyph of its own.
    let _ = write!(out, ">{} / {total}</span>", current.map_or(0, |at| at + 1));

    out.push_str("<button type=\"button\"");
    class_attr(&["button"], opts, out);
    out.push_str(" data-shows=\"next\">Next</button>");

    out.push_str("</div>");
}

/// A region, and everything under it.
pub(crate) fn slot_html(
    slot: &Slot,
    morphs: bool,
    opts: &Emit,
    fills: &HashMap<String, String>,
    out: &mut String,
) {
    let kind = match &slot.kind {
        quasi_router::RegionKind::Band => "band",
        quasi_router::RegionKind::Sidebar => "sidebar",
        quasi_router::RegionKind::Pane => "pane",
        quasi_router::RegionKind::Split => "split",
        quasi_router::RegionKind::TabGroup => "tabgroup",
        quasi_router::RegionKind::Modal => "modal",
        quasi_router::RegionKind::Bespoke { .. } => "bespoke",
        quasi_router::RegionKind::Widget { .. } => "widget",
    };

    out.push_str("<div id=\"");
    // The id is the fragment's address. It is escaped and otherwise untouched:
    // rewriting it would break the HX-Retarget the router just sent, which
    // names the slot's own id.
    escape_into(&slot.id, out);
    out.push('"');
    class_attr(&["region", kind], opts, out);

    if let quasi_router::RegionKind::Bespoke { name } = &slot.kind {
        // Never interpreted, per decision 4. Handed to the app under a name it
        // chose, which is the entire contract for a bespoke region.
        out.push_str(" data-bespoke=\"");
        escape_into(name, out);
        out.push('"');
    }

    if let quasi_router::RegionKind::Widget { name } = &slot.kind {
        // Also never interpreted here, and for a different purpose: this is the
        // hook a stylesheet or a script attaches to in order to draw the
        // assembly the way a browser does it. It is an attribute rather than a
        // class because a widget name is app vocabulary and classes here are
        // this renderer's.
        //
        // What makes it safe to emit and ignore is that the body under it is
        // already the whole assembly in primitives. Nothing recognises
        // `data-widget` and the region still renders -- a carousel degrades to
        // its frames, which is the JS-off fallback the shipped partial has and
        // the reason the tier does not need three renderers to release in step.
        out.push_str(" data-widget=\"");
        escape_into(name, out);
        out.push('"');
    }

    // What a binder looks for, and the one attribute that says this region has
    // chrome to bind. It is not the widget's name: a script that moved between
    // a carousel's frames by matching `data-widget="carousel"` would have to be
    // written again for the next assembly, which is the per-widget code the
    // whole derivation exists to stop.
    //
    // Nothing is emitted for `Showing::All`, so the hook is present exactly
    // when there is something to bind.
    match slot.showing {
        layout::Showing::One => out.push_str(" data-showing=\"one\""),
        layout::Showing::AtMostOne => out.push_str(" data-showing=\"at-most-one\""),
        _ => {}
    }

    if matches!(slot.readiness, layout::Readiness::Pending) {
        out.push_str(" aria-busy=\"true\"");
    }

    if matches!(slot.kind, quasi_router::RegionKind::Modal) {
        // A modal takes input until dismissed, which is what modal means, and
        // saying so is the renderer's job rather than the app's.
        out.push_str(" role=\"dialog\" aria-modal=\"true\"");
    }

    out.push('>');
    if slot.showing.selective() {
        let current = slot.current();
        let labelled = !slot.labels().is_empty();

        // A strip sits above the panes it opens and a counter row sits under
        // the content it counts. That is the only placement decision here, and
        // it is the folder semantic rather than a preference: a tab that came
        // after its pane would not read as the tab of it.
        if labelled {
            showing_html(slot, opts, out);
        }

        // Each child is wrapped, because the rule that collapses the stack has
        // to have something to select and a described child emits whatever
        // element it is. The wrapper appears only here, so a region that shows
        // everything -- which is every region written before `Showing` existed
        // -- emits exactly the markup it always did.
        for (at, node) in slot.body.iter().enumerate() {
            out.push_str("<div");
            frame_class_attr(current == Some(at), opts, out);
            out.push('>');
            node_html(node, morphs, opts, fills, out);
            out.push_str("</div>");
        }

        if !labelled {
            showing_html(slot, opts, out);
        }
    } else {
        for node in &slot.body {
            node_html(node, morphs, opts, fills, out);
        }
    }

    // The host's markup for this region, after whatever the description put
    // here, and only for a bespoke one: a fill named against a pane is a host
    // reaching into a region the description already owns.
    //
    // Verbatim. See `Webview::fills` for why that is not the hole it looks
    // like: the string is host code's, never a description's, so the escaping
    // guarantee the whole vocabulary rests on is untouched.
    if matches!(slot.kind, quasi_router::RegionKind::Bespoke { .. })
        && let Some(fill) = fills.get(&slot.id)
    {
        out.push_str(fill);
    }

    out.push_str("</div>");
}