ifc_lite_processing/

prepass.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Canonical prepass resolution — the single post-scan step that turns the
//! entity spans a scan collected into the style / material / void context the
//! per-element producer ([`crate::element`]) consumes.
//!
//! Both pipelines run this exact code:
//! - the native orchestrator (`processor.rs`) span-stashes during its scan and
//!   resolves here before the rayon loop;
//! - the browser prepasses (`buildPrePassOnce` / `buildPrePassStreaming` in
//!   `wasm-bindings`) span-stash during their scans and resolve here before
//!   serialising the flat wire arrays.
//!
//! The two scan loops remain per-pipeline (they are mechanical `match`-arms
//! over type names with pipeline-specific extras: quick-metadata, properties,
//! incremental job emission), but everything SEMANTIC — styled-item
//! precedence, IfcIndexedColourMap fallback, the #407 material chain, void
//! collection and aggregate propagation (#845), and unit-scale resolution —
//! lives here exactly once. The historic #858/#913-class drift was always in
//! this resolution layer, not in the span stashing.

use crate::style::{FullIndexedColourMap, GeometryStyleInfo};
use ifc_lite_core::{
    express_id::parse_express_id, find_keyword, keyword_eq, DecodedEntity, EntityDecoder,
};
use rustc_hash::FxHashMap;

/// One stashed entity span: `(express_id, start, end)`.
pub type Span = (u32, usize, usize);

/// Entity spans a scan collected for post-scan resolution (no mid-scan decode).
#[derive(Debug, Default, Clone)]
pub struct PrepassSpans {
    /// `IFCSTYLEDITEM` — geometry-attached AND orphan (material appearance);
    /// the resolver classifies them (decoding is the cost of telling them apart).
    pub styled_items: Vec<Span>,
    /// `IFCINDEXEDCOLOURMAP` (#663/#858 — CATIA/3DEXPERIENCE per-triangle palettes).
    pub indexed_colour_maps: Vec<Span>,
    /// `IFCMATERIALDEFINITIONREPRESENTATION` (#407 material chain).
    pub material_def_reprs: Vec<Span>,
    /// `IFCRELASSOCIATESMATERIAL` (#407 material chain).
    pub rel_associates_material: Vec<Span>,
    /// `IFCRELVOIDSELEMENT` — host → opening.
    pub void_rels: Vec<Span>,
    /// `IFCRELFILLSELEMENT` — opening → filling (window/door); drives the
    /// native opening filter. Cheap to collect everywhere.
    pub fills_rels: Vec<Span>,
    /// `IFCRELAGGREGATES` — parent → children, for aggregate void
    /// propagation (#845, IfcWallElementedCase etc.).
    pub aggregate_rels: Vec<Span>,
    pub defines_by_type: Vec<Span>, // IFCRELDEFINESBYTYPE, for prepass_type_material.
}

impl PrepassSpans {
    /// Stash `(id, start, end)` under the list `type_name` belongs to, and say
    /// whether it belonged to one at all.
    ///
    /// `type_name` is the raw keyword from `EntityScanner::next_entity`, in
    /// whatever case the file wrote it, so the dispatch goes through
    /// [`keyword_eq`]. Every scan loop that only needs the span lists calls
    /// this instead of spelling the same keyword table again; `processor::mod`
    /// keeps its own arms (its `continue`s interleave with other work) but
    /// compares the same way.
    pub fn stash(&mut self, type_name: &str, id: u32, start: usize, end: usize) -> bool {
        let list = if keyword_eq(type_name, "IFCSTYLEDITEM") {
            &mut self.styled_items
        } else if keyword_eq(type_name, "IFCINDEXEDCOLOURMAP") {
            &mut self.indexed_colour_maps
        } else if keyword_eq(type_name, "IFCMATERIALDEFINITIONREPRESENTATION") {
            &mut self.material_def_reprs
        } else if keyword_eq(type_name, "IFCRELASSOCIATESMATERIAL") {
            &mut self.rel_associates_material
        } else if keyword_eq(type_name, "IFCRELVOIDSELEMENT") {
            &mut self.void_rels
        } else if keyword_eq(type_name, "IFCRELFILLSELEMENT") {
            &mut self.fills_rels
        } else if keyword_eq(type_name, "IFCRELAGGREGATES") {
            &mut self.aggregate_rels
        } else if keyword_eq(type_name, "IFCRELDEFINESBYTYPE") {
            &mut self.defines_by_type
        } else {
            return false;
        };
        list.push((id, start, end));
        true
    }
}

/// Resolution switches (both pipelines share the resolver).
#[derive(Debug, Clone, Copy)]
pub struct ResolveOptions {
    /// Collect the FULL per-triangle palette maps (#858). The native pipeline
    /// consumes them in-process; the browser prepass leaves this off (each
    /// process worker rebuilds its own copy — shipping full palettes over the
    /// JS boundary would dwarf the styles arrays).
    pub collect_indexed_colour_full: bool,
    /// Defer geometry-attached styled items: classify and resolve ORPHAN
    /// styled items now (#913 §2c — the material chain needs them up front),
    /// but return attached spans unresolved on
    /// [`ResolvedPrepass::deferred_attached_styled_spans`] for a later
    /// [`resolve_styled_item_spans`] replay. Native `fast_first_batch` mode.
    pub defer_attached_styles: bool,
}

impl Default for ResolveOptions {
    fn default() -> Self {
        Self {
            collect_indexed_colour_full: true,
            defer_attached_styles: false,
        }
    }
}

/// Everything the post-scan resolution produces.
#[derive(Debug, Default)]
pub struct ResolvedPrepass {
    /// Geometry item id → resolved style (styled items first in file order,
    /// then IfcIndexedColourMap dominant colours fill the gaps — styled items
    /// win, #913 precedence).
    pub geometry_style_index: FxHashMap<u32, GeometryStyleInfo>,
    /// Geometry item id → dominant palette colour (#858).
    pub indexed_colour_index: FxHashMap<u32, [f32; 4]>,
    /// Geometry item id → full per-triangle palette (#858); empty unless
    /// [`ResolveOptions::collect_indexed_colour_full`].
    pub indexed_colour_full: FxHashMap<u32, FullIndexedColourMap>,
    /// Orphan `IfcStyledItem` colours (material appearances, #407).
    pub orphan_styled_items: FxHashMap<u32, [f32; 4]>,
    /// Material id → styled representation ids (#407).
    pub material_def_reprs: FxHashMap<u32, Vec<u32>>,
    /// Element id → material(-select) id (#407).
    pub element_to_material: FxHashMap<u32, u32>,
    /// Element id → material colour list (#407/#913 §2.3 transparent/opaque
    /// alternation for window/door parts). The canonical join.
    pub element_material_colors: FxHashMap<u32, Vec<[f32; 4]>>,
    /// Host element id → opening ids, AFTER aggregate propagation (#845).
    pub void_index: FxHashMap<u32, Vec<u32>>,
    /// Opening id → filling element id (native opening filter input).
    pub filling_by_opening: FxHashMap<u32, u32>,
    /// Geometry-attached styled spans left unresolved under
    /// [`ResolveOptions::defer_attached_styles`]; replay via [`resolve_styled_item_spans`].
    pub deferred_attached_styled_spans: Vec<(usize, usize)>,
}

pub use crate::prepass_styled::{resolve_styled_items_into, StyleSeeds};

/// THE canonical post-scan resolution (file-order, first-wins precedence).
pub fn resolve_prepass(
    spans: &PrepassSpans,
    decoder: &mut EntityDecoder,
    opts: ResolveOptions,
) -> ResolvedPrepass {
    resolve_prepass_with_style_seeds(spans, decoder, opts, None)
}

/// [`resolve_prepass`] with PRE-RESOLVED styled maps (sharded pre-pass). Seeds
/// MUST install before the material/void loops: the material chain consults
/// `orphan_styled_items` — injecting after loses material-dependent styles.
pub fn resolve_prepass_with_style_seeds(
    spans: &PrepassSpans,
    decoder: &mut EntityDecoder,
    opts: ResolveOptions,
    style_seeds: Option<StyleSeeds>,
) -> ResolvedPrepass {
    let mut out = ResolvedPrepass::default();

    if let Some((orphan, geom)) = style_seeds {
        out.orphan_styled_items = orphan;
        out.geometry_style_index = geom;
    }
    // ── Styled items: orphan (material appearance) vs geometry-attached ──
    resolve_styled_items_into(
        &spans.styled_items,
        decoder,
        opts.defer_attached_styles,
        &mut out.orphan_styled_items,
        &mut out.geometry_style_index,
        &mut out.deferred_attached_styled_spans,
    );

    // ── IfcIndexedColourMap (#663/#858) ──
    for &(id, start, end) in &spans.indexed_colour_maps {
        let Ok(icm) = decoder.decode_at_with_id(id, start, end) else {
            continue;
        };
        let Some(full) = crate::style::resolve_indexed_colour_map_full(&icm, decoder) else {
            continue;
        };
        let geometry_id = full.geometry_id;
        out.indexed_colour_index
            .entry(geometry_id)
            .or_insert(full.dominant().to_array());
        if opts.collect_indexed_colour_full {
            out.indexed_colour_full.entry(geometry_id).or_insert(full);
        }
    }

    // ── Material chain inputs (#407) ──
    for &(id, start, end) in &spans.material_def_reprs {
        if let Ok(entity) = decoder.decode_at_with_id(id, start, end) {
            // RepresentedMaterial (attr 3) → Representations (attr 2).
            if let Some(material_id) = entity.get_ref(3) {
                if let Some(reprs) = refs_from_list(&entity, 2) {
                    out.material_def_reprs
                        .entry(material_id)
                        .or_default()
                        .extend(reprs);
                }
            }
        }
    }
    for &(id, start, end) in &spans.rel_associates_material {
        if let Ok(entity) = decoder.decode_at_with_id(id, start, end) {
            // RelatingMaterial (attr 5) ← RelatedObjects (attr 4).
            if let Some(material_select_id) = entity.get_ref(5) {
                if let Some(related) = refs_from_list(&entity, 4) {
                    for element_id in related {
                        out.element_to_material.insert(element_id, material_select_id);
                    }
                }
            }
        }
    }

    crate::prepass_type_material::propagate_type_material(&spans.defines_by_type, decoder, &mut out.element_to_material);
    // ── Voids + fills + aggregate propagation (#845) ──
    for &(id, start, end) in &spans.void_rels {
        if let Ok(entity) = decoder.decode_at_with_id(id, start, end) {
            if let (Some(host), Some(opening)) = (entity.get_ref(4), entity.get_ref(5)) {
                out.void_index.entry(host).or_default().push(opening);
            }
        }
    }
    for &(id, start, end) in &spans.fills_rels {
        if let Ok(entity) = decoder.decode_at_with_id(id, start, end) {
            // attr 4 = RelatingOpeningElement, attr 5 = RelatedBuildingElement.
            if let (Some(opening_id), Some(filling_id)) = (entity.get_ref(4), entity.get_ref(5)) {
                out.filling_by_opening.insert(opening_id, filling_id);
            }
        }
    }
    if !out.void_index.is_empty() && !spans.aggregate_rels.is_empty() {
        let mut aggregate_children: FxHashMap<u32, Vec<u32>> = FxHashMap::default();
        for &(id, start, end) in &spans.aggregate_rels {
            if let Ok(entity) = decoder.decode_at_with_id(id, start, end) {
                let Some(parent_id) = entity.get_ref(4) else {
                    continue;
                };
                if let Some(children) = refs_from_list(&entity, 5) {
                    aggregate_children
                        .entry(parent_id)
                        .or_default()
                        .extend(children);
                }
            }
        }
        ifc_lite_geometry::propagate_voids_via_aggregates(
            &mut out.void_index,
            &aggregate_children,
        );
    }

    // Canonicalise each host's opening order (#2019). The scan pushes in
    // statement order, aggregate propagation in hashmap-BFS order; neither
    // is a property of the model. Sequential void cuts are not associative
    // (each pass snaps f64->f32), so reordering them moves the world
    // geometry hash on a re-export that only shuffled statements.
    for openings in out.void_index.values_mut() {
        openings.sort_unstable();
    }

    // ── Material chain join (#407): element id → colour list ──
    out.element_material_colors = crate::style::build_element_material_colors(
        &out.material_def_reprs,
        &out.orphan_styled_items,
        &out.element_to_material,
        decoder,
    );

    out
}

/// Resolve geometry-attached styled-item spans into a style index — the
/// defer-mode replay (`fast_first_batch`), and the building block
/// [`resolve_prepass`] uses internally.
pub fn resolve_styled_item_spans(
    spans: &[(usize, usize)],
    decoder: &mut EntityDecoder,
) -> FxHashMap<u32, GeometryStyleInfo> {
    let mut styles: FxHashMap<u32, GeometryStyleInfo> = FxHashMap::default();
    for &(start, end) in spans {
        if let Ok(styled_item) = decoder.decode_at(start, end) {
            if styled_item.get_ref(0).is_some() {
                collect_geometry_style_info(&mut styles, &styled_item, decoder);
            }
        }
    }
    styles
}

/// Fold `IfcIndexedColourMap` dominant colours into the style index, keyed by
/// target geometry id. `or_insert` preserves IFCSTYLEDITEM precedence: a
/// geometry that already has a direct style keeps it; the indexed colour only
/// fills the gaps (#913).
pub fn merge_indexed_colours(
    geometry_styles: &mut FxHashMap<u32, GeometryStyleInfo>,
    indexed_colours: &FxHashMap<u32, [f32; 4]>,
) {
    for (&geometry_id, &color) in indexed_colours {
        geometry_styles
            .entry(geometry_id)
            .or_insert_with(|| GeometryStyleInfo::from_color(color));
    }
}

/// The file's unit scales, resolved exactly once per parse.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct UnitScales {
    /// Length unit → metres (1.0 for metre files, 0.001 for millimetre files).
    pub length_unit_scale: f64,
    /// Plane-angle unit → radians (1.0 for RADIAN files, π/180 for DEGREE).
    pub plane_angle_to_radians: f64,
    /// The `IFCPROJECT` express id the scales were resolved from, when found.
    pub project_id: Option<u32>,
}

impl Default for UnitScales {
    fn default() -> Self {
        Self {
            length_unit_scale: 1.0,
            plane_angle_to_radians: 1.0,
            project_id: None,
        }
    }
}

/// Resolve BOTH unit scales once, against the decoder's (possibly partial)
/// entity index, with the documented fallback ladder:
///
/// 1. `project_id` hint (recorded by the scan) — O(1) decode via the index.
/// 2. No hint? Find `IFCPROJECT` by SIMD substring search (it is a singleton
///    and many exporters — IfcOpenShell, Revit — emit it near the END of the
///    file, after the scan's early-meta point).
/// 3. Resolution chain incomplete on a PARTIAL index (streaming early-meta:
///    the IFCSIUNIT chain may sit past the scan point)? Re-resolve against a
///    freshly built FULL index rather than silently defaulting — a millimetre
///    model resolved as metres renders 1000× oversized.
///
/// This is the only sanctioned place that hunts for `IFCPROJECT`; per-element
/// decoders are seeded from the result (`EntityDecoder::seed_unit_scales`) so
/// the historic O(file)-scan-per-decoder stall class stays dead.
pub fn resolve_unit_scales(
    content: &[u8],
    project_id_hint: Option<u32>,
    decoder: &mut EntityDecoder,
) -> UnitScales {
    let project_id = project_id_hint.or_else(|| find_ifcproject_id(content));
    let Some(pid) = project_id else {
        return UnitScales::default();
    };

    // Fast path: resolve on the caller's decoder/index. BOTH resolvers return
    // `None` (not a masked default) when their chain is incomplete on a partial
    // index, so an unresolved either-scale forces the full-index retry below
    // rather than silently shipping radians/metres (issue #1367).
    let length = ifc_lite_core::try_extract_length_unit_scale(decoder, pid);
    let angle = ifc_lite_core::try_extract_plane_angle_to_radians(decoder, pid);

    if let (Some(length_unit_scale), Some(plane_angle_to_radians)) = (length, angle) {
        return UnitScales {
            length_unit_scale,
            plane_angle_to_radians,
            project_id,
        };
    }

    // Chain incomplete (partial index) — resolve against a full index.
    let full_index = ifc_lite_core::build_entity_index(content);
    let mut full_decoder = EntityDecoder::with_index(content, full_index);
    UnitScales {
        length_unit_scale: length.or_else(|| {
            ifc_lite_core::extract_length_unit_scale(&mut full_decoder, pid).ok()
        })
        .unwrap_or(1.0),
        plane_angle_to_radians: angle
            .or_else(|| {
                ifc_lite_core::extract_plane_angle_to_radians(&mut full_decoder, pid).ok()
            })
            .unwrap_or(1.0),
        project_id,
    }
}

/// Find the singleton `IFCPROJECT`'s express id by SIMD substring search —
/// no full entity scan. Returns `None` when the file has no project.
///
/// A refused id (issue #3421: an `IFCPROJECT` express id above `u32::MAX`) is
/// reported through [`ifc_lite_core::parser::report_oversized_ids`] — the
/// same sink the definition scanner uses (issue #3395/#3752) — because it is
/// exactly that class of event: this function backtracks from `IFCPROJECT(`
/// to the record's OWN id, not to a reference into another entity, so a
/// refusal here is indistinguishable in kind from a scan refusing to index
/// the record at all. Left unreported, it would default the file's unit
/// scales (see [`resolve_unit_scales`]) with the exact silent-1000×-oversized
/// symptom issue #1367 already fixed for the "not found at all" case.
pub fn find_ifcproject_id(content: &[u8]) -> Option<u32> {
    let mut refused = 0usize;
    let result = find_ifcproject_id_inner(content, &mut refused);
    ifc_lite_core::parser::report_oversized_ids(refused);
    result
}

/// Case-insensitive search for the literal keyword `IFCPROJECT(` at or after
/// `from` (issue #4497: STEP keyword case is not significant, so a lowercase
/// or CamelCase exporter's `ifcproject(`/`IfcProject(` must resolve exactly
/// like the uppercase form). [`find_keyword`] anchors on `J`, which occurs in
/// almost nothing else; the measurement that chose it over the lead `I` is
/// recorded on that function's module. The `from` cut matters because the
/// caller resumes at `previous_hit + 1`, so a hit behind it would be
/// returned forever.
fn find_ifcproject_keyword(content: &[u8], from: usize) -> Option<usize> {
    find_keyword(content.get(from..)?, b"IFCPROJECT(").map(|rel| from + rel)
}

fn find_ifcproject_id_inner(content: &[u8], refused: &mut usize) -> Option<u32> {
    let mut from = 0usize;
    // Search for the keyword+paren only; the `=` and `#<id>` are reconstructed by
    // backtracking. Exporters vary the whitespace around `=` — Revit/EDM emits
    // `#1593796= IFCPROJECT(` with a SPACE, so the old `=IFCPROJECT(` literal
    // never matched and the whole unit chain silently defaulted (length → metres
    // on a mm model, plane-angle → radians on a degree model, making arched
    // openings render as full circles — issue #1367). `IFCPROJECT(` cannot
    // collide with `IFCPROJECTEDCRS(` because the `(` must immediately follow.
    while let Some(kw) = find_ifcproject_keyword(content, from) {
        // Backtrack over optional whitespace, then require '='.
        let mut i = kw;
        while i > 0 && content[i - 1].is_ascii_whitespace() {
            i -= 1;
        }
        if i > 0 && content[i - 1] == b'=' {
            i -= 1; // step over '='
            // Optional whitespace between the express id and '='.
            while i > 0 && content[i - 1].is_ascii_whitespace() {
                i -= 1;
            }
            // Backtrack over the express id digits to the '#'.
            let digits_end = i;
            while i > 0 && content[i - 1].is_ascii_digit() {
                i -= 1;
            }
            if i > 0 && content[i - 1] == b'#' && i < digits_end && starts_a_record(content, i - 1)
            {
                // Refuse (not wrap) above u32::MAX (#3421); None here just
                // keeps searching, same as the "not found" case below.
                // Counted (issue #3752) so the caller can report it via the
                // scanner's own oversized-id sink instead of it vanishing.
                match parse_express_id(&content[i..digits_end]) {
                    Some(id) => return Some(id),
                    None => *refused += 1,
                }
            }
        }
        // `IFCPROJECT(` not preceded by a record-starting `#<digits>=` (e.g.
        // the whole thing quoted inside a string) — keep searching.
        from = kw + 1;
    }
    None
}

/// Does the `#` at `hash` begin a record, rather than sit inside a quoted
/// string or a comment?
///
/// 10303-21 terminates every entity instance with `;`, so a declaration's
/// `#` is preceded — across trivia only — by that `;` or by the start of
/// input. Without this check a description or comment containing a
/// record-shaped decoy such as `'note: #9=ifcproject( …'` is accepted, and
/// the scan returns a WRONG express id AND stops, so the real project is
/// never reached: `extract_length_unit_scale` then rejects that id on its
/// `IFCPROJECT` type guard and the caller's `unwrap_or(1.0)` restores the
/// 1000×-oversized millimetre default issue #4497 exists to remove. The
/// hazard predates case-insensitive matching, which only widens it from
/// uppercase decoys to ordinary lowercase prose.
///
/// Validating instead that the id decodes to an `IFCPROJECT` would be
/// stricter, but it needs an entity index per candidate — the
/// O(file)-scan-per-decoder cost [`resolve_unit_scales`] exists to keep
/// dead. This stays a single linear byte scan.
///
/// "Trivia", not whitespace: a `/* … */` comment is legal wherever
/// whitespace is, so `#1=IFCWALL(…); /* note */ #7=IFCPROJECT(…)` is a real
/// declaration and must not be refused (the entity scanner's `skip_step_trivia`
/// makes the same allowance in the forward direction).
fn starts_a_record(content: &[u8], hash: usize) -> bool {
    let mut i = hash;
    loop {
        while i > 0 && content[i - 1].is_ascii_whitespace() {
            i -= 1;
        }
        // A closing `*/` here means a comment sits between the boundary and
        // the `#`; skip back over it and re-test. An unopened `*/` is not
        // trivia, so refuse rather than loop.
        if i >= 2 && content[i - 1] == b'/' && content[i - 2] == b'*' {
            match memchr::memmem::rfind(&content[..i - 2], b"/*") {
                Some(open) => i = open,
                None => return false,
            }
            continue;
        }
        return i == 0 || content[i - 1] == b';';
    }
}

/// Flat wire encodings of the resolved styles for the browser's
/// `styleIds`/`styleColors` arrays: the rich style index flattened to
/// `(ids, rgba8)`, with IfcIndexedColourMap dominants, flat material colours,
/// and per-element first material colours filling the gaps — the exact
/// layered precedence the browser prepasses have always shipped.
pub fn flat_styles_rgba8(resolved: &ResolvedPrepass, decoder: &mut EntityDecoder) -> (Vec<u32>, Vec<u8>) {
    let mut merged: FxHashMap<u32, [f32; 4]> = resolved
        .geometry_style_index
        .iter()
        .map(|(&id, info)| (id, info.color))
        .collect();
    for (&geometry_id, &color) in &resolved.indexed_colour_index {
        merged.entry(geometry_id).or_insert(color);
    }
    // Flat material_id → colour, then element id → first material colour, so
    // `processGeometryBatch`'s per-element fallback picks them up.
    let material_styles = crate::style::build_material_style_index(
        &resolved.material_def_reprs,
        &resolved.orphan_styled_items,
        decoder,
    );
    for (&mat_id, &color) in crate::style::flatten_material_color_index(&material_styles).iter() {
        merged.entry(mat_id).or_insert(color);
    }
    for (&element_id, colors) in &resolved.element_material_colors {
        if let Some(&color) = colors.first() {
            merged.entry(element_id).or_insert(color);
        }
    }

    // Emit id-ascending: hashmap iteration order is an implementation detail,
    // and these arrays are wire output. Consumers rebuild a map (see the sort
    // rationale on `flat_voids`), so the order is free to pin.
    let mut entries: Vec<(u32, [f32; 4])> = merged.into_iter().collect();
    entries.sort_unstable_by_key(|&(id, _)| id);
    let mut ids: Vec<u32> = Vec::with_capacity(entries.len());
    let mut rgba: Vec<u8> = Vec::with_capacity(entries.len() * 4);
    for (id, color) in entries {
        ids.push(id);
        rgba.extend_from_slice(&crate::style::Rgba::from_array(color).to_rgba8());
    }
    (ids, rgba)
}

/// Flat wire encoding of the void index: `(keys, counts, values)` in the
/// shape `processGeometryBatch` accepts.
///
/// Emitted sorted by host id (u32 ascending). FxHashMap iteration order is
/// seed-free and therefore stable today, but it is an implicit
/// insertion+hash-order artifact; the sort makes the wire byte order an
/// explicit contract (pinned by the mesh-output determinism manifest,
/// `docs/architecture/mesh-determinism.md`). Consumers rebuild a map from the
/// flat arrays (`processGeometryBatch`), so they are order-insensitive.
pub fn flat_voids(void_index: &FxHashMap<u32, Vec<u32>>) -> (Vec<u32>, Vec<u32>, Vec<u32>) {
    let mut hosts: Vec<(&u32, &Vec<u32>)> = void_index.iter().collect();
    hosts.sort_unstable_by_key(|&(&host_id, _)| host_id);
    let mut keys: Vec<u32> = Vec::with_capacity(hosts.len());
    let mut counts: Vec<u32> = Vec::with_capacity(hosts.len());
    let mut values: Vec<u32> = Vec::new();
    for (&host_id, openings) in hosts {
        keys.push(host_id);
        counts.push(openings.len() as u32);
        values.extend(openings.iter().copied());
    }
    (keys, counts, values)
}

/// Flat wire encoding of the element material colour lists (#407/#913 §2.3):
/// `(element_ids, counts, rgba8)` — `counts[i]` colours belong to
/// `element_ids[i]`, in order, 4 bytes each.
///
/// Emitted sorted by element id (u32 ascending) - same explicit-order wire
/// contract as [`flat_voids`]; the per-element colour list order (file order)
/// is unchanged. The inverse [`material_colors_from_flat`] rebuilds a map, so
/// consumers are order-insensitive.
pub fn flat_material_colors(
    element_material_colors: &FxHashMap<u32, Vec<[f32; 4]>>,
) -> (Vec<u32>, Vec<u32>, Vec<u8>) {
    let mut elements: Vec<(&u32, &Vec<[f32; 4]>)> = element_material_colors.iter().collect();
    elements.sort_unstable_by_key(|&(&element_id, _)| element_id);
    let mut ids: Vec<u32> = Vec::with_capacity(elements.len());
    let mut counts: Vec<u32> = Vec::with_capacity(elements.len());
    let mut rgba: Vec<u8> = Vec::new();
    for (&element_id, colors) in elements {
        if colors.is_empty() {
            continue;
        }
        ids.push(element_id);
        counts.push(colors.len() as u32);
        for &c in colors {
            rgba.extend_from_slice(&crate::style::Rgba::from_array(c).to_rgba8());
        }
    }
    (ids, counts, rgba)
}

/// Decode the flat material-colour wire arrays back into the canonical map —
/// the inverse of [`flat_material_colors`], used by `processGeometryBatch`.
pub fn material_colors_from_flat(
    element_ids: &[u32],
    counts: &[u32],
    rgba: &[u8],
) -> FxHashMap<u32, Vec<[f32; 4]>> {
    let mut out: FxHashMap<u32, Vec<[f32; 4]>> = FxHashMap::default();
    let mut offset = 0usize;
    for (i, &element_id) in element_ids.iter().enumerate() {
        let Some(&count) = counts.get(i) else { break };
        let count = count as usize;
        let mut colors: Vec<[f32; 4]> = Vec::with_capacity(count);
        for c in 0..count {
            let base = (offset + c) * 4;
            if base + 3 >= rgba.len() {
                break;
            }
            colors.push(
                crate::style::Rgba::from_rgba8([
                    rgba[base],
                    rgba[base + 1],
                    rgba[base + 2],
                    rgba[base + 3],
                ])
                .to_array(),
            );
        }
        offset += count;
        if !colors.is_empty() {
            out.insert(element_id, colors);
        }
    }
    out
}

// ── Styled-item resolution chain (moved from processor.rs — shared) ──

/// Resolve a geometry-attached `IfcStyledItem` into the style index with
/// first-wins precedence per geometry id (file order = authored intent).
pub(crate) fn collect_geometry_style_info(
    geometry_styles: &mut FxHashMap<u32, GeometryStyleInfo>,
    styled_item: &DecodedEntity,
    decoder: &mut EntityDecoder,
) {
    let Some(geometry_id) = styled_item.get_ref(0) else {
        return;
    };
    if geometry_styles.contains_key(&geometry_id) {
        return;
    }
    if let Some(style_info) = extract_style_info_from_styled_item(styled_item, decoder) {
        geometry_styles.insert(geometry_id, style_info);
    }
}

/// Extract colour + name from an `IfcStyledItem` by traversing its style
/// references (directly or through `IfcPresentationStyleAssignment`).
pub(crate) fn extract_style_info_from_styled_item(
    styled_item: &DecodedEntity,
    decoder: &mut EntityDecoder,
) -> Option<GeometryStyleInfo> {
    surface_style_from_styled_item(styled_item, decoder).map(|(_, info)| info)
        .or_else(|| crate::style::fill::fill_style_from_styled_item(styled_item, decoder))
}

/// Canonical first valid rendering style, also used when authoring clones its
/// non-albedo properties instead of discarding them (#4260).
pub(crate) fn surface_style_from_styled_item(
    styled_item: &DecodedEntity,
    decoder: &mut EntityDecoder,
) -> Option<(u32, GeometryStyleInfo)> {
    for style_id in refs_from_list(styled_item, 1)? {
        if let Ok(style) = decoder.decode_by_id(style_id) {
            if let Some(inner_refs) = refs_from_list(&style, 0) {
                for inner_id in inner_refs {
                    if let Some(info) = extract_surface_style_info(inner_id, decoder) { return Some((inner_id, info)); }
                }
            }
            if let Some(info) = extract_surface_style_info(style_id, decoder) { return Some((style_id, info)); }
        }
    }
    None
}

/// Extract colour + style name from an `IfcSurfaceStyle`. Colour resolution is
/// the canonical [`crate::style::extract_surface_style_colors`], shared with
/// the browser pre-pass so the server and viewer can't disagree on
/// `SurfaceColour` vs `DiffuseColour` precedence (#997).
fn extract_surface_style_info(
    style_id: u32,
    decoder: &mut EntityDecoder,
) -> Option<GeometryStyleInfo> {
    let style = decoder.decode_by_id(style_id).ok()?;
    let material_name = normalize_style_name(style.get_string(0));
    let (color, shading_color) = crate::style::extract_surface_style_colors(style_id, decoder)?;
    Some(GeometryStyleInfo {
        color,
        shading_color,
        material_name,
    })
}

fn normalize_style_name(raw: Option<&str>) -> Option<String> {
    let name = raw?.trim();
    if name.is_empty() || name == "$" {
        return None;
    }
    if name.eq_ignore_ascii_case("<unnamed>") || name.eq_ignore_ascii_case("unnamed") {
        return None;
    }
    Some(name.to_string())
}

/// Extract entity references from a list attribute.
pub(crate) fn refs_from_list(entity: &DecodedEntity, index: usize) -> Option<Vec<u32>> {
    let list = entity.get_list(index)?;
    let refs: Vec<u32> = list.iter().filter_map(|v| v.as_entity_ref()).collect();
    if refs.is_empty() {
        None
    } else {
        Some(refs)
    }
}

#[cfg(test)]
#[path = "prepass_tests.rs"]
mod tests;