//! Turning a parsed declaration into the Rust a shape function used to be.
//!
//! Every construct emitted here is a constructor `quasi_router` already has, so
//! nothing in the generated code is reachable only through this macro. The
//! expansion is the same tree the hand-written shape built, made at the same
//! moment for the same request; what changes is who wrote it.
//!
//! Two rules decide most of this file. Rule R2 says what the shape's return
//! type makes: a `Node` shape's single emission IS the result, so there is no
//! fabricated container to fill. And rule R8 says nothing borrows implicitly,
//! so an `&` appears in the output only where the declaration wrote one.

use proc_macro2::{Span, TokenStream};
use quote::{format_ident, quote};
use syn::spanned::Spanned as _;
use syn::{LitStr, Result};

use crate::ast::{
    Action, Arg, Declaration, Emission, Guard, Hole, HoleRoot, Interpolated, Item, Pattern,
    Predicate, RegionKind, Source, Step, StrPart,
};
use crate::parse::{COMPARISONS, VOCABULARY};

/// What the items of a body accrete onto.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Container {
    /// A region: emissions accrete onto a `Slot`.
    Slot,
    /// A row: every emission is `beside` and carries a priority.
    Run,
    /// One control: its body sets, and emits nothing.
    Act,
    /// One field: its body sets, and emits nothing.
    Field,
    /// A document: its members are regions, held as slots rather than nodes.
    Screen,
    /// One row of a list: its members are the controls it offers.
    Row,
    /// A table: its members are its columns and its rows.
    Table,
    /// One column: its body says how it narrows, and it emits nothing.
    Column,
    /// One cell: its body says what opening it does.
    Cell,
    /// One node member: its body says what it is told afterwards.
    Node,
    /// One picture: its body sets on the `Image`, and it emits nothing.
    Image,
    /// One canvas: its body sets on the `Canvas` and draws inside its scope.
    Canvas,
    /// One tag: its body says what it is like, and it emits nothing.
    Tag,
    /// An axis: its members are `at`, each a placement and the row on it.
    Timeline,
    /// One meter: its body says what it is like, and it emits nothing.
    Meter,
    /// One figure: its body says what it is like, and it emits nothing.
    Figure,
    /// One repeating question: its body says how few may be left, and it emits
    /// nothing.
    Repeats,
}

pub fn declaration(declaration: &Declaration) -> Result<TokenStream> {
    let Declaration {
        docs,
        flags,
        vis,
        name,
        params,
        returns,
        items,
    } = declaration;

    let shaped = shaped_name(returns)?;

    let docs = docs.iter().map(|line| {
        let line = LitStr::new(line, Span::call_site());
        quote!(#[doc = #line])
    });
    // `staged` asks for the twin in `symbolic` and `constant` asks for the
    // shim beside it. Neither is an attribute rustc has ever heard of.
    let flags = flags
        .iter()
        .filter(|flag| *flag != crate::symbolic::FLAG && *flag != crate::symbolic::CONSTANT)
        .map(|flag| quote!(#[#flag]));
    let params = params.iter().map(|param| {
        let name = &param.name;
        let ty = &param.ty;
        quote!(#name: #ty)
    });
    let body = value_body(items, &shaped, name.span())?;

    let returns = returns_type(returns)?;

    Ok(quote! {
        #(#docs)*
        #(#flags)*
        #vis fn #name(#(#params),*) -> #returns #body
    })
}

/// The vocabulary type a shape returns, written out.
///
/// The vocabulary type, not the path the file happened to import it under:
/// team.rs takes `Screen as Described` because it has a function called
/// `screen`, and a declaration names what it returns rather than what the module
/// around it calls that.
///
/// Public to the crate because `symbolic`'s `#[constant]` shim has the same
/// signature as the shape it stands for, and a second spelling of this mapping
/// would drift from the first the moment a shaped type was added.
pub fn returns_type(returns: &syn::Type) -> Result<TokenStream> {
    let shaped = shaped_name(returns)?;
    Ok(match &shaped {
        Shaped::Nodes => quote!(::std::vec::Vec<::quasi_router::Node>),
        Shaped::Acts => quote!(::std::vec::Vec<::quasi_router::Act>),
        Shaped::Single { name, optional } => {
            let shaped_type = format_ident!("{}", name, span = returns.span());
            if *optional {
                quote!(::std::option::Option<::quasi_router::#shaped_type>)
            } else {
                quote!(::quasi_router::#shaped_type)
            }
        }
    })
}

/// What a shape returns.
enum Shaped {
    /// One vocabulary type, which the body's single emission is. `optional` is
    /// the grammar's `single "?"`, and rule R10 is what makes it usable: a body
    /// whose emission is guarded away yields `None`.
    Single { name: String, optional: bool },
    /// `Vec<Node>`: the members of a panel, in order, with nothing wrapping
    /// them.
    ///
    /// The one shape that is not a single emission, and it is not a container
    /// either. `user_support` demanded it: the dashboard strip draws the region
    /// and its `id`, so the panel's own fill must add no second one, and the
    /// tab that answers over htmx wraps the same members itself. 52 of the
    /// population's 484 shapes return this, third after `Slot` and `Node`.
    Nodes,
    /// `Vec<Act>`: a menu, which is the controls a row holds back.
    ///
    /// [`Nodes`](Self::Nodes)' twin and for its reason. `Row::menu` and
    /// `Row::menu` takes the whole list, so a menu that is built conditionally
    /// has nowhere to accrete, and audiofiles' file list has two of them --
    /// what a row offers and what a chosen set does. Every member is an `act`,
    /// because a menu is nothing but controls.
    Acts,
}

/// The type a shape returns, read off the declaration.
fn shaped_name(returns: &syn::Type) -> Result<Shaped> {
    let syn::Type::Path(path) = returns else {
        return Err(syn::Error::new_spanned(
            returns,
            "a shape returns one of the vocabulary types",
        ));
    };
    let Some(last) = path.path.segments.last() else {
        return Err(syn::Error::new_spanned(returns, "an empty return type"));
    };
    if last.ident == "Vec" {
        let Some(inner) = sole_argument(returns, &last.arguments)? else {
            return Err(syn::Error::new_spanned(returns, "`Vec` of what?"));
        };
        return match shaped_name(inner)? {
            Shaped::Single {
                ref name,
                optional: false,
            } if name == "Node" => Ok(Shaped::Nodes),
            Shaped::Single {
                ref name,
                optional: false,
            } if name == "Act" => Ok(Shaped::Acts),
            _ => Err(syn::Error::new_spanned(
                returns,
                "a shape builds two lists: `Vec<Node>`, a panel's members, and \
                 `Vec<Act>`, a menu",
            )),
        };
    }
    if last.ident == "Option" {
        let Some(inner) = sole_argument(returns, &last.arguments)? else {
            return Err(syn::Error::new_spanned(returns, "`Option` of what?"));
        };
        return match shaped_name(inner)? {
            Shaped::Single {
                name,
                optional: false,
            } => Ok(Shaped::Single {
                name,
                optional: true,
            }),
            Shaped::Single { .. } => Err(syn::Error::new_spanned(
                returns,
                "a shape omits its result or does not; there is no second omission",
            )),
            Shaped::Nodes => Err(syn::Error::new_spanned(
                returns,
                "a panel with no members is an empty `Vec<Node>`, not a `None`",
            )),
            Shaped::Acts => Err(syn::Error::new_spanned(
                returns,
                "a menu with no entries is an empty `Vec<Act>`, not a `None`",
            )),
        };
    }
    Ok(Shaped::Single {
        name: last.ident.to_string(),
        optional: false,
    })
}

/// The one type inside `Option<..>` or `Vec<..>`.
fn sole_argument<'a>(
    returns: &syn::Type,
    arguments: &'a syn::PathArguments,
) -> Result<Option<&'a syn::Type>> {
    let syn::PathArguments::AngleBracketed(arguments) = arguments else {
        return Err(syn::Error::new_spanned(returns, "of what?"));
    };
    Ok(match arguments.args.first() {
        Some(syn::GenericArgument::Type(inner)) => Some(inner),
        _ => None,
    })
}

/// A shape's body: its bindings, then the single emission that is the value.
///
/// Rule R2 for the two shapes converted so far. A `-> Node` shape's single
/// emission IS the result and a `-> Act` shape's single `act` member is, so
/// neither fabricates a container: what a caller gets is what the body said.
///
/// Bindings are hoisted above the emissions of their own body. Nothing is
/// reordered by that: a binding can only name bindings written before it, and
/// an emission produces a value rather than an effect, so the two are
/// independent within one block.
fn value_body(items: &[Item], shaped: &Shaped, span: Span) -> Result<TokenStream> {
    let shaped = match shaped {
        Shaped::Nodes => return nodes(items),
        Shaped::Acts => return acts(items),
        single @ Shaped::Single { .. } => single,
    };
    let Shaped::Single {
        name: shaped,
        optional,
    } = shaped
    else {
        unreachable!("the two lists are answered above")
    };
    let optional = *optional;
    let shaped = shaped.as_str();
    let mut bindings = Vec::new();
    let mut emissions = Vec::new();
    for item in items {
        match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                bindings.push(quote!(let #name = #value;));
            }
            Item::Attribute { name, .. } => {
                return Err(syn::Error::new(
                    name.span(),
                    "a setting needs something to set: put it in the member's body",
                ));
            }
            Item::For { binder, .. } => {
                return Err(syn::Error::new(
                    binder.span(),
                    "a loop emits many members, and this shape is its single one",
                ));
            }
            Item::Emit(emission) => emissions.push(emission),
        }
    }

    let [only] = emissions.as_slice() else {
        return Err(syn::Error::new(
            span,
            format!(
                "a `-> {shaped}` shape is its single emission, and this one has {}",
                emissions.len()
            ),
        ));
    };

    let (guard, only) = match only {
        Emission::Guarded { guard, inner } => (Some(guard), &**inner),
        other => (None, *other),
    };
    if guard.is_some() && !optional {
        return Err(syn::Error::new(
            span,
            "a guard on the whole result needs a shape that may omit it: `-> Option<_>`",
        ));
    }

    let built = match shaped {
        "Node" => node(only)?,
        "Act" => match only {
            Emission::Act { .. } => act(only)?,
            other => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a `-> Act` shape is its single `act` member",
                ));
            }
        },
        "Screen" => match only {
            Emission::Screen {
                arrangement,
                args,
                body,
            } => {
                let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
                accrete(
                    body,
                    Container::Screen,
                    &quote!(::quasi_router::Screen::#arrangement(#(#args),*)),
                )?
            }
            other => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a `-> Screen` shape is its single `screen` member",
                ));
            }
        },
        "Slot" => match only {
            Emission::Region { name, kind, body } => slot(name, kind, body)?,
            other => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a `-> Slot` shape is its single `region` member",
                ));
            }
        },
        // One arm, because there is one row type since the 2026-09-05 collapse.
        // The body says which spelling it is -- `row "primary" { .. }` names
        // roles of the default column set, `cells { .. }` names declared columns
        // -- and the return type was a second, redundant way to say the same
        // thing. It was worse than redundant: it had to agree with the body, so
        // a table row spelled `-> Row` was an error about the return type when
        // nothing was wrong with it.
        "Row" => match only {
            Emission::Row { primary, body } => row(Some(primary), body)?,
            Emission::Cells(body) => cells(body)?,
            other => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a `-> Row` shape is its single `row` or `cells` member",
                ));
            }
        },
        "Field" => match only {
            Emission::Field {
                kind,
                name,
                label,
                body,
            } => field(kind, name, label, body)?,
            other => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a `-> Field` shape is its single `field` member",
                ));
            }
        },
        other => {
            return Err(syn::Error::new(
                span,
                format!(
                    "`-> {other}` is not a shape this form can build yet. \
                     Add the R2 case, and name the screen that demanded it in the commit."
                ),
            ));
        }
    };

    let built = if optional {
        let test = match guard {
            Some(guard) => predicate(guard)?,
            None => quote!(true),
        };
        quote!(if #test { ::std::option::Option::Some(#built) } else { ::std::option::Option::None })
    } else {
        built
    };

    Ok(quote!({ #(#bindings)* #built }))
}

/// A binding's value, with the dispatch's ownership already decided.
fn source_value(source: &Source) -> Result<TokenStream> {
    self::source(source, owned_arms(source))
}

/// A body that accretes onto something already built.
fn accrete(items: &[Item], container: Container, base: &TokenStream) -> Result<TokenStream> {
    // A loop cannot be a link in a chain, and neither can a guard: both are
    // statements. A body with either accumulates instead.
    let statementish = items.iter().any(|item| {
        matches!(
            item,
            Item::For { .. }
                | Item::Emit(Emission::Guarded { .. })
                | Item::Attribute { guard: Some(_), .. }
        )
    });
    if statementish {
        return accumulate(items, container, base);
    }

    let mut bindings = Vec::new();
    let mut steps = Vec::new();
    for item in items {
        match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                bindings.push(quote!(let #name = #value;));
            }
            Item::Attribute { name, args, .. } => steps.push(attribute(name, args)?),
            Item::For { .. } => unreachable!("a loop takes the accumulating form"),
            Item::Emit(emission) => {
                // A member is evaluated into its own binding before the
                // container is built, because a container's own name is often
                // the same value one of its members borrows: follow.rs names
                // the region and then aims the press at it. Built inline, the
                // container would move the name before the member read it.
                let held = format_ident!("member_{}", bindings.len(), span = Span::call_site());
                let (value, call) = step(emission, container, &held)?;
                bindings.push(quote!(let #held = #value;));
                steps.push(call);
            }
        }
    }
    Ok(quote!({ #(#bindings)* #base #(#steps)* }))
}

/// The same body, for a container a loop adds to.
///
/// A chain cannot hold a loop, so this accumulates instead. The two forms are
/// kept apart rather than merged because the chain is what a container with no
/// loop should read as, and a `let mut` that is never reassigned is a warning
/// in the caller's crate that the caller cannot see the cause of.
fn accumulate(items: &[Item], container: Container, base: &TokenStream) -> Result<TokenStream> {
    let built = format_ident!("built", span = Span::call_site());
    let statements = statements(items, container, &built)?;
    Ok(quote!({
        let mut #built = #base;
        #(#statements)*
        #built
    }))
}

/// The statements one body contributes to an accumulating container.
fn statements(
    items: &[Item],
    container: Container,
    built: &proc_macro2::Ident,
) -> Result<Vec<TokenStream>> {
    let mut statements = Vec::new();
    for (index, item) in items.iter().enumerate() {
        statements.push(match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                quote!(let #name = #value;)
            }
            Item::Attribute { name, args, guard } => {
                let call = attribute(name, args)?;
                match guard {
                    // The same rule a guarded member follows: the guard decides
                    // whether the setting is made, and the args are evaluated
                    // either way.
                    Some(guard) => {
                        let test = predicate(guard)?;
                        quote!(if #test { #built = #built #call; })
                    }
                    None => quote!(#built = #built #call;),
                }
            }
            Item::For {
                dereferenced,
                binder,
                iterable,
                body,
            } => {
                let iterable = hole(iterable)?;
                let inner = self::statements(body, container, built)?;
                let binder = binder_pattern(*dereferenced, binder);
                quote!(for #binder in #iterable { #(#inner)* })
            }
            Item::Emit(Emission::Guarded { guard, inner }) => {
                let test = predicate(guard)?;
                let held = format_ident!("member_{index}", span = Span::call_site());
                let (value, call) = step(inner, container, &held)?;
                // R9: the guard decides whether the member is placed, not
                // whether its holes are evaluated. The value is built either
                // way, and a supplier that is asked for nothing answers with
                // nothing.
                quote!({
                    let #held = #value;
                    if #test {
                        #built = #built #call;
                    }
                })
            }
            Item::Emit(emission) => {
                let held = format_ident!("member_{index}", span = Span::call_site());
                let (value, call) = step(emission, container, &held)?;
                quote!({ let #held = #value; #built = #built #call; })
            }
        });
    }
    Ok(statements)
}

/// One setting, as the builder call ATTRIBUTE NAMING says it is.
fn attribute(name: &proc_macro2::Ident, args: &[Arg]) -> Result<TokenStream> {
    let slot = name.to_string();
    let enumeration = VOCABULARY
        .iter()
        .find(|(attribute, _)| *attribute == slot)
        .map(|(_, enumeration)| *enumeration);
    let args = args
        .iter()
        .map(|value| match enumeration {
            Some(enumeration) => variant(value, enumeration),
            None => arg(value),
        })
        .collect::<Result<Vec<_>>>()?;
    Ok(quote!(.#name(#(#args),*)))
}

/// Rule R1(4): a bare uppercase ident in a vocabulary slot is that enum's
/// variant. A `SCREAMING_CASE` ident never is, because 19 of 19 real uses of
/// the `measured` slot pass a module const rather than a variant.
fn variant(value: &Arg, enumeration: &str) -> Result<TokenStream> {
    let Arg::Hole(hole) = value else {
        return arg(value);
    };
    let HoleRoot::Path(path) = &hole.root else {
        return arg(value);
    };
    if !hole.steps.is_empty() || path.leading_colon.is_some() || path.segments.len() != 1 {
        return arg(value);
    }
    let name = path.segments[0].ident.to_string();
    if name.chars().all(|letter| !letter.is_lowercase()) {
        return arg(value);
    }
    let enumeration = format_ident!("{}", enumeration);
    let name = &path.segments[0].ident;
    Ok(quote!(::quasi_router::layout::#enumeration::#name))
}

/// One emission, as the value it builds and the call that places it.
fn step(
    emission: &Emission,
    container: Container,
    held: &proc_macro2::Ident,
) -> Result<(TokenStream, TokenStream)> {
    match (container, emission) {
        (Container::Slot, Emission::Across { fallback, body }) => {
            let run = accrete(
                body,
                Container::Run,
                &quote!(::quasi_router::Run::new(::quasi_router::layout::Fallback::#fallback)),
            )?;
            Ok((run, quote!(.across(#held))))
        }
        // A question standing in a region rather than in a form. A region that
        // consults gathers the dials it contains and sends them itself, so
        // there is no form to put them in and `Node::field` is what the
        // vocabulary has for it. `pricing`'s calculator is the site: five dials
        // and no submit button anywhere on the page.
        //
        // Narrow on purpose. Everywhere else a field is still refused with the
        // message that names the two legal homes, because a question in a cell
        // or a row is a question nothing will ever read.
        //
        // A ranked member, which is `beside`'s third container and its second
        // meaning of `Priority`: a run ranks everything it holds and a region
        // ranks the members that say so. audiofiles' status band is the site --
        // every fact in it is stated nowhere else on the window except the
        // focused sample's tags, which the detail panel repeats in full, so a
        // window with no room loses the repetition and keeps the rest.
        (
            Container::Slot,
            Emission::Beside {
                priority,
                width,
                inner,
            },
        ) => {
            if width.is_some() {
                return Err(syn::Error::new(
                    Span::call_site(),
                    "a region's body is a stack and every member gets the whole width: \
                     say a width on a row's member, inside `across`",
                ));
            }
            let rank = variant(priority, "Priority")?;
            Ok((panel_member(inner)?, quote!(.with_ranked(#held, #rank))))
        }
        // The control one slot of a repeating question carries to take itself
        // away, and the question the slots are of. Both are `Act`s the region is
        // told, and neither could be said at all: written where the vocabulary
        // takes them they are expressions in argument position, which no guard
        // reaches and no reader of the description sees. audiofiles' rule editor
        // is the site for both, twice each.
        (
            Container::Slot,
            Emission::Removes {
                label,
                action,
                body,
            },
        ) => {
            let label = arg(label)?;
            let called = self::action(action)?;
            let taken = accrete(
                body,
                Container::Act,
                &quote!(::quasi_router::Act::new(#label, #called)),
            )?;
            Ok((taken, quote!(.removes(#held))))
        }
        (
            Container::Slot,
            Emission::Repeats {
                one,
                label,
                action,
                body,
            },
        ) => {
            let one = arg(one)?;
            let label = arg(label)?;
            let called = self::action(action)?;
            let question = accrete(
                body,
                Container::Repeats,
                &quote!(::quasi_router::Repeating::new(
                    #one,
                    ::quasi_router::Act::new(#label, #called)
                )),
            )?;
            Ok((question, quote!(.repeating(#held))))
        }
        // A named member of a region: the label is hoisted out of the child and
        // onto the placement, because that is where `Slot::frame` takes it.
        //
        // The word stays written inside the child, which is where it reads --
        // "this region is called Bio" -- but it is no longer something the child
        // carries. Since quasicoherent `2cdc6761` a `Slot` has no label at all,
        // so a label on a member that nothing reveals cannot be built rather
        // than being built and dropped. See [`labelled`] for what is refused.
        // A member placed as a named frame, whatever it is. `include` is the
        // reason this exists: a shape in another `declare!` answers a `Slot`,
        // which since `2cdc6761` cannot carry a label, so the name has to be
        // said where the placing happens.
        (Container::Slot, Emission::Framed { label, inner }) => {
            let label = arg(label)?;
            let (built, _) = step(inner, container, held)?;
            Ok((built, quote!(.frame(#label, #held))))
        }
        (Container::Slot, Emission::Region { name, kind, body }) => {
            let (label, body) = labelled(body)?;
            let slot = slot(name, kind, &body)?;
            let node = quote!(::quasi_router::Node::Region(#slot));
            match label {
                Some(label) => Ok((node, quote!(.frame(#label, #held)))),
                None => Ok((node, quote!(.with(#held)))),
            }
        }
        // A shape that answers many members, spliced whole. The plural of
        // `include`, and only a container that holds many can take one.
        (Container::Slot, Emission::IncludeEach(supplier)) => {
            let supplier = hole(supplier)?;
            Ok((quote!(#supplier), quote!(.with_all(#held))))
        }
        (Container::Slot, other) => Ok((panel_member(other)?, quote!(.with(#held)))),
        (Container::Screen, Emission::Region { name, kind, body }) => {
            Ok((slot(name, kind, body)?, quote!(.with(#held))))
        }
        // A region another shape built. `custom_page`'s three screens carry the
        // same platform strip top and bottom, and every link in it is per
        // request, so the band is a shape rather than `Chrome`. A table already
        // takes a row this way and a row a control; this is a document taking a
        // region.
        (Container::Screen, Emission::Include(supplier)) => {
            let supplier = hole(supplier)?;
            Ok((
                quote!(::std::convert::Into::into(#supplier)),
                quote!(.with(#held)),
            ))
        }
        (Container::Screen, other) => Err(syn::Error::new(
            emission_span(other),
            "a document holds regions: write `region <name> as <kind> { .. }` \
             or `include <shape>;`",
        )),
        (Container::Cell | Container::Row, Emission::Activate(action)) => {
            Ok((self::action(action)?, quote!(.activate(#held))))
        }
        (Container::Row, Emission::Act { .. }) => Ok((act(emission)?, quote!(.act(#held)))),
        // `act`'s held-back twin. A row shows what `act` puts in it and keeps
        // what `offers` gives it until the host is asked, which is the whole of
        // the difference and is why the two are one word apart. A member rather
        // than a setting because a menu control is told the same things an
        // inline one is: audiofiles' sidebar greys a vault's Delete when it is
        // the last vault, and a control written as an expression in an argument
        // cannot say that.
        (Container::Row, Emission::Offers { .. }) => Ok((act(emission)?, quote!(.offers(#held)))),
        // A control another shape built. `export_act::control` is the export
        // portal's one sentence about saving a file, said once and offered
        // under each card's own label, and a row holds acts rather than nodes.
        (Container::Row, Emission::Include(supplier)) => {
            let supplier = hole(supplier)?;
            Ok((
                quote!(::std::convert::Into::into(#supplier)),
                quote!(.act(#held)),
            ))
        }
        // A row's parts are placed by role rather than ranked by priority,
        // which is the other thing `beside` means and the container is what
        // says which. embeds' button strip is the site: a thumbnail and a title
        // in `Primary`, the buy control in `Actions`, the price a setting
        // between them.
        (
            Container::Row,
            Emission::Beside {
                priority,
                width,
                inner,
            },
        ) => {
            if width.is_some() {
                return Err(syn::Error::new(
                    Span::call_site(),
                    "a row of a list places its parts by name and not by width: \
                     say a width on a region row's member, inside `across`",
                ));
            }
            let part = variant(priority, "RowPart")?;
            Ok((node(inner)?, quote!(.part(#part, #held))))
        }
        // A cell names its column instead of taking a role, and that is the
        // whole of what a table row spells differently. One container since the
        // 2026-09-05 collapse, so this sits beside `beside` rather than in a
        // second settings table.
        (
            Container::Row,
            Emission::Cell {
                column,
                value,
                body,
            },
        ) => {
            let built = cell(value, body)?;
            Ok(match column {
                Some(column) => {
                    let column = arg(column)?;
                    (built, quote!(.at(#column, #held)))
                }
                None => (built, quote!(.cell(#held))),
            })
        }
        // One message, because there is one container. A row places its content
        // by key and the two spellings are the two kinds of key: `beside <part>`
        // names a role of the default column set, `cell at <column>` names a
        // declared column.
        (Container::Row, other) => Err(syn::Error::new(
            emission_span(other),
            "a row holds controls, places its content and says what opening it does: write \
             `act <label> to <action>;`, `include <shape>;`, `beside <part> <emission>`, \
             `cell [at <column>] <value>;` or `activate to <action>;`",
        )),
        (Container::Image, other) => Err(syn::Error::new(
            emission_span(other),
            "a picture holds nothing: its body says how it sits in its box",
        )),
        // Inside the scope and after the markup, which is the only place a
        // canvas can hold anything: the markup is opaque, so nothing is
        // injected into the middle of it.
        (Container::Canvas, other) => Ok((node(other)?, quote!(.with(#held)))),
        (Container::Tag, other) => Err(syn::Error::new(
            emission_span(other),
            "a tag holds nothing: its body says what it is like",
        )),
        (Container::Figure, other) => Err(syn::Error::new(
            emission_span(other),
            "a figure holds nothing: its body says what it is like",
        )),
        (Container::Meter, other) => Err(syn::Error::new(
            emission_span(other),
            "a meter holds nothing: its body says what it is like",
        )),
        (Container::Repeats, other) => Err(syn::Error::new(
            emission_span(other),
            "a repeating question holds nothing: its body says how few may be left",
        )),
        // `panel_member` rather than `node`, which is what a region's `beside`
        // already used: a question standing in a row is the same narrow
        // allowance as a question standing in a region, and audiofiles' search
        // box is a field in a toolbar. The two spellings of one keyword had
        // drifted apart, and nothing but the drift was stopping it.
        (
            Container::Run,
            Emission::Beside {
                priority,
                width,
                inner,
            },
        ) => {
            let rank = variant(priority, "Priority")?;
            let member = panel_member(inner)?;
            let Some(width) = width else {
                return Ok((member, quote!(.beside(#held, #rank))));
            };
            let share = variant(width, "Width")?;
            Ok((member, quote!(.spread(#held, #rank, #share))))
        }
        (Container::Run, other) => Err(syn::Error::new(
            emission_span(other),
            "a row ranks what it holds: write `beside <priority> <emission>`",
        )),
        (Container::Table, Emission::Column { name, body }) => {
            Ok((column(name, body)?, quote!(.column(#held))))
        }
        (Container::Table, Emission::Cells(body)) => Ok((cells(body)?, quote!(.row(#held)))),
        // A row another shape built. `item_sales` splits its columns from its
        // cells on purpose, so the row arrives whole rather than being written
        // inside the table.
        (Container::Table, Emission::Include(supplier)) => {
            let supplier = hole(supplier)?;
            Ok((
                quote!(::std::convert::Into::into(#supplier)),
                quote!(.row(#held)),
            ))
        }
        (Container::Table, other) => Err(syn::Error::new(
            emission_span(other),
            "a table holds columns and rows: write `column <name>;`, `cells { .. }` \
             or `include <shape>;`",
        )),
        (Container::Cell, Emission::Act { .. }) => Ok((act(emission)?, quote!(.act(#held)))),
        // A control another shape built, as a row takes one. `item_files`'s
        // acts column holds a Download written here and a Delete that is
        // `version_delete_act`'s whole subject.
        (Container::Cell, Emission::Include(supplier)) => {
            let supplier = hole(supplier)?;
            Ok((
                quote!(::std::convert::Into::into(#supplier)),
                quote!(.act(#held)),
            ))
        }
        // A cell is a run of leaves, which is what `Cell::part` is for.
        // `git_blame`'s commit cell carries the short oid and, when the commit
        // has annotations, a second link to its notes; its code cell carries the
        // line. A control is still `.act`, so a supplier reached by `include`
        // stays a control and a node member is a part.
        (Container::Cell, other) => Ok((node(other)?, quote!(.part(#held)))),
        (
            Container::Node,
            Emission::Offering {
                label,
                action,
                body,
            },
        ) => {
            let label = arg(label)?;
            let called = self::action(action)?;
            let way_out = accrete(
                body,
                Container::Act,
                &quote!(::quasi_router::Act::new(#label, #called)),
            )?;
            Ok((way_out, quote!(.offering(#held))))
        }
        (Container::Node, other) => Err(syn::Error::new(
            emission_span(other),
            "a node member is told settings and a way out: write `offering <label> to <action>;`",
        )),
        (Container::Column, other) => Err(syn::Error::new(
            emission_span(other),
            "a column holds no members: its body says how it narrows",
        )),
        (Container::Timeline, Emission::At { at, inner }) => {
            let at = arg(at)?;
            // A supplier, the same courtesy `include` is everywhere else:
            // goingson's day view draws the axis and the all-day strip from
            // one row shape, so the row is a shape away from both. An inline
            // row is not a form until a screen wants one.
            let row = match &**inner {
                Emission::Include(supplier) => {
                    let supplier = hole(supplier)?;
                    quote!(::std::convert::Into::into(#supplier))
                }
                other => {
                    return Err(syn::Error::new(
                        emission_span(other),
                        "an axis holds rows another shape builds: write `at <placement> include <supplier>;`",
                    ));
                }
            };
            Ok((
                quote!(::quasi_router::screen::Placed {
                    placement: #at,
                    row: #row,
                }),
                quote!(.placed(#held)),
            ))
        }
        (Container::Timeline, other) => Err(syn::Error::new(
            emission_span(other),
            "an axis holds what sits on it: write `at <placement> include <supplier>;`",
        )),
        (
            Container::Act,
            Emission::Field {
                kind,
                name,
                label,
                body,
            },
        ) => {
            // `Act::asking`: a control that wants a value before it acts.
            // goingson's day view is the site -- placing a task asks which slot
            // and, when the task carries no estimate, how long it takes.
            let asked = field(kind, name, label, body)?;
            Ok((asked, quote!(.asking(#held))))
        }
        (Container::Act | Container::Field, other) => Err(syn::Error::new(
            emission_span(other),
            "this holds no members: its body says what it is like",
        )),
    }
}

/// One guard, as the `bool` it tests.
pub(crate) fn predicate(guard: &Guard) -> Result<TokenStream> {
    let test = clause(&guard.predicate)?;
    Ok(if guard.negated {
        quote!(!(#test))
    } else {
        test
    })
}

fn clause(predicate: &Predicate) -> Result<TokenStream> {
    Ok(match predicate {
        Predicate::Joined {
            connective,
            clauses,
        } => {
            let operator: TokenStream = if connective == "and" { "&&" } else { "||" }
                .parse()
                .expect("a connective");
            let clauses = clauses.iter().map(clause).collect::<Result<Vec<_>>>()?;
            let mut joined = TokenStream::new();
            for (index, one) in clauses.into_iter().enumerate() {
                if index > 0 {
                    joined.extend(operator.clone());
                }
                joined.extend(quote!((#one)));
            }
            joined
        }
        Predicate::Not(inner) => {
            let inner = clause(inner)?;
            quote!(!(#inner))
        }
        Predicate::Truth(hole) => self::hole(hole)?,
        Predicate::Comparison {
            left,
            compare,
            right,
        } => {
            let spelling = compare.to_string();
            let operator = COMPARISONS
                .iter()
                .find(|(known, _)| *known == spelling)
                .map(|(_, operator)| *operator)
                .ok_or_else(|| {
                    syn::Error::new(compare.span(), format!("`{spelling}` is not a comparison"))
                })?;
            let operator: TokenStream = operator.parse().expect("a comparison operator");
            let left = self::hole(left)?;
            let right = arg(right)?;
            quote!(#left #operator #right)
        }
    })
}

/// One member of a region or of a panel, as the `Node` it is.
///
/// [`node`] plus the one emission that is a node only in these two places. A
/// question standing in a region rather than in a form is what a consulting
/// region is made of -- it gathers the dials it contains and sends them itself,
/// so there is no form to put them in -- and a `-> Vec<Node>` panel is a
/// region's members with the region spread off, so the same holds there.
///
/// Narrow on purpose. A field is still refused everywhere else, because a
/// question in a cell or a row is a question nothing will ever read.
fn panel_member(emission: &Emission) -> Result<TokenStream> {
    match emission {
        Emission::Field {
            kind,
            name,
            label,
            body,
        } => {
            let built = field(kind, name, label, body)?;
            Ok(quote!(::quasi_router::Node::field(#built)))
        }
        other => node(other),
    }
}

/// One emission as a `Node` value.
fn node(emission: &Emission) -> Result<TokenStream> {
    match emission {
        // A run of members is not a node, so it can only be written where a
        // container holds many. Refused where it is written rather than
        // reported against generated code.
        Emission::IncludeEach(_) => Err(syn::Error::new(
            Span::call_site(),
            "`include each` splices a run of members, so it belongs in a body \
             that holds many: write `include` for one node",
        )),
        // `framed` says how a member is placed, so it has no meaning where a
        // bare node is wanted. Refused where it is written rather than silently
        // losing the name.
        Emission::Framed { inner, .. } => Err(syn::Error::new(
            emission_span(inner),
            "`framed` names a member of a region that shows one at a time, \
             so it belongs where the member is placed",
        )),
        Emission::Simple { member, args, body } if member == "picture" => {
            // The one member whose body does not set on a `Node`. `Node::Image`
            // holds an `Image`, and `fit`, `lazy`, `caption` and `intrinsic`
            // are that type's builders, so the body accretes onto the picture
            // and the variant goes on afterwards. embeds' cover is the site: a
            // 40-pixel thumbnail whose art is any shape, which is `Fit::Cover`
            // and is unsayable without a body.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            let picture = accrete(
                body,
                Container::Image,
                &quote!(::quasi_router::Image::new(#(#args),*)),
            )?;
            Ok(quote!(::quasi_router::Node::Image(#picture)))
        }
        Emission::Simple { member, args, body } if member == "badge" => {
            // The third member whose body does not set on a `Node`, and the
            // first of two over `Tag`. `Node::Token` holds a `Tag`, and `token`
            // is a setting on `Row` and on `Cell` so it cannot be a member at
            // all, so the members are named for `Tag`'s constructors instead.
            // quasicoherent `e2030032` decided it over 33 sites.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            let tag = accrete(
                body,
                Container::Tag,
                &quote!(::quasi_router::screen::Tag::badge(#(#args),*)),
            )?;
            Ok(quote!(::quasi_router::Node::token(#tag)))
        }
        Emission::Chip {
            value,
            action,
            removable,
            body,
        } => {
            // The other two thirds of `badge`. A chip goes somewhere, so it
            // carries an action, which is why it is spelled
            // `chip <value> to <action>` rather than as a member with two
            // arguments. `removable` is the same member and the same shape with
            // the third constructor: a tag whose going takes it off. audiofiles'
            // detail panel is the site and `Tag` has no fourth constructor, so
            // the form now says all of them.
            let value = arg(value)?;
            let called = self::action(action)?;
            let tag = accrete(
                body,
                Container::Tag,
                &if *removable {
                    quote!(::quasi_router::screen::Tag::removable(#value, #called))
                } else {
                    quote!(::quasi_router::screen::Tag::chip(#value, #called))
                },
            )?;
            Ok(quote!(::quasi_router::Node::token(#tag)))
        }
        Emission::Simple { member, args, body } if member == "proportion" => {
            // A meter standing on its own. `Node::Meter` holds a `Meter`, so
            // the body sets on the meter the way `badge`'s sets on a `Tag`, and
            // the member is named for the row part rather than for the type:
            // `meter` is a setting on `Row` and on `Cell`, so it cannot also be
            // a member.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            let meter = accrete(
                body,
                Container::Meter,
                &quote!(::quasi_router::screen::Meter::new(#(#args),*)),
            )?;
            Ok(quote!(::quasi_router::Node::Meter(#meter)))
        }
        Emission::Simple { member, args, body } if member == "tally" => {
            // One number and what it counts, standing on its own. `Node::Figure`
            // holds a `Figure`, so the body sets on the figure the way
            // `proportion`'s sets on a `Meter`, and the member is named for what
            // it says rather than for the type: `figure` is the setting a
            // `stats` strip accretes with, so it cannot also be a member.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            let figure = accrete(
                body,
                Container::Figure,
                &quote!(::quasi_router::screen::Figure::new(#(#args),*)),
            )?;
            Ok(quote!(::quasi_router::Node::Figure(#figure)))
        }
        Emission::Simple { member, args, body } if member == "underway" => {
            // The one member whose name is not its constructor's. `Node::pending`
            // is the third `StandIn` state, beside `empty` and `failed`, and
            // `pending` is a setting on `Slot`, so the member is named for what
            // it says instead. The body still sets on a `Node`, which is what
            // `offering` wants: a stand-in with a way out of it.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            accrete(
                body,
                Container::Node,
                &quote!(::quasi_router::Node::pending(#(#args),*)),
            )
        }
        Emission::Simple { member, args, body } if member == "canvas" => {
            // The second member whose body does not set on a `Node`, and for
            // `picture`'s reason: `Node::Canvas` holds a `Canvas`, and
            // `classed`, `identified` and the nodes drawn in the scope are that
            // type's. `custom_page` is the site -- a creator's markup under the
            // scope `css_sanitizer` rewrote every one of their rules for.
            //
            // One argument always, because `Canvas::new("")` is
            // `Canvas::default()`: an item page has no creator markup and the
            // scope is still what carries the stylesheet.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            let canvas = accrete(
                body,
                Container::Canvas,
                &quote!(::quasi_router::screen::Canvas::new(#(#args),*)),
            )?;
            Ok(quote!(::quasi_router::Node::Canvas(::std::boxed::Box::new(#canvas))))
        }
        Emission::Simple { member, args, body } if member == "timeline" => {
            // The fifth member whose body is not `Node`'s own, and the only one
            // that holds members rather than settings: an axis is told what
            // sits on it and where. `Node::timeline` answers with the variant
            // already, so nothing is wrapped afterwards.
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            accrete(
                body,
                Container::Timeline,
                &quote!(::quasi_router::Node::timeline(#(#args),*)),
            )
        }
        Emission::Simple { member, args, body } => {
            let args = args.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            accrete(
                body,
                Container::Node,
                &quote!(::quasi_router::Node::#member(#(#args),*)),
            )
        }
        Emission::List(items) => list(items),
        Emission::Table(items) => {
            let table = self::table(items)?;
            Ok(quote!(::std::convert::Into::into(#table)))
        }
        Emission::Form { action, body } => form(action, body),
        Emission::Field { kind, .. } => Err(syn::Error::new(
            kind.span(),
            "a field is not a node: put it in a `form`, or give the shape `-> Field`",
        )),
        Emission::Row { .. } => Err(syn::Error::new(
            emission_span(emission),
            "a row is not a node: put it in a `list`",
        )),
        Emission::Screen { arrangement, .. } => Err(syn::Error::new(
            arrangement.span(),
            "a document is not a node",
        )),
        Emission::Link { text, action } => {
            let text = arg(text)?;
            let action = self::action(action)?;
            Ok(quote! {
                ::quasi_router::Node::Link {
                    text: ::std::convert::Into::into(#text),
                    action: #action,
                }
            })
        }
        Emission::Act { .. } => {
            let control = act(emission)?;
            Ok(quote!(::quasi_router::Node::Act(#control)))
        }
        Emission::Offers { action, .. } => Err(syn::Error::new(
            action.verb.span(),
            "`offers` is a control a row holds back; outside a row write `act`",
        )),
        Emission::Include(supplier) => {
            let supplier = hole(supplier)?;
            Ok(quote!(::std::convert::Into::into(#supplier)))
        }
        Emission::Region { name, kind, body } => {
            let slot = slot(name, kind, body)?;
            Ok(quote!(::quasi_router::Node::Region(#slot)))
        }
        Emission::Given {
            scrutinee,
            arms,
            otherwise,
        } => {
            let scrutinee = hole(scrutinee)?;
            let arms = arms
                .iter()
                .map(|(pattern, arm)| {
                    let pattern = self::pattern(pattern);
                    let arm = node(arm)?;
                    Ok(quote!(#pattern => #arm,))
                })
                .collect::<Result<Vec<_>>>()?;
            let otherwise = match otherwise {
                Some(otherwise) => {
                    let otherwise = node(otherwise)?;
                    quote!(_ => #otherwise,)
                }
                None => quote!(),
            };
            Ok(quote!(match #scrutinee { #(#arms)* #otherwise }))
        }
        Emission::Guarded { guard, .. } => Err(syn::Error::new(
            guard.span,
            "a guarded member needs a container that may hold nothing; \
             only a `-> Option<_>` shape can drop its whole result so far",
        )),
        Emission::Across { fallback, .. } => Err(syn::Error::new(
            fallback.span(),
            "a row is not a node: `across` belongs in a region",
        )),
        Emission::Column { .. } | Emission::Cells(_) | Emission::Cell { .. } => {
            Err(syn::Error::new(
                emission_span(emission),
                "a column, a row of cells and a cell are a table's, not a node's",
            ))
        }
        Emission::Activate(action) => Err(syn::Error::new(
            action.verb.span(),
            "`activate` says what opening a row or a cell does; it is not a node",
        )),
        Emission::Offering { action, .. } => Err(syn::Error::new(
            action.verb.span(),
            "`offering` is the way out an empty state offers; it is not a node",
        )),
        Emission::Beside { inner, .. } => Err(syn::Error::new(
            emission_span(inner),
            "`beside` needs a run in scope, which is rule R3",
        )),
        Emission::At { inner, .. } => Err(syn::Error::new(
            emission_span(inner),
            "`at` places a row on an axis; it needs a `timeline` in scope",
        )),
        Emission::Removes { action, .. } | Emission::Repeats { action, .. } => {
            Err(syn::Error::new(
                action.verb.span(),
                "a repeating question and the control that takes one away are a \
                 region's, not a node's",
            ))
        }
    }
}

/// One region, as the `Slot` it is. A document holds these; a body wraps them
/// in [`Node::Region`].
fn slot(name: &Arg, kind: &RegionKind, body: &[Item]) -> Result<TokenStream> {
    let name = arg(name)?;
    let kind = match kind {
        RegionKind::Variant(variant) => quote!(::quasi_router::RegionKind::#variant),
        RegionKind::Supplied(hole) => self::hole(hole)?,
    };
    accrete(
        body,
        Container::Slot,
        &quote!(::quasi_router::Slot::new(#name, #kind)),
    )
}

/// A region's `label`, taken out of its body.
///
/// Answers the label and the rest of the body without it. The label is not a
/// setting on the region any more: it names the control that reveals the region,
/// so it belongs to the placement, and [`Slot::frame`] is the only thing that
/// takes one.
///
/// A guarded `label` is refused rather than hoisted. A frame's name is not
/// something a request decides -- a tab whose text comes and goes is a strip
/// that changes shape under the reader -- and hoisting it would move the guard
/// somewhere it no longer guards what it was written next to.
fn labelled(body: &[Item]) -> Result<(Option<TokenStream>, Vec<Item>)> {
    let mut label = None;
    let mut rest = Vec::with_capacity(body.len());

    for item in body {
        let Item::Attribute { name, args, guard } = item else {
            rest.push(item.clone());
            continue;
        };
        if name != "label" {
            rest.push(item.clone());
            continue;
        }
        if guard.is_some() {
            return Err(syn::Error::new(
                name.span(),
                "a frame's name is not something a request decides: \
                 drop the guard, or guard the whole region",
            ));
        }
        let [only] = args.as_slice() else {
            return Err(syn::Error::new(
                name.span(),
                "`label` names the control that reveals this region: one name",
            ));
        };
        if label.is_some() {
            return Err(syn::Error::new(name.span(), "a region has one name"));
        }
        label = Some(arg(only)?);
    }

    Ok((label, rest))
}

/// The loop's binder, dereferenced where the declaration said to.
fn binder_pattern(dereferenced: bool, binder: &proc_macro2::Ident) -> TokenStream {
    if dereferenced {
        quote!(&#binder)
    } else {
        quote!(#binder)
    }
}

/// One form: where it writes, what its button says, and what it asks.
///
/// The fields are pushed rather than written into a `vec![]` literal because a
/// field may be guarded, which is what `settings::email`'s advanced block asked
/// for: six server questions that are on the form only while the disclosure is
/// open. R9 holds here as everywhere else -- the field is built whether or not
/// it is asked -- so a supplier feeding a question nobody sees is still called
/// and still answers.
fn form(action: &Action, body: &[Item]) -> Result<TokenStream> {
    let mut submit = None;
    let mut asked = Vec::new();
    let held = format_ident!("asked", span = Span::call_site());
    for (index, item) in body.iter().enumerate() {
        match item {
            Item::Attribute { name, args, guard } if name == "submit" => {
                let [label] = args.as_slice() else {
                    return Err(syn::Error::new(name.span(), "`submit` says one thing"));
                };
                if let Some(guard) = guard {
                    return Err(syn::Error::new(
                        guard.span,
                        "a form always has a button: `submit` takes no guard",
                    ));
                }
                submit = Some(arg(label)?);
            }
            Item::Emit(Emission::Field {
                kind,
                name,
                label,
                body,
            }) => {
                let built = field(kind, name, label, body)?;
                asked.push(quote!(#held.push(#built);));
            }
            // A question another shape built, which is the courtesy every other
            // container already extends: a table takes a row, a cell takes a
            // control, a region takes a field. A form was the one that did not,
            // so two ends of an interval or four bounded millisecond boxes had
            // to be written out per form. audiofiles' editor is the site --
            // `span` twice in one form and `milliseconds` four times across two.
            Item::Emit(Emission::Include(supplier)) => {
                let supplier = self::hole(supplier)?;
                asked.push(quote!(#held.push(::std::convert::Into::into(#supplier));));
            }
            Item::Emit(Emission::Guarded { guard, inner }) => {
                let Emission::Field {
                    kind,
                    name,
                    label,
                    body,
                } = &**inner
                else {
                    return Err(syn::Error::new(
                        emission_span(inner),
                        "a form holds fields, and only a field may be guarded here",
                    ));
                };
                let built = field(kind, name, label, body)?;
                let test = predicate(guard)?;
                let question = format_ident!("question_{index}", span = Span::call_site());
                asked.push(quote!({
                    let #question = #built;
                    if #test {
                        #held.push(#question);
                    }
                }));
            }
            Item::Attribute { name, .. } => {
                return Err(syn::Error::new(
                    name.span(),
                    "a form says `submit` and asks fields, and nothing else yet",
                ));
            }
            Item::Bind { name, .. } => {
                return Err(syn::Error::new(name.span(), "a form binds nothing"));
            }
            Item::For { binder, .. } => {
                return Err(syn::Error::new(
                    binder.span(),
                    "a form's fields are written out; a loop over them is not a production yet",
                ));
            }
            Item::Emit(other) => {
                return Err(syn::Error::new(
                    emission_span(other),
                    "a form holds fields: write `field <kind> <name> <label>` or \
                     `include <shape>;`",
                ));
            }
        }
    }
    let Some(submit) = submit else {
        return Err(syn::Error::new(
            action.verb.span(),
            "a form says what its button reads: `submit <text>;`",
        ));
    };
    let action = self::action(action)?;
    Ok(quote! {
        ::quasi_router::Node::Form {
            action: #action,
            submit: ::std::convert::Into::into(#submit),
            fields: {
                let mut #held = ::std::vec::Vec::new();
                #(#asked)*
                #held
            },
        }
    })
}

/// One field: what it asks for, by name, under a label.
fn field(kind: &proc_macro2::Ident, name: &Arg, label: &Arg, body: &[Item]) -> Result<TokenStream> {
    let name = arg(name)?;
    let label = arg(label)?;
    accrete(
        body,
        Container::Field,
        &quote!(::quasi_router::Field::new(
            ::quasi_router::layout::FieldKind::#kind,
            #name,
            #label
        )),
    )
}

/// A panel's members, in order, with nothing wrapping them.
///
/// The `-> Vec<Node>` shape. Kept apart from [`accumulate`] rather than folded
/// into it: every other container is told `.with(member)` and answers with
/// itself, and a `Vec` is told `push` and answers with nothing, so one of the
/// two spellings would have had to be special-cased inside the general form
/// anyway.
fn nodes(items: &[Item]) -> Result<TokenStream> {
    let held = format_ident!("nodes", span = Span::call_site());
    let statements = node_statements(items, &held)?;
    Ok(quote!({
        let mut #held = ::std::vec::Vec::new();
        #(#statements)*
        #held
    }))
}

/// A menu's entries, in order.
///
/// [`nodes`]' twin, and narrower: every member is an `act`, because a menu is
/// nothing but controls. A guard and a loop work the way they do everywhere
/// else, which is the whole reason this exists -- audiofiles' row menu is
/// fourteen entries of which nine are conditional.
fn acts(items: &[Item]) -> Result<TokenStream> {
    let held = format_ident!("entries", span = Span::call_site());
    let statements = act_statements(items, &held)?;
    Ok(quote!({
        let mut #held = ::std::vec::Vec::new();
        #(#statements)*
        #held
    }))
}

fn act_statements(items: &[Item], entries: &proc_macro2::Ident) -> Result<Vec<TokenStream>> {
    items
        .iter()
        .map(|item| match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                Ok(quote!(let #name = #value;))
            }
            Item::For {
                dereferenced,
                binder,
                iterable,
                body,
            } => {
                let iterable = hole(iterable)?;
                let inner = act_statements(body, entries)?;
                let binder = binder_pattern(*dereferenced, binder);
                Ok(quote!(for #binder in #iterable { #(#inner)* }))
            }
            // R9, as everywhere else: the entry is built whether or not the
            // guard places it.
            Item::Emit(Emission::Guarded { guard, inner }) => {
                let test = predicate(guard)?;
                let value = act(inner)?;
                let held = format_ident!("entry", span = Span::call_site());
                Ok(quote!({
                    let #held = #value;
                    if #test {
                        #entries.push(#held);
                    }
                }))
            }
            Item::Emit(emission) => {
                let value = act(emission)?;
                Ok(quote!(#entries.push(#value);))
            }
            Item::Attribute { name, .. } => Err(syn::Error::new(
                name.span(),
                "a menu sets nothing: say it on the entry it belongs to",
            )),
        })
        .collect()
}

fn node_statements(items: &[Item], nodes: &proc_macro2::Ident) -> Result<Vec<TokenStream>> {
    items
        .iter()
        .map(|item| match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                Ok(quote!(let #name = #value;))
            }
            Item::For {
                dereferenced,
                binder,
                iterable,
                body,
            } => {
                let iterable = hole(iterable)?;
                let inner = node_statements(body, nodes)?;
                let binder = binder_pattern(*dereferenced, binder);
                Ok(quote!(for #binder in #iterable { #(#inner)* }))
            }
            Item::Emit(Emission::Guarded { guard, inner }) => {
                let test = predicate(guard)?;
                let value = panel_member(inner)?;
                // R9, as everywhere else: the guard decides whether the member
                // is placed, and the holes inside it are evaluated either way.
                let member = format_ident!("member", span = Span::call_site());
                Ok(quote!({
                    let #member = #value;
                    if #test {
                        #nodes.push(#member);
                    }
                }))
            }
            Item::Emit(emission) => {
                let value = panel_member(emission)?;
                Ok(quote!(#nodes.push(#value);))
            }
            // The one attribute a panel takes, and it means in a panel what it
            // means on a region: splice another shape's nodes in here. A panel
            // built out of panels had no spelling until goingson's Sharing
            // section, which is eight of them under one heading.
            Item::Attribute { name, args, guard } if name == "extend" => {
                let spliced = args.iter().map(arg).collect::<Result<Vec<_>>>()?;
                let extending = quote!(#(#nodes.extend(#spliced);)*);
                guard.as_ref().map_or_else(
                    || Ok(extending.clone()),
                    |guard| {
                        let test = predicate(guard)?;
                        Ok(quote!(if #test { #extending }))
                    },
                )
            }
            Item::Attribute { name, .. } => Err(syn::Error::new(
                name.span(),
                "a panel sets nothing but `extend`: say it on the member it belongs to",
            )),
        })
        .collect()
}

/// The rows of a list, built where they are read.
///
/// `more` is the one thing a list sets rather than says on a row, because it is
/// about the list and not about any row in it: what is left over, and the
/// address that fetches it. goingson's mail list is the site -- the query hands
/// back the page and the total in one call, so the description carries both
/// numbers and `Rest` derives the difference.
fn list(items: &[Item]) -> Result<TokenStream> {
    let rows = format_ident!("rows", span = Span::call_site());
    let rest = format_ident!("rest", span = Span::call_site());
    let mut more = Vec::new();
    let mut body = Vec::new();
    for item in items {
        match item {
            Item::Attribute { name, args, guard } if name == "more" => {
                let [only] = args.as_slice() else {
                    return Err(syn::Error::new(
                        name.span(),
                        "`more` says what is left over: one `Rest`",
                    ));
                };
                let value = arg(only)?;
                let setting = quote!(#rest = ::std::option::Option::Some(#value););
                more.push(match guard {
                    None => setting,
                    Some(guard) => {
                        let test = predicate(guard)?;
                        quote!(if #test { #setting })
                    }
                });
            }
            other => body.push(other),
        }
    }
    let statements = list_statements(&body, &rows)?;
    if more.is_empty() {
        return Ok(quote!({
            let mut #rows = ::std::vec::Vec::new();
            #(#statements)*
            ::quasi_router::Node::list(#rows)
        }));
    }
    Ok(quote!({
        let mut #rows = ::std::vec::Vec::new();
        #(#statements)*
        let mut #rest = ::std::option::Option::None;
        #(#more)*
        ::quasi_router::Node::Table {
            columns: ::std::vec::Vec::new(),
            rows: #rows,
            more: #rest,
        }
    }))
}

fn list_statements(items: &[&Item], rows: &proc_macro2::Ident) -> Result<Vec<TokenStream>> {
    items
        .iter()
        .map(|item| match item {
            Item::Bind { name, source } => {
                let value = source_value(source)?;
                Ok(quote!(let #name = #value;))
            }
            Item::For {
                dereferenced,
                binder,
                iterable,
                body,
            } => {
                let iterable = hole(iterable)?;
                let inner = list_statements(&body.iter().collect::<Vec<_>>(), rows)?;
                let binder = binder_pattern(*dereferenced, binder);
                Ok(quote!(for #binder in #iterable { #(#inner)* }))
            }
            // R9 again: the row is built whether or not the guard places it.
            Item::Emit(Emission::Guarded { guard, inner }) => {
                let test = predicate(guard)?;
                let value = list_row(inner)?;
                let held = format_ident!("member", span = Span::call_site());
                Ok(quote!({
                    let #held = #value;
                    if #test {
                        #rows.push(#held);
                    }
                }))
            }
            Item::Emit(emission) => {
                let row = list_row(emission)?;
                Ok(quote!(#rows.push(#row);))
            }
            Item::Attribute { name, .. } => Err(syn::Error::new(
                name.span(),
                "a list sets nothing but `more`: say it on the row",
            )),
        })
        .collect()
}

/// One row of a list, written here or built by another shape.
///
/// `export_portal` demanded the second: five of its six cards come off a const
/// and the sixth is the asynchronous export, which is a shape of its own and is
/// drawn only for a reader who has files. The table already took an `include`
/// for the same reason, and this is the list saying it the same way.
fn list_row(emission: &Emission) -> Result<TokenStream> {
    match emission {
        Emission::Row { primary, body } => row(Some(primary), body),
        Emission::Include(supplier) => {
            let supplier = hole(supplier)?;
            Ok(quote!(::std::convert::Into::into(#supplier)))
        }
        other => Err(syn::Error::new(
            emission_span(other),
            "a list holds rows: write `row <primary> { .. }` or `include <shape>;`",
        )),
    }
}

/// One table: its columns, its rows, and what it has not shown.
///
/// Both halves accrete. `Table::new` takes its columns as a list and the form
/// has no expression to hold one in, so `Table::column` was added beside it
/// rather than the form growing a production that admits a list of built
/// values. Columns before rows is the vocabulary's own rule and this emits them
/// in the order they were written, so a declaration that gets it wrong trips
/// `Table::row`'s assertion rather than losing a cell quietly.
fn table(items: &[Item]) -> Result<TokenStream> {
    accrete(
        items,
        Container::Table,
        &quote!(::quasi_router::screen::Table::new(::std::iter::empty())),
    )
}

/// One column: what it is called, and how it narrows.
fn column(name: &Arg, body: &[Item]) -> Result<TokenStream> {
    let name = arg(name)?;
    accrete(
        body,
        Container::Column,
        &quote!(::quasi_router::screen::Column::new(#name)),
    )
}

/// One row of a table, by position. `row` with no primary.
fn cells(body: &[Item]) -> Result<TokenStream> {
    row(None, body)
}

/// One cell: what it says, what it holds, and what opening it does.
fn cell(value: &Arg, body: &[Item]) -> Result<TokenStream> {
    let value = arg(value)?;
    accrete(
        body,
        Container::Cell,
        &quote!(::quasi_router::screen::Cell::new(#value)),
    )
}

/// One row: what it says, what it holds, and what it offers.
///
/// One function since the 2026-09-05 collapse. `row "x" { .. }` and `cells {
/// .. }` were two builders onto what is now one type, differing only in whether
/// a primary was named: a list row opens with its primary text and a table row
/// opens empty and fills by key. That is an argument, not a second function.
fn row(primary: Option<&Arg>, body: &[Item]) -> Result<TokenStream> {
    let base = match primary {
        Some(primary) => {
            let primary = arg(primary)?;
            quote!(::quasi_router::Row::new(#primary))
        }
        None => quote!(<::quasi_router::Row as ::std::default::Default>::default()),
    };
    accrete(body, Container::Row, &base)
}

/// One control: what it is called, what it does, and what it is like.
fn act(emission: &Emission) -> Result<TokenStream> {
    let (Emission::Act {
        label,
        action,
        body,
    }
    | Emission::Offers {
        label,
        action,
        body,
    }) = emission
    else {
        return Err(syn::Error::new(
            emission_span(emission),
            "expected a control here",
        ));
    };
    let label = arg(label)?;
    let called = self::action(action)?;
    accrete(
        body,
        Container::Act,
        &quote!(::quasi_router::Act::new(#label, #called)),
    )
}

fn action(action: &Action) -> Result<TokenStream> {
    let Action {
        verb,
        target,
        modifiers,
    } = action;
    let called = if verb == "doing" {
        // Amendment 6: the supplier IS the action.
        let Some(target) = target else {
            return Err(syn::Error::new(verb.span(), "`doing` names a supplier"));
        };
        arg(target)?
    } else {
        let target = match target {
            Some(target) => arg(target)?,
            None => quote!(),
        };
        quote!(::quasi_router::Action::#verb(#target))
    };
    let modifiers = modifiers
        .iter()
        .map(|modifier| {
            let name = &modifier.name;
            let args = modifier.args.iter().map(arg).collect::<Result<Vec<_>>>()?;
            Ok(quote!(.#name(#(#args),*)))
        })
        .collect::<Result<Vec<_>>>()?;
    Ok(quote!(#called #(#modifiers)*))
}

fn source(source: &Source, owned: bool) -> Result<TokenStream> {
    match source {
        Source::Str(text) => Ok(interpolated(text, owned)),
        Source::Hole(hole) => self::hole(hole),
        Source::Choose {
            scrutinee,
            arms,
            otherwise,
        } => {
            let scrutinee = self::hole(scrutinee)?;
            let arms = arms
                .iter()
                .map(|(pattern, value)| {
                    let pattern = self::pattern(pattern);
                    let value = self::source(value, owned)?;
                    Ok(quote!(#pattern => #value,))
                })
                .collect::<Result<Vec<_>>>()?;
            let otherwise = self::source(otherwise, owned)?;
            Ok(quote! {
                match #scrutinee {
                    #(#arms)*
                    _ => #otherwise,
                }
            })
        }
    }
}

/// Whether a source's arms have to agree on `String`.
///
/// A dispatch whose arms are all strings and at least one of which interpolates
/// mixes a `&'static str` with a `String`, which is the split the record's
/// amendment 10 reached for with a `&`/`owned` spelling. It does not need one:
/// the arms of one dispatch have to agree on a type, so the dispatch decides
/// the ownership for all of them, and nothing outside a dispatch has an
/// ambiguity to settle.
fn owned_arms(source: &Source) -> bool {
    let Source::Choose {
        arms, otherwise, ..
    } = source
    else {
        return false;
    };
    let every = arms
        .iter()
        .map(|(_, value)| value)
        .chain(std::iter::once(&**otherwise));
    let mut all_strings = true;
    let mut any_interpolates = false;
    for value in every {
        match value {
            Source::Str(text) => {
                any_interpolates |= text
                    .parts
                    .iter()
                    .any(|part| matches!(part, StrPart::Hole(_)));
            }
            _ => all_strings = false,
        }
    }
    all_strings && any_interpolates
}

fn pattern(pattern: &Pattern) -> TokenStream {
    match pattern {
        Pattern::Int(value) => {
            let value = proc_macro2::Literal::i64_unsuffixed(*value);
            quote!(#value)
        }
        Pattern::Str(value) => {
            let value = LitStr::new(value, Span::call_site());
            quote!(#value)
        }
        Pattern::Bool(value) => quote!(#value),
        Pattern::Path(path) => quote!(#path),
    }
}

fn interpolated(text: &Interpolated, owned: bool) -> TokenStream {
    let mut format = String::new();
    let mut holes = Vec::new();
    for part in &text.parts {
        match part {
            StrPart::Lit(literal) => {
                for character in literal.chars() {
                    if character == '{' || character == '}' {
                        format.push(character);
                    }
                    format.push(character);
                }
            }
            StrPart::Hole(hole) => {
                format.push_str("{}");
                holes.push(hole);
            }
        }
    }
    let literal = LitStr::new(&format, text.span);

    if holes.is_empty() {
        return if owned {
            quote!(::std::string::String::from(#literal))
        } else {
            quote!(#literal)
        };
    }

    let holes = holes
        .iter()
        .map(|hole| self::hole(hole).unwrap_or_else(syn::Error::into_compile_error));
    quote!(::std::format!(#literal, #(#holes),*))
}

pub(crate) fn hole(hole: &Hole) -> Result<TokenStream> {
    let mut built = match &hole.root {
        HoleRoot::Binding(name) => quote!(#name),
        HoleRoot::Path(path) => quote!(#path),
        HoleRoot::Call { path, args } => {
            let args = args.iter().map(arg).collect::<Result<Vec<_>>>()?;
            quote!(#path(#(#args),*))
        }
    };
    for step in &hole.steps {
        built = match step {
            Step::Field(name) => quote!(#built.#name),
            Step::Method { name, args } => {
                let args = args.iter().map(arg).collect::<Result<Vec<_>>>()?;
                quote!(#built.#name(#(#args),*))
            }
        };
    }
    Ok(built)
}

pub(crate) fn arg(arg: &Arg) -> Result<TokenStream> {
    match arg {
        Arg::Str(text) => Ok(interpolated(text, false)),
        Arg::Hole(hole) => self::hole(hole),
        Arg::Int(value) => {
            let value = proc_macro2::Literal::i64_unsuffixed(*value);
            Ok(quote!(#value))
        }
        Arg::Bool(value) => Ok(quote!(#value)),
        Arg::List(items) => {
            let items = items.iter().map(self::arg).collect::<Result<Vec<_>>>()?;
            Ok(quote!([#(#items),*]))
        }
        Arg::Borrow(inner) => {
            let inner = self::arg(inner)?;
            Ok(quote!(&#inner))
        }
    }
}

fn emission_span(emission: &Emission) -> Span {
    match emission {
        Emission::Framed { inner, .. } => emission_span(inner),
        Emission::Include(_) | Emission::IncludeEach(_) | Emission::Link { .. } => {
            Span::call_site()
        }
        Emission::Simple { member, .. } => member.span(),
        Emission::Screen { arrangement, .. } => arrangement.span(),
        Emission::Row { .. } | Emission::List(_) => Span::call_site(),
        Emission::Form { action, .. } | Emission::Chip { action, .. } => action.verb.span(),
        Emission::Field { kind, .. } => kind.span(),
        Emission::Act { action, .. }
        | Emission::Offers { action, .. }
        | Emission::Removes { action, .. }
        | Emission::Repeats { action, .. } => action.verb.span(),
        Emission::Guarded { guard, .. } => guard.span,
        Emission::Given { .. } => Span::call_site(),
        Emission::Region { kind, .. } => match kind {
            RegionKind::Variant(variant) => variant.span(),
            RegionKind::Supplied(_) => Span::call_site(),
        },
        Emission::Across { fallback, .. } => fallback.span(),
        Emission::Beside { inner, .. } => emission_span(inner),
        Emission::At { inner, .. } => emission_span(inner),
        Emission::Table(_) | Emission::Cells(_) => Span::call_site(),
        Emission::Column { .. } | Emission::Cell { .. } => Span::call_site(),
        Emission::Activate(action) => action.verb.span(),
        Emission::Offering { action, .. } => action.verb.span(),
    }
}