@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/plugins/beamng-vehicle/bin/convert-beamng.py

@@ -0,0 +1,1563 @@
+#!/usr/bin/env python3
+"""Blender-side BeamNG DAE to canonical HELIX GLB conversion.
+
+The converter never fabricates cabin or wheel meshes. It measures authored source
+geometry, restores source material maps, emits canonical sockets, and leaves final
+acceptance to vehicle-qa.mjs.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+# Blender runs `--python <script>` without the script's directory on sys.path (4.0 and 4.5 on
+# Linux), so sibling modules must be made importable explicitly before they are imported.
+_SCRIPT_DIR = str(Path(__file__).resolve().parent)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import bpy
+import numpy as np
+from mathutils import Matrix, Vector
+from beamng_materials import TextureChain, parse_material_tree
+from beamng_jbeam import (
+    JBeamDocumentCache,
+    MAX_PC_FILE_BYTES,
+    MAX_PC_SOURCES,
+    MAX_PC_TOTAL_BYTES,
+    bounded_asset_paths,
+    build_part_catalog,
+    build_selected_part_index,
+    preselect_configuration,
+    resolve_part_closure,
+    selected_part_summary,
+    write_bound_selected_part_index,
+)
+
+
+INTERIOR = re.compile(r"seat|dash|interior|cabin|console|steer|gauge|door.?(?:card|panel)|pedal", re.I)
+# `trim`, `wheelwell`, and `steeringwheel` are common vehicle mesh names but are
+# not road-wheel custody. Keep this predicate exact because it controls both
+# configuration retention and destructive wheel-source normalization.
+WHEEL = re.compile(r"tyre|tire|(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim", re.I)
+TYRE = re.compile(r"tyre|tire", re.I)
+BRAKE_HARDWARE = re.compile(r"brake.?disc|brake.?rotor|brake.?drum|(?:^|_)drum(?:_|$)|"
+                            r"wheel.?hub|(?:^|_)hub(?:_|$)", re.I)
+REAR = re.compile(r"exhaust|muffler|tail.?pipe|taillight|tailgate|trunk|boot|bumper.?r", re.I)
+COLLADA_NS = {"c": "http://www.collada.org/2005/11/COLLADASchema"}
+MATERIAL_SCAN_LIMIT = (4_096, 256 * 1024 * 1024, 32 * 1024 * 1024)
+TEXTURE_SCAN_LIMIT = (200_000, 128 * 1024 * 1024 * 1024, 2 * 1024 * 1024 * 1024)
+AUDIO_SCAN_LIMIT = (20_000, 16 * 1024 * 1024 * 1024, 1024 * 1024 * 1024)
+
+
+def local_tag(element) -> str:
+    return element.tag.split("}")[-1]
+
+
+def primitive_inputs(element) -> list[dict]:
+    return [{"semantic": row.get("semantic"), "source": row.get("source", "").lstrip("#"),
+             "offset": int(row.get("offset", "0")), "set": int(row.get("set") or 0)}
+            for row in element.findall("c:input", COLLADA_NS) if row.get("source")]
+
+
+def fan_triangulate(rows: np.ndarray, counts: np.ndarray) -> np.ndarray:
+    output = []
+    cursor = 0
+    for count in counts:
+        face = rows[cursor:cursor + int(count)]
+        cursor += int(count)
+        for index in range(1, len(face) - 1):
+            output.extend((face[0], face[index], face[index + 1]))
+    return np.asarray(output, dtype=np.int64)
+
+
+def read_geometry(element) -> tuple[str, dict] | None:
+    mesh = element.find("c:mesh", COLLADA_NS)
+    if mesh is None:
+        return None
+    sources = {}
+    for source in mesh.findall("c:source", COLLADA_NS):
+        values = source.find("c:float_array", COLLADA_NS)
+        accessor = source.find("c:technique_common/c:accessor", COLLADA_NS)
+        if values is None:
+            continue
+        stride = int(accessor.get("stride", "1")) if accessor is not None else 1
+        numbers = np.fromstring(values.text or "", dtype=np.float64, sep=" ")
+        numbers = numbers[:numbers.size - numbers.size % stride] if stride else numbers
+        sources[source.get("id")] = numbers.reshape(-1, stride)
+    vertices = {}
+    for vertex in mesh.findall("c:vertices", COLLADA_NS):
+        position = vertex.find('c:input[@semantic="POSITION"]', COLLADA_NS)
+        if position is not None:
+            vertices[vertex.get("id")] = position.get("source", "").lstrip("#")
+    primitives = []
+    for primitive in list(mesh.findall("c:triangles", COLLADA_NS)) + list(mesh.findall("c:polylist", COLLADA_NS)):
+        inputs = primitive_inputs(primitive)
+        payload = primitive.find("c:p", COLLADA_NS)
+        if not inputs or payload is None:
+            continue
+        stride = max(row["offset"] for row in inputs) + 1
+        values = np.fromstring(payload.text or "", dtype=np.int64, sep=" ")
+        values = values[:values.size - values.size % stride].reshape(-1, stride)
+        if local_tag(primitive) == "polylist":
+            counts_element = primitive.find("c:vcount", COLLADA_NS)
+            counts = np.fromstring(counts_element.text or "", dtype=np.int64, sep=" ") if counts_element is not None else np.zeros(0)
+            values = fan_triangulate(values, counts)
+        else:
+            values = values[:len(values) - len(values) % 3]
+        if len(values):
+            primitives.append({"material": primitive.get("material") or "default", "inputs": inputs, "indices": values})
+    identifier = element.get("id")
+    return (identifier, {"name": element.get("name") or identifier, "sources": sources,
+                         "vertices": vertices, "primitives": primitives}) if identifier else None
+
+
+def read_scene(element) -> list[dict]:
+    nodes = []
+
+    def visit(parent, parent_matrix):
+        for node in parent.findall("c:node", COLLADA_NS):
+            local = np.eye(4)
+            for child in node:
+                if local_tag(child) == "matrix" and (child.text or "").strip():
+                    local = local @ np.fromstring(child.text, dtype=np.float64, sep=" ").reshape(4, 4)
+            world = parent_matrix @ local
+            instance = node.find("c:instance_geometry", COLLADA_NS)
+            bindings = {}
+            if instance is not None:
+                for binding in instance.findall(".//c:instance_material", COLLADA_NS):
+                    bindings[binding.get("symbol")] = binding.get("target", "").lstrip("#")
+            nodes.append({"name": node.get("name") or node.get("id") or "mesh",
+                          "geometry": instance.get("url", "").lstrip("#") if instance is not None else None,
+                          "matrix": world, "materials": bindings})
+            visit(node, world)
+    for scene in element.findall("c:visual_scene", COLLADA_NS):
+        visit(scene, np.eye(4))
+    return nodes
+
+
+def parse_collada(path: Path) -> dict:
+    geometries, materials, nodes = {}, {}, []
+    up_axis, metre = "Z_UP", 1.0
+    for _, element in ET.iterparse(path, events=("end",)):
+        tag = local_tag(element)
+        if tag == "asset":
+            up = element.find("c:up_axis", COLLADA_NS)
+            unit = element.find("c:unit", COLLADA_NS)
+            up_axis = (up.text or "Z_UP").strip() if up is not None else "Z_UP"
+            metre = float(unit.get("meter", "1")) if unit is not None else 1.0
+            element.clear()
+        elif tag == "library_materials":
+            for material in element.findall("c:material", COLLADA_NS):
+                materials[material.get("id")] = material.get("name") or material.get("id") or "default"
+            element.clear()
+        elif tag == "geometry":
+            result = read_geometry(element)
+            if result:
+                geometries[result[0]] = result[1]
+            element.clear()
+        elif tag == "library_visual_scenes":
+            nodes.extend(read_scene(element))
+            element.clear()
+    return {"geometries": geometries, "materials": materials, "nodes": nodes,
+            "upAxis": up_axis, "metre": metre}
+
+
+def build_collada(path: Path) -> list[bpy.types.Object]:
+    document = parse_collada(path)
+    built = []
+    path_parts = [part.lower() for part in path.parts]
+    wheel_axle = "front" if "wheels" in path_parts and "f" in path_parts else \
+        "rear" if "wheels" in path_parts and "r" in path_parts else None
+    for node in document["nodes"]:
+        geometry = document["geometries"].get(node["geometry"])
+        if not geometry or not geometry["primitives"]:
+            continue
+        position_source = None
+        for primitive in geometry["primitives"]:
+            vertex = next((row for row in primitive["inputs"] if row["semantic"] == "VERTEX"), None)
+            if vertex:
+                position_source = geometry["vertices"].get(vertex["source"], vertex["source"])
+                break
+        positions = geometry["sources"].get(position_source)
+        if positions is None or len(positions) == 0:
+            continue
+        faces, face_materials, loop_uvs, slots = [], [], [], []
+        for primitive in geometry["primitives"]:
+            input_by_semantic = {}
+            for row in primitive["inputs"]:
+                if row["semantic"] != "TEXCOORD" or row["semantic"] not in input_by_semantic or row["set"] == 0:
+                    input_by_semantic[row["semantic"]] = row
+            vertex = input_by_semantic.get("VERTEX")
+            if not vertex:
+                continue
+            material_id = node["materials"].get(primitive["material"], primitive["material"])
+            material_name = document["materials"].get(material_id, material_id or "default")
+            if material_name not in slots:
+                slots.append(material_name)
+            material_index = slots.index(material_name)
+            texcoord = input_by_semantic.get("TEXCOORD")
+            tex_values = geometry["sources"].get(texcoord["source"]) if texcoord else None
+            rows = primitive["indices"]
+            for start in range(0, len(rows), 3):
+                triangle = rows[start:start + 3]
+                if len(triangle) < 3:
+                    continue
+                faces.append(tuple(int(row[vertex["offset"]]) for row in triangle))
+                face_materials.append(material_index)
+                loop_uvs.extend(tuple(tex_values[int(row[texcoord["offset"]])][:2]) if tex_values is not None else (0.0, 0.0)
+                                for row in triangle)
+        if not faces:
+            continue
+        object_name = f"{node['name']}_{wheel_axle}" if wheel_axle and WHEEL.search(node["name"]) else node["name"]
+        mesh = bpy.data.meshes.new(object_name)
+        mesh.from_pydata([tuple(row[:3] * document["metre"]) for row in positions], [], faces)
+        mesh.update()
+        obj = bpy.data.objects.new(object_name, mesh)
+        bpy.context.scene.collection.objects.link(obj)
+        obj["helix_source_dae"] = str(path)
+        obj["helix_dedicated_wheel"] = bool(wheel_axle)
+        for name in slots:
+            material = bpy.data.materials.get(name) or bpy.data.materials.new(name)
+            mesh.materials.append(material)
+        for polygon, index in zip(mesh.polygons, face_materials):
+            polygon.material_index = index
+        uv_layer = mesh.uv_layers.new(name="UVMap")
+        for index, value in enumerate(loop_uvs[:len(uv_layer.data)]):
+            uv_layer.data[index].uv = value
+        obj.matrix_world = Matrix(node["matrix"].tolist())
+        if document["upAxis"] == "Y_UP":
+            obj.matrix_world = Matrix.Rotation(math.radians(90), 4, "X") @ obj.matrix_world
+        built.append(obj)
+    return built
+
+
+def config_overrides(path: Path, cache: JBeamDocumentCache) -> dict:
+    try:
+        document = cache.load(path)
+        return document.get("parts", {}) if isinstance(document, dict) and isinstance(document.get("parts"), dict) else {}
+    except Exception:
+        return {}
+
+
+def choose_config(root: Path, daes: list[str], parts: dict[str, dict],
+                  cache: JBeamDocumentCache,
+                  configuration_hint: str | None = None,
+                  present_meshes: set[str] | None = None) -> Path | None:
+    variants = [root.name.lower(), *(Path(value).parent.name.lower() for value in daes)]
+    configs = bounded_asset_paths(
+        [root], {".pc": (MAX_PC_SOURCES, MAX_PC_TOTAL_BYTES, MAX_PC_FILE_BYTES)},
+        recursive=False)
+    preselected = preselect_configuration(root, variants, configuration_hint)
+    if preselected is not None:
+        return preselected
+    if not configs:
+        return None
+
+    def score(path: Path) -> tuple:
+        overrides = config_overrides(path, cache)
+        chosen = resolve_part_closure(parts, overrides)["parts"]
+        meshes = {mesh for part in chosen for mesh in part["meshes"] if isinstance(mesh, str)}
+        semantic = " ".join([path.stem, *overrides.keys(), *map(str, overrides.values()),
+                             *(part["name"] for part in chosen), *meshes]).lower()
+        present = meshes & present_meshes if present_meshes is not None else meshes
+        present_semantic = " ".join(present).lower()
+        present_coverage = sum(bool(re.search(pattern, present_semantic)) for pattern in (
+            r"body|shell|frame|chassis", r"seat|interior|cabin", r"steer", r"wheel|rim|tire|tyre",
+            r"engine|motor", r"suspension|hub", r"door", r"glass|windshield|windscreen"))
+        coverage = sum(bool(re.search(pattern, semantic)) for pattern in (
+            r"body|shell|frame|chassis", r"seat|interior|cabin", r"steer", r"wheel|rim|tire|tyre",
+            r"engine|motor", r"suspension|hub", r"door", r"glass|windshield|windscreen"))
+        stem = re.sub(r"[^a-z0-9]", "", path.stem.lower())
+        candidate = re.sub(r"[^a-z0-9]", "", root.name.lower())
+        canonical = int(stem == candidate)
+        configured = " ".join(str(value) for value in overrides.values() if isinstance(value, str)).lower()
+        active_seats = {value for value in overrides.values()
+                        if isinstance(value, str) and value != "none" and re.search(r"(?:^|_)seat(?:s)?(?:_|$)", value, re.I)}
+        front_sides = sum(bool(re.search(pattern, configured)) for pattern in (
+            r"seat[^ ]*(?:_fl|_l(?:_|$)|driver)", r"seat[^ ]*(?:_fr|_r(?:_|$)|passenger)"))
+        rear_seats = int(bool(re.search(r"seat(?:s)?[^ ]*(?:_r(?:_|$)|rear)", configured)))
+        visual_steering = int(any(isinstance(value, str) and value != "none"
+                                  and re.search(r"(?:^|_)steer(?:_|$)", value, re.I)
+                                  for value in overrides.values()))
+        # A complete road cabin outranks optional mesh volume. This rejects a
+        # one-seat hillclimb shell in favour of the authored two/four-seat trim
+        # while leaving requested compatibility-profile configurations intact.
+        cabin = min(len(active_seats), 4) + front_sides + rear_seats + visual_steering * 2
+        stock = int(bool(re.search(r"(?:^|_)(?:base|stock|factory|default|vanilla)(?:_|$)", path.stem, re.I)))
+        info_path = root / f"info_{path.stem}.json"
+        if info_path.is_file():
+            try:
+                info = cache.load(info_path)
+                description = f"{info.get('Configuration', '')} {info.get('Description', '')}".lower()
+                stock += int(bool(re.search(r"base model|stock|factory|standard model|entry.?level", description))) * 2
+            except Exception:
+                pass
+        stock += int(bool(re.fullmatch(r"sa_1000", path.stem, re.I))) * 2
+        modified = int(bool(re.search(r"race|drift|drag|hillclimb|maxspeed|stanced|stripped|offroad|jato|godmode|"
+                                      r"derby|custom|tuned|owner|experience|camo|colour|special|rhd|police|pursuit",
+                                      path.stem, re.I)))
+        if modified:
+            stock = 0
+        # Completeness comes first. Among complete configurations, canonical or
+        # explicitly stock/base spawns win before raw optional-part volume.
+        return (present_coverage, coverage, canonical, cabin, stock, -modified,
+                len(present), len(meshes), len(chosen), len(overrides), path.name)
+
+    scored = [(score(path), path) for path in configs]
+    selected = max(scored, key=lambda row: row[0])[1]
+    top = sorted(scored, key=lambda row: row[0], reverse=True)[:5]
+    print(f"[beamng] configuration candidates top={[(path.name, values[:-1]) for values, path in top]}")
+    return selected
+
+
+def configured_meshes(root: Path, source_root: Path, daes: list[str],
+                      configuration_hint: str | None = None,
+                      present_meshes: set[str] | None = None,
+                      dependency_roots: list[Path] | None = None,
+                      part_index_path: Path | None = None,
+                      bridge_plan_key: str | None = None,
+                      source_sha256: str | None = None,
+                      common_closure_sha256: str | None = None) -> tuple[set[str], dict]:
+    dependency_roots = dependency_roots or []
+    cache = JBeamDocumentCache(source_root, dependency_roots)
+    common = source_root / "vehicles" / "common"
+    dependency_common = [path / "vehicles" / "common" for path in dependency_roots]
+    ranked_roots = [(root, 0), (common, 1), *((source, 2) for source in dependency_common)]
+    admitted = [(source, rank) for source, rank in ranked_roots if source.is_dir()]
+    parts, errors = build_part_catalog(
+        [source for source, _ in admitted], cache, [rank for _, rank in admitted])
+    config = choose_config(root, daes, parts, cache, configuration_hint, present_meshes)
+    overrides = {}
+    config_document = {}
+    if config:
+        try:
+            config_document = cache.load(config)
+            overrides = config_overrides(config, cache)
+        except Exception as error:
+            errors.append(f"{config.name}: {error}")
+    requested_main = config_document.get("mainPartName") if isinstance(config_document, dict) else None
+    graph = resolve_part_closure(parts, overrides, requested_main)
+    chosen = graph["parts"]
+    wanted = {mesh for part in chosen for mesh in part["meshes"] if isinstance(mesh, str)}
+    slot_closure = graph["slotClosure"]
+    semantic = " ".join([*(part["name"] for part in chosen), *wanted]).lower()
+    if len(wanted) < 4 or not re.search(r"body|shell|frame|chassis", semantic):
+        raise RuntimeError(f"configuration {config.name if config else '<default>'} has no complete vehicle shell "
+                           f"({len(wanted)} render meshes; JBeam parse failures={len(errors)})")
+    paint_base = None
+    if config_document:
+        try:
+            paints = config_document.get("paints", [])
+            colors = config_document.get("colors", [])
+            raw_color = paints[0].get("baseColor") if (
+                isinstance(paints, list) and paints and isinstance(paints[0], dict)
+            ) else colors[0] if (
+                isinstance(colors, list) and colors and isinstance(colors[0], list)
+            ) else None
+            if isinstance(raw_color, list) and len(raw_color) >= 3:
+                paint_base = [round(max(0.0, min(1.0, float(value))), 4) for value in raw_color[:3]] + [1.0]
+        except Exception:
+            pass
+    selected_part_index = build_selected_part_index(root.name, config, graph, cache, parts) if config else None
+    selected_summary = None
+    if selected_part_index is not None:
+        if part_index_path is None or bridge_plan_key is None or source_sha256 is None:
+            raise RuntimeError("selected-part index output and Bridge identity are required")
+        selected_part_index["parseFailures"] = errors[:20]
+        selected_part_index["parseCounts"] = {
+            f"{cache.receipt(path)['root']}:{cache.receipt(path)['path']}": count
+            for path, count in sorted(cache.parse_counts.items(), key=lambda row: str(row[0]))
+        }
+        index_receipt = write_bound_selected_part_index(selected_part_index, part_index_path,
+                                                        bridge_plan_key, source_sha256,
+                                                        common_closure_sha256)
+        selected_summary = selected_part_summary(selected_part_index, index_receipt)
+    configuration_receipt = cache.receipt(config) if config else None
+    return wanted, {"file": config.name if config else None,
+                    "path": configuration_receipt["path"] if configuration_receipt else None,
+                    "sha256": configuration_receipt["sha256"] if configuration_receipt else None,
+                    "sizeBytes": configuration_receipt["sizeBytes"] if configuration_receipt else None,
+                    "parts": [part["name"] for part in chosen],
+                    "slotClosure": slot_closure, "selectedMeshes": sorted(wanted),
+                    "meshes": len(wanted), "explicitOverrides": len(overrides),
+                    "selectedPartSummary": selected_summary,
+                    "paintBaseColor": paint_base,
+                    "semanticCoverage": {key: bool(re.search(pattern, semantic)) for key, pattern in {
+                        "body": r"body|shell|frame|chassis", "cabin": r"seat|interior|cabin",
+                        "steering": r"steer", "wheels": r"wheel|rim|tire|tyre", "engine": r"engine|motor"}.items()},
+                    "jbeamParseFailures": errors[:20]}
+
+
+def filter_configuration(objects: list[bpy.types.Object], wanted: set[str],
+                         has_dedicated_wheels: bool,
+                         configuration_hint: str | None = None) -> tuple[list[bpy.types.Object], list[str]]:
+    present = {obj.name for obj in objects}
+    # Wheel geometry is often authored directly in the main DAE and never
+    # repeated as a JBeam flexbody, so an exact config-only filter can delete
+    # every wheel (RX-7). When the selected trim supplies dedicated wheel DAEs
+    # (992 GT3 RS), those are authoritative and the unrelated base wheels must
+    # be excluded. Otherwise retain the main DAE's authored wheel geometry.
+    def configured(obj: bpy.types.Object) -> bool:
+        # Blender may disambiguate equal source names with a numeric suffix.
+        # That must not disconnect a JBeam-selected flexbody from its authored
+        # DAE mesh.
+        return obj.name in wanted or re.sub(r"\.\d+$", "", obj.name) in wanted
+
+    for obj in objects:
+        obj["helix_configured_mesh"] = configured(obj)
+
+    normalized_hint = re.sub(r"[^a-z0-9]", "", (configuration_hint or "").lower())
+
+    def cross_variant_source(obj: bpy.types.Object) -> bool:
+        # Some trims inherit their seats/interior from a sibling body-kit DAE.
+        # Importing that whole sibling stacks two exterior shells, while
+        # dropping it removes the authored H-points. Retain only semantic cabin
+        # meshes when an explicitly requested trim consumes a different
+        # body-kit variant.
+        dae = Path(str(obj.get("helix_source_dae", "")))
+        lowered_parts = [part.lower() for part in dae.parts]
+        if "body kits" not in lowered_parts:
+            return False
+        variant_tail = dae.parts[lowered_parts.index("body kits") + 1:]
+        normalized_variant = re.sub(r"[^a-z0-9]", "", "/".join(variant_tail).lower())
+        return bool(normalized_hint and normalized_hint not in normalized_variant)
+
+    def cross_variant_interior(obj: bpy.types.Object) -> bool:
+        return cross_variant_source(obj) and bool(INTERIOR.search(obj.name))
+
+    def inactive_damage_variant(obj: bpy.types.Object) -> bool:
+        # JBeam flexbody lists can include the replacement mesh used only after
+        # breakage. Exporting it alongside the intact part produces cracked
+        # glass and doubled/deformed panels on a freshly imported vehicle.
+        return bool(re.search(r"(?:^|[_-])(?:dmg|damage|broken|deformed)(?:[_-]|$)", obj.name, re.I))
+
+    configured_wheels = {obj.name for obj in objects if road_wheel_signal(obj) and (
+        not has_dedicated_wheels
+        or TYRE.search(obj.name)
+        # A dedicated axle DAE is an authored source library, not a placed road
+        # wheel. Retain its candidates until axle expansion can choose the
+        # configured trim, instantiate four corners, and prune the rest.
+        or "wheels" in [part.lower() for part in Path(str(obj.get("helix_source_dae", ""))).parts]
+    )}
+    keep = [obj for obj in objects if not inactive_damage_variant(obj) and (cross_variant_interior(obj) or (
+        not cross_variant_source(obj) and (
+            configured(obj) or obj.name in configured_wheels or BRAKE_HARDWARE.search(obj.name)
+        )
+    ))]
+    missing = sorted(wanted - present)
+    for obj in list(objects):
+        if obj not in keep:
+            bpy.data.objects.remove(obj, do_unlink=True)
+    if len(keep) < 5:
+        raise RuntimeError(f"default configuration retained only {len(keep)} authored mesh nodes")
+    return keep, missing
+
+
+def arguments() -> argparse.Namespace:
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source-root", required=True)
+    parser.add_argument("--vehicle-root", required=True)
+    parser.add_argument("--dae", action="append", required=True)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--receipt", required=True)
+    parser.add_argument("--palette", required=True)
+    parser.add_argument("--material-root", action="append", default=[])
+    parser.add_argument("--configuration-hint")
+    parser.add_argument("--part-index", required=True)
+    parser.add_argument("--bridge-plan-key", required=True)
+    parser.add_argument("--source-sha", required=True)
+    parser.add_argument("--common-closure")
+    parser.add_argument("--mirror-z", action="store_true")
+    return parser.parse_args(argv)
+
+
+def parse_materials(root: Path, default_tier: str, vehicle_root: Path | None = None) -> dict:
+    parsed = parse_material_tree(root, default_tier, vehicle_root)
+    rows = parsed["materials"]
+    aliases = parsed["aliases"]
+    block_re = re.compile(r"(?:singleton\s+)?Material\s*\([^)]*\)\s*\{(.*?)\};", re.I | re.S)
+    for path in bounded_asset_paths(
+            [root], {"materials.cs": MATERIAL_SCAN_LIMIT},
+            exact_names={"materials.cs": "materials.cs"}):
+        text = path.read_text(errors="ignore")
+        for block in block_re.findall(text):
+            mapped = re.search(r'mapTo\s*=\s*"([^"]+)"', block, re.I)
+            if not mapped:
+                continue
+
+            def indexed(field: str) -> str | None:
+                values = [(int(index), value) for index, value in re.findall(
+                    rf'{field}\s*\[(\d+)\]\s*=\s*"([^"]+)"', block, re.I)]
+                return max(values, default=(0, None))[1]
+
+            color_match = re.search(r'diffuseColor\s*\[\d+\]\s*=\s*"([\d.\s-]+)"', block, re.I)
+            power_match = re.search(r'specularPower\s*\[\d+\]\s*=\s*"?([\d.]+)', block, re.I)
+            power = float(power_match.group(1)) if power_match else 32.0
+            identity = mapped.group(1).lower()
+            base = indexed("diffuseMap")
+            normal = indexed("normalMap")
+            roughness_map = indexed("roughnessMap")
+            metallic_map = indexed("metallicMap")
+            rows[identity] = {
+                "key": mapped.group(1), "mapTo": mapped.group(1), "stageCount": 0, "stages": [],
+                "maps": {key: value for key, value in {"baseColor": base, "normal": normal,
+                         "roughness": roughness_map, "metallic": metallic_map}.items() if value},
+                "orderedMaps": [], "factors": {},
+                "base": base,
+                "paletteMask": None,
+                "normal": normal,
+                "roughnessMap": roughness_map,
+                "metallicMap": metallic_map,
+                "color": [float(value) for value in color_match.group(1).split()] if color_match else None,
+                "metallic": 0.75 if re.search(r'dynamicCubemap\s*=\s*(?:true|"1")', block, re.I) else 0.0,
+                "roughness": max(0.08, min(0.9, 1.0 - power / 160.0)),
+                "alpha": {"mode": "BLEND" if re.search(r'translucent\s*=\s*(?:true|"1")', block, re.I) else "OPAQUE",
+                          "source": "materials.cs"},
+                "provenance": {"declarationTier": default_tier,
+                               "declarationFile": str(path.relative_to(root)).replace(os.sep, "/"),
+                               "declarationKey": mapped.group(1), "mapTo": mapped.group(1)},
+            }
+            aliases[identity] = identity
+    return {"materials": rows, "aliases": aliases, "diagnostics": parsed["diagnostics"]}
+
+
+def texture_index(root: Path) -> dict[str, list[Path]]:
+    result: dict[str, list[Path]] = {}
+    extensions = {extension: TEXTURE_SCAN_LIMIT for extension in
+                  (".dds", ".png", ".jpg", ".jpeg", ".tga", ".bmp")}
+    for path in bounded_asset_paths([root], extensions):
+        result.setdefault(path.name.lower(), []).append(path)
+    return result
+
+
+def material_row(definitions: dict[str, tuple[dict, Path]], name: str) -> tuple[dict, Path] | None:
+    key = name.lower()
+    candidates = [key, key.removeprefix("m_"), re.sub(r"\.\d{3}$", "", key)]
+    return next((definitions[value] for value in candidates if value in definitions), None)
+
+
+def connect_image(nodes, links, shader, socket: str, path: Path, non_color: bool = False,
+                  link_alpha: bool = False) -> bool:
+    try:
+        image = bpy.data.images.load(str(path), check_existing=True)
+    except Exception as error:
+        print(f"[beamng] texture refused {path}: {error}")
+        return False
+    if non_color:
+        image.colorspace_settings.name = "Non-Color"
+    texture = nodes.new("ShaderNodeTexImage")
+    texture.image = image
+    if socket == "Normal":
+        normal = nodes.new("ShaderNodeNormalMap")
+        links.new(texture.outputs["Color"], normal.inputs["Color"])
+        links.new(normal.outputs["Normal"], shader.inputs["Normal"])
+    else:
+        links.new(texture.outputs["Color"], shader.inputs[socket])
+        # BeamNG commonly stores masks/palette data in the alpha channel of an
+        # otherwise opaque surface. Treating every image alpha as transparency
+        # made paint, dashboards and upholstery ghost through the car in HELIX.
+        # Only real glazing is allowed to drive the Principled alpha socket.
+        if link_alpha and "Alpha" in texture.outputs and "Alpha" in shader.inputs:
+            links.new(texture.outputs["Alpha"], shader.inputs["Alpha"])
+    return True
+
+
+VEHICLE_MATERIAL_ROLES = (
+    ("tyre", re.compile(r"tyre|tire|tread", re.I), "tire-rubber", (0.012, 0.012, 0.014, 1.0)),
+    ("glass", re.compile(r"glass|window|windscreen|windshield", re.I), "vehicle-glass", (0.025, 0.035, 0.045, 1.0)),
+    ("brake-caliper", re.compile(r"caliper", re.I), "brake-caliper-painted", (0.55, 0.025, 0.015, 1.0)),
+    ("brake-rotor", re.compile(r"brake|rotor|disc", re.I), "brake-rotor", (0.18, 0.19, 0.20, 1.0)),
+    ("headlamp", re.compile(r"head.?l(?:amp|ight)|light[_-]?f", re.I), "headlamp-lens", (0.78, 0.86, 1.0, 1.0)),
+    ("taillamp", re.compile(r"tail.?l(?:amp|ight)|brake.?light|light[_-]?r", re.I), "taillamp-lens", (0.52, 0.01, 0.008, 1.0)),
+    ("carbon", re.compile(r"carbon|cfiber|(?:^|[_-])cf(?:[_-]|$)", re.I), "carbon-fiber", (0.012, 0.014, 0.016, 1.0)),
+    ("carpet", re.compile(r"carpet|floor.?mat", re.I), "vehicle-carpet", (0.012, 0.013, 0.015, 1.0)),
+    ("leather", re.compile(r"leather|upholstery|seat", re.I), "vehicle-leather", (0.024, 0.027, 0.032, 1.0)),
+    ("dashboard", re.compile(r"dashboard|dash|gauges?|instrument|cluster|soft.?touch", re.I),
+     "dashboard-soft-touch", (0.018, 0.020, 0.024, 1.0)),
+    ("interior", re.compile(r"interior|plastic|console|door.?card|trim|fabric|speaker|symbol", re.I),
+     "vehicle-interior-plastic", (0.018, 0.020, 0.024, 1.0)),
+    ("underbody", re.compile(r"underbody|under.?tray|chassis|subframe|suspension", re.I),
+     "underbody-coating", (0.014, 0.015, 0.017, 1.0)),
+    ("exhaust", re.compile(r"exhaust|muffler|tail.?pipe", re.I), "stainless-steel", (0.24, 0.25, 0.27, 1.0)),
+    ("chrome", re.compile(r"chrome", re.I), "chrome", (0.62, 0.65, 0.68, 1.0)),
+    ("wheel", re.compile(r"wheel|rim|alloy|aluminium|aluminum", re.I), "aluminum-brushed", (0.28, 0.30, 0.32, 1.0)),
+    ("paint", re.compile(r"paint|body|bodyshell|main|exterior", re.I), "vehicle-paint-metallic", (0.42, 0.025, 0.035, 1.0)),
+    ("metal", re.compile(r"metal|steel|iron", re.I), "stainless-steel", (0.22, 0.24, 0.26, 1.0)),
+)
+
+
+# Contracts whose `families[]` carry the fields this converter reads (id, definitionVersion,
+# physical.sizeMeters, shader.defaults). /4 is the current asset pack; /3 stays accepted.
+SUPPORTED_PALETTE_CONTRACTS = ("helix-palette/4", "helix-palette/3")
+
+
+def load_vehicle_palette(path: Path) -> tuple[str, dict[str, dict]]:
+    try:
+        document = json.loads(path.read_text())
+    except Exception as error:
+        raise RuntimeError(f"Palette input is not valid JSON: {error}")
+    contract = document.get("contract")
+    if contract not in SUPPORTED_PALETTE_CONTRACTS or not isinstance(document.get("families"), list):
+        raise RuntimeError(f"Palette input must use contract {' or '.join(SUPPORTED_PALETTE_CONTRACTS)} "
+                           "with a families array")
+    families = {row.get("id"): row for row in document["families"] if isinstance(row, dict)}
+    required = {row[2] for row in VEHICLE_MATERIAL_ROLES} | {"vehicle-interior-plastic"}
+    for family_id in required:
+        family = families.get(family_id)
+        defaults = family.get("shader", {}).get("defaults", {}) if family else {}
+        if not family or not isinstance(family.get("definitionVersion"), str):
+            raise RuntimeError(f"Palette has no versioned reusable family {family_id}")
+        for field in ("roughness", "metallic"):
+            value = defaults.get(field)
+            if not isinstance(value, (int, float)) or not 0 <= value <= 1:
+                raise RuntimeError(f"Palette family {family_id} has invalid {field}")
+    return contract, families
+
+
+def vehicle_material_role(name: str) -> tuple[str, str, tuple]:
+    return next(((role, family, tint) for role, pattern, family, tint in VEHICLE_MATERIAL_ROLES
+                 if pattern.search(name)),
+                ("generic", "vehicle-interior-plastic", (0.12, 0.13, 0.15, 1.0)))
+
+
+def helix_material_binding(family: dict, source_id: str, tint: tuple | None,
+                           authored_maps: bool, alpha_mode: str) -> dict:
+    physical = family.get("physical", {})
+    size = physical.get("sizeMeters")
+    physical_size = size if isinstance(size, list) and len(size) == 2 else None
+    overrides = {}
+    if tint is not None:
+        overrides["tint"] = "#" + "".join(f"{max(0, min(255, round(channel*255))):02X}" for channel in tint[:3])
+    return {
+        "contract": "helix-material-binding/1",
+        "familyId": family["id"],
+        "familyVersion": family["definitionVersion"],
+        "presetId": None,
+        "overrides": overrides,
+        "uv": {"uvSet": 0, "offset": [0.0, 0.0], "scale": [1.0, 1.0], "rotationRadians": 0.0,
+               "physicalSizeMeters": physical_size},
+        "preserved": {"identityBearingDetails": authored_maps, "sourceMaterialId": source_id,
+                      "maskBindings": [], "decals": []},
+        "renderState": {"alphaMode": alpha_mode, "alphaCutoff": 0.5, "doubleSided": False,
+                        "depthWrite": True, "depthTest": True, "blendMode": "normal"},
+    }
+
+
+def restore_materials(roots: list[Path], palette_path: Path, vehicle_root: Path,
+                      configured_paint: list[float] | None = None) -> dict:
+    palette_contract, palette = load_vehicle_palette(palette_path)
+    definitions: dict[str, tuple[dict, Path]] = {}
+    source_diagnostics = {key: [] for key in ("parseFailures", "shadowedDeclarations", "stageConflicts",
+                                               "dynamicTextures", "sentinels", "unsupportedMaps")}
+    # Shared/base-game dependencies first; the mod's own definitions win when
+    # both bind the same mapTo name.
+    for index in reversed(range(len(roots))):
+        root = roots[index]
+        tier = "mod" if index == 0 else "basegame"
+        parsed = parse_materials(root, tier, vehicle_root if index == 0 else None)
+        for alias, identity in parsed["aliases"].items():
+            row = parsed["materials"].get(identity)
+            if row:
+                definitions[alias] = (row, root)
+        for key in source_diagnostics:
+            source_diagnostics[key].extend(parsed["diagnostics"].get(key, []))
+    texture_chain = TextureChain([("mod", roots[0]), *[("basegame", root) for root in roots[1:]]])
+    resolved = mapped = factor_defaults = 0
+    role_counts: dict[str, int] = {}
+    bindings = []
+    texture_resolutions, unresolved_textures, ambiguous_textures = [], [], []
+
+    def material_texture(row: dict, role: str, material_name: str) -> Path | None:
+        raw = row.get("maps", {}).get(role)
+        resolution = texture_chain.resolve(raw)
+        if raw is None:
+            return None
+        portable = {key: value for key, value in resolution.items() if key != "path"}
+        portable.update({"material": material_name, "role": role})
+        if resolution.get("resolved"):
+            hit = Path(resolution["path"])
+            root = next((candidate for _tier, candidate in texture_chain.roots
+                         if candidate == hit or candidate in hit.parents), roots[0])
+            portable["path"] = str(hit.relative_to(root)).replace(os.sep, "/")
+            texture_resolutions.append(portable)
+            return hit
+        if resolution.get("reason") == "ambiguous":
+            portable["candidates"] = [Path(value).name for value in resolution.get("candidates", [])]
+            ambiguous_textures.append(portable)
+        elif not resolution.get("dynamic") and not resolution.get("sentinel"):
+            unresolved_textures.append(portable)
+        return None
+
+    for material in bpy.data.materials:
+        material.use_nodes = True
+        shader = next((node for node in material.node_tree.nodes if node.type == "BSDF_PRINCIPLED"), None)
+        if not shader:
+            continue
+        material_binding = material_row(definitions, material.name)
+        row, owner_root = material_binding if material_binding is not None else (None, roots[0])
+        semantic = material.name.lower()
+        is_glazing = bool(re.search(r"glass|window|windscreen|windshield", semantic))
+        role, family_id, tint = vehicle_material_role(semantic)
+        configured_paint_active = role == "paint" and bool(configured_paint and len(configured_paint) >= 3)
+        if configured_paint_active:
+            tint = tuple(configured_paint[:3]) + (1.0,)
+        is_transmissive = is_glazing or role in {"headlamp", "taillamp"}
+        family = palette[family_id]
+        source_color = False
+        incomplete_paint = False
+        if row:
+            resolved += 1
+            color = row.get("color")
+            if isinstance(color, list) and len(color) >= 3 and not configured_paint_active:
+                rgba = tuple(float(value) for value in color[:4])
+                if len(rgba) == 3:
+                    rgba += (1.0,)
+                shader.inputs["Base Color"].default_value = rgba
+                source_color = True
+            if isinstance(row.get("metallic"), (int, float)):
+                shader.inputs["Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"].default_value = float(row["metallic"])
+            if isinstance(row.get("roughness"), (int, float)):
+                shader.inputs["Roughness"].default_value = float(row["roughness"])
+            base = material_texture(row, "baseColor", material.name)
+            palette_mask = material_texture(row, "colorPalette", material.name)
+            normal = material_texture(row, "normal", material.name)
+            roughness_map = material_texture(row, "roughness", material.name)
+            metallic_map = material_texture(row, "metallic", material.name)
+            attached = False
+            # A configured BeamNG paint is assembled from multi-channel palette
+            # masks in-engine. A portable glTF cannot reproduce that shader by
+            # wiring the mask itself as RGB; doing so yielded disconnected
+            # white/red panels. Keep normal/roughness detail, but use the
+            # selected paint as the portable base-color factor.
+            if base and not configured_paint_active:
+                attached |= connect_image(material.node_tree.nodes, material.node_tree.links, shader, "Base Color", base,
+                                          link_alpha=is_transmissive)
+            elif palette_mask and role == "paint" and not configured_paint_active:
+                # glTF multiplies baseColorTexture by baseColorFactor, so a
+                # BeamNG palette mask can stay authored while the Palette tint
+                # supplies the missing in-engine color factor.
+                attached |= connect_image(material.node_tree.nodes, material.node_tree.links, shader, "Base Color", palette_mask)
+                incomplete_paint = True
+            if normal:
+                attached |= connect_image(material.node_tree.nodes, material.node_tree.links, shader, "Normal", normal, True)
+            if roughness_map:
+                attached |= connect_image(material.node_tree.nodes, material.node_tree.links, shader, "Roughness", roughness_map, True)
+            if metallic_map:
+                attached |= connect_image(material.node_tree.nodes, material.node_tree.links, shader,
+                                          "Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic",
+                                          metallic_map, True)
+            mapped += int(attached)
+            # `translucent` in BeamNG is also used for palette masks, decals,
+            # illuminated gauges and chrome. Those surfaces are not transparent
+            # in the final vehicle. Restrict blend materials to actual glazing.
+            if is_transmissive:
+                shader.inputs["Alpha"].default_value = min(shader.inputs["Alpha"].default_value, 0.42)
+                if hasattr(material, "surface_render_method"):
+                    material.surface_render_method = "DITHERED"
+            else:
+                shader.inputs["Alpha"].default_value = 1.0
+        elif re.search(r"glass|window|windscreen|windshield", semantic):
+            shader.inputs["Base Color"].default_value = (0.025, 0.035, 0.045, 1.0)
+            shader.inputs["Roughness"].default_value = 0.08
+            shader.inputs["Alpha"].default_value = 0.26
+            if hasattr(material, "surface_render_method"):
+                material.surface_render_method = "DITHERED"
+        elif re.search(r"tyre|tire|rubber", semantic):
+            shader.inputs["Base Color"].default_value = (0.012, 0.012, 0.014, 1.0)
+            shader.inputs["Roughness"].default_value = 0.82
+        elif re.search(r"chrome|wheel|rim|metal|exhaust", semantic):
+            shader.inputs["Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"].default_value = 0.82
+            shader.inputs["Roughness"].default_value = 0.25
+        elif re.search(r"paint|body|main", semantic):
+            shader.inputs["Base Color"].default_value = (0.42, 0.025, 0.018, 1.0)
+            shader.inputs["Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"].default_value = 0.18
+            shader.inputs["Roughness"].default_value = 0.24
+            if "Coat Weight" in shader.inputs:
+                shader.inputs["Coat Weight"].default_value = 1.0
+                shader.inputs["Coat Roughness"].default_value = 0.06
+        else:
+            shader.inputs["Roughness"].default_value = 0.55
+        # A large class of older BeamNG interiors declares neutral white
+        # factors and relies on an in-engine skin tint. HELIX has no such tint
+        # target, so preserve embedded maps but close the untextured factors to
+        # the selected black cabin instead of rendering white plastic/leather.
+        if not shader.inputs["Base Color"].is_linked:
+            if re.search(r"leather|upper_leather|interior_d", semantic):
+                shader.inputs["Base Color"].default_value = (0.024, 0.027, 0.032, 1.0)
+                shader.inputs["Roughness"].default_value = 0.42
+            elif re.search(r"plastic|rubber|carpet|fabric|speakers|symbols", semantic):
+                shader.inputs["Base Color"].default_value = (0.018, 0.020, 0.024, 1.0)
+                shader.inputs["Roughness"].default_value = 0.58
+        if re.search(r"(?:int|gauges?)_chrome", semantic):
+            shader.inputs["Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"].default_value = 0.88
+            shader.inputs["Roughness"].default_value = 0.2
+        authored_maps = any(shader.inputs[name].is_linked for name in (
+            "Base Color", "Normal", "Roughness",
+            "Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"))
+        applied_tint = None
+        # BeamNG paint textures are frequently grayscale/palette masks whose
+        # actual color comes from the selected `.pc` configuration. Preserve
+        # the authored image/UV and supply that missing multiplicative factor.
+        palette_authoritative = role in {"tyre", "glass", "brake-rotor", "carbon", "carpet",
+                                         "dashboard", "underbody", "exhaust", "wheel", "interior", "leather"}
+        if role != "generic" and (configured_paint_active or not source_color or palette_authoritative):
+            shader.inputs["Base Color"].default_value = tint
+            applied_tint = tint
+        if not authored_maps or incomplete_paint or configured_paint_active:
+            defaults = family["shader"]["defaults"]
+            if configured_paint_active or not source_color or incomplete_paint:
+                shader.inputs["Base Color"].default_value = tint
+                applied_tint = tint
+            shader.inputs["Metallic IOR Level" if "Metallic IOR Level" in shader.inputs else "Metallic"].default_value = float(defaults["metallic"])
+            shader.inputs["Roughness"].default_value = float(defaults["roughness"])
+            factor_defaults += 1
+            if role == "paint" and "Coat Weight" in shader.inputs:
+                shader.inputs["Coat Weight"].default_value = 1.0
+                shader.inputs["Coat Roughness"].default_value = 0.06
+        if role == "glass":
+            shader.inputs["Base Color"].default_value = (0.025, 0.04, 0.055, 1.0)
+            shader.inputs["Alpha"].default_value = 0.28
+            shader.inputs["Roughness"].default_value = min(0.12, shader.inputs["Roughness"].default_value)
+            transmission = shader.inputs.get("Transmission Weight") or shader.inputs.get("Transmission")
+            if transmission is not None:
+                transmission.default_value = 0.72
+            ior = shader.inputs.get("IOR")
+            if ior is not None:
+                ior.default_value = 1.45
+            if hasattr(material, "surface_render_method"):
+                material.surface_render_method = "DITHERED"
+        declared_alpha = row.get("alpha", {}) if row else {}
+        alpha_mode = str(declared_alpha.get("mode", "blend" if is_transmissive else "opaque")).lower()
+        if alpha_mode == "blend" and not is_transmissive:
+            # Preserve the declaration in provenance but retain the existing
+            # portable opaque fallback for palette/decal materials until the
+            # runtime has the matching staged compositor.
+            alpha_mode = "opaque"
+        bindings.append({"name": material.name, "role": role, "binding": helix_material_binding(
+            family, material.name, applied_tint, authored_maps, alpha_mode),
+            "source": {"provenance": row.get("provenance") if row else None,
+                       "stages": row.get("stages", []) if row else [],
+                       "factors": row.get("factors", {}) if row else {},
+                       "alpha": declared_alpha}})
+        material["helix_vehicle_role"] = role
+        role_counts[role] = role_counts.get(role, 0) + 1
+    total = len(bpy.data.materials)
+    declaration_provenance = sorted({json.dumps(row[0].get("provenance"), sort_keys=True)
+                                     for row in definitions.values() if row[0].get("provenance")})
+    return {"definitions": len({id(row[0]) for row in definitions.values()}), "resolved": resolved, "mapped": mapped, "materials": total,
+            "paletteContract": palette_contract, "bound": total, "factorDefaults": factor_defaults,
+            "familyVersions": {family_id: family["definitionVersion"] for family_id, family in palette.items()},
+            "renderReady": total, "renderReadyCoverage": 1.0 if total else 0.0,
+            "roles": role_counts, "bindings": bindings,
+            "declarationProvenance": [json.loads(value) for value in declaration_provenance],
+            **source_diagnostics, "textureResolutions": texture_resolutions,
+            "unresolvedTextures": unresolved_textures, "ambiguousTextures": ambiguous_textures}
+
+
+def meshes() -> list[bpy.types.Object]:
+    return [obj for obj in bpy.context.scene.objects if obj.type == "MESH" and len(obj.data.polygons) > 0]
+
+
+def world_bounds(obj: bpy.types.Object) -> tuple[Vector, Vector]:
+    points = [obj.matrix_world @ Vector(corner) for corner in obj.bound_box]
+    return Vector((min(point.x for point in points), min(point.y for point in points), min(point.z for point in points))), \
+        Vector((max(point.x for point in points), max(point.y for point in points), max(point.z for point in points)))
+
+
+def bounds_of(objects: list[bpy.types.Object]) -> tuple[Vector, Vector]:
+    values = [world_bounds(obj) for obj in objects]
+    return Vector(tuple(min(row[0][axis] for row in values) for axis in range(3))), \
+        Vector(tuple(max(row[1][axis] for row in values) for axis in range(3)))
+
+
+def centre(obj: bpy.types.Object) -> Vector:
+    lo, hi = world_bounds(obj)
+    return (lo + hi) * 0.5
+
+
+def dimensions(obj: bpy.types.Object) -> Vector:
+    lo, hi = world_bounds(obj)
+    return hi - lo
+
+
+def road_wheel_signal(obj: bpy.types.Object) -> bool:
+    """Recognize road-wheel meshes by semantic name or authored source library.
+
+    BeamNG flexbodies often call a rim by a style name (for example
+    `gavril_VSpoke_17x7_5H_F`) that contains neither `wheel` nor `rim`. The DAE
+    path remains explicit. Steering-wheel libraries are deliberately excluded.
+    """
+    if WHEEL.search(obj.name):
+        return True
+    source = str(obj.get("helix_source_dae", "")).lower()
+    return bool(re.search(r"wheel|rim", source) and not re.search(r"steer|wheelwell", source))
+
+
+def canonical(point: Vector) -> list[float]:
+    # Blender/BeamNG +X-left, +Z-up, -Y-forward -> glTF/HELIX +X-left, +Y-up, +Z-forward.
+    return [round(float(point.x), 4), round(float(point.z), 4), round(float(-point.y), 4)]
+
+
+def tag_for(point: Vector, split_y: float) -> str:
+    return ("l" if point.x >= 0 else "r") + ("f" if point.y <= split_y else "r")
+
+
+def select_wheels(objects: list[bpy.types.Object]) -> tuple[dict[str, bpy.types.Object], dict[str, bpy.types.Object]]:
+    candidates = []
+    for obj in objects:
+        if not road_wheel_signal(obj):
+            continue
+        size = dimensions(obj)
+        c = centre(obj)
+        if max(size) < 0.12 or max(size) > 1.5 or abs(c.x) < 0.25:
+            continue
+        candidates.append(obj)
+    if not candidates:
+        return {}, {}
+    ys = sorted(centre(obj).y for obj in candidates)
+    split_y = (ys[0] + ys[-1]) / 2
+    rims: dict[str, bpy.types.Object] = {}
+    tyres: dict[str, bpy.types.Object] = {}
+    for obj in candidates:
+        tag = tag_for(centre(obj), split_y)
+        target = tyres if TYRE.search(obj.name) else rims
+        if tag not in target or len(obj.data.polygons) > len(target[tag].data.polygons):
+            target[tag] = obj
+    # Some sources call the complete wheel a tyre; allow that authored mesh to be the rim visual too.
+    for tag in ("lf", "rf", "lr", "rr"):
+        if tag not in rims and tag in tyres:
+            rims[tag] = tyres[tag]
+    return rims, tyres
+
+
+def normalize_authored_tyres(objects: list[bpy.types.Object]) -> tuple[list[str], dict, dict]:
+    """Export exactly four instances of one rim-compatible authored tyre source."""
+    rims, _ = select_wheels(objects)
+    actual_rims = {tag: obj for tag, obj in rims.items() if not TYRE.search(obj.name)}
+    if len(actual_rims) != 4:
+        raise RuntimeError("cannot normalize authored tyres without four measured authored rim corners")
+    candidates = [obj for obj in objects if TYRE.search(obj.name)]
+    if not candidates:
+        raise RuntimeError("default configuration contains no authored tyre mesh")
+    rim_radii = {tag: max(dimensions(obj).y, dimensions(obj).z) * 0.5 for tag, obj in actual_rims.items()}
+    reference_radius = sum(rim_radii.values()) / len(rim_radii)
+
+    def compatibility(obj: bpy.types.Object) -> tuple[float, int, str] | None:
+        size = dimensions(obj)
+        radius = max(size.y, size.z) * 0.5
+        radial_roundness = abs(size.y-size.z) / max(size.y, size.z, 0.001)
+        ratio = radius / max(reference_radius, 0.001)
+        if not (0.04 <= size.x <= 0.65 and 0.18 <= radius <= 0.70
+                and radial_roundness <= 0.25 and 0.90 <= ratio <= 1.65):
+            return None
+        return abs(ratio-1.18) + radial_roundness * 0.5, -len(obj.data.polygons), obj.name
+
+    compatible = [(score, obj) for obj in candidates if (score := compatibility(obj)) is not None]
+    if not compatible:
+        measured = [(obj.name, tuple(round(value, 3) for value in dimensions(obj))) for obj in candidates]
+        raise RuntimeError(f"no authored tyre variant is compatible with the selected rims: {measured}")
+    _, source = min(compatible, key=lambda row: row[0])
+    source_identity = f"{Path(str(source.get('helix_source_dae', 'unknown'))).name}:{source.name}"
+    source_centre = centre(source)
+    source_radius = max(dimensions(source).y, dimensions(source).z) * 0.5
+    instances = []
+    for tag in ("lf", "rf", "lr", "rr"):
+        target = centre(actual_rims[tag])
+        desired_radius = max(0.22, min(0.55, rim_radii[tag] * 1.18))
+        copy = source.copy()
+        copy.data = source.data
+        copy.name = f"tyre_{tag}"
+        copy["helix_tyre_source"] = source_identity
+        bpy.context.scene.collection.objects.link(copy)
+        copy.matrix_world = (Matrix.Translation(target) @ Matrix.Scale(desired_radius / source_radius, 4)
+                             @ Matrix.Translation(-source_centre)) @ copy.matrix_world
+        source_side = "l" if source_centre.x >= 0.25 else "r" if source_centre.x <= -0.25 else None
+        if ((source_side is not None and source_side != tag[0])
+                or (source_side is None and tag[0] == "r")):
+            copy.matrix_world = (Matrix.Translation(target) @ Matrix.Rotation(math.pi, 4, "Z")
+                                 @ Matrix.Translation(-target)) @ copy.matrix_world
+        instances.append(copy)
+    chosen_rims = set(actual_rims.values())
+    rim_sources = []
+    for tag, rim in actual_rims.items():
+        identity = f"{Path(str(rim.get('helix_source_dae', 'unknown'))).name}:{rim.name}"
+        rim["helix_rim_source"] = identity
+        rim_sources.append(identity)
+    # Configuration libraries contain centered templates and color variants.
+    # Once four measured rims have won custody, every other true road-wheel
+    # object must be removed so it cannot render beneath the vehicle.
+    for candidate in list(objects):
+        if candidate not in chosen_rims and road_wheel_signal(candidate):
+            bpy.data.objects.remove(candidate, do_unlink=True)
+    objects[:] = meshes()
+    receipt = {"source": source_identity, "instances": [obj.name for obj in instances]}
+    rim_receipt = {"sources": sorted(set(rim_sources)),
+                   "instances": [f"rim_{tag}" for tag in ("lf", "rf", "lr", "rr")]}
+    print(f"[beamng] normalized tyre custody={receipt}")
+    print(f"[beamng] normalized rim custody={rim_receipt}")
+    return [f"instanced one compatible authored tyre source {source_identity} to four measured rim centres",
+            "pruned every unselected authored road-wheel template after four-corner rim custody"], receipt, rim_receipt
+
+
+def expand_axle_wheels(objects: list[bpy.types.Object]) -> list[str]:
+    rims, tyres = select_wheels(objects)
+    # `select_wheels` intentionally lets a complete tyre stand in for a rim
+    # when a source only authors complete wheels. Do not let that fallback hide
+    # centred trim-specific rim geometry: the 992 then rendered four bare rims
+    # and silently discarded its four correctly placed base tyres.
+    actual_rims = {tag: obj for tag, obj in rims.items() if not TYRE.search(obj.name)}
+    if len(actual_rims) == 4 and len(tyres) == 4:
+        return []
+    sources = [obj for obj in objects if road_wheel_signal(obj)]
+    body = vehicle_shell(objects)
+    print(f"[beamng] axle wheel expansion sources={[obj.name for obj in sources]} body={body.name if body else None}")
+    if not sources or not body:
+        return []
+    lo, hi = world_bounds(body)
+    width, length = hi.x-lo.x, hi.y-lo.y
+    # Measured road-car wheel centres sit at roughly 41.5% of body width. The
+    # older 38.5% envelope rule put dependency wheels too far inboard; in the
+    # 992 the driver's line of sight went over the inner fender and straight
+    # onto the left-front tyre.
+    half_track = width * 0.415
+    # Axle-pair legacy assets carry no per-corner transforms. A measured 64%
+    # shell-length wheelbase is conservative across compact and sports-car
+    # bodies; the older 55% rule collapsed short legacy cars below a plausible
+    # road-car wheelbase even though their authored body proportions were sound.
+    front_y, rear_y = lo.y + length * 0.18, hi.y - length * 0.18
+    target_radius = max(0.28, min(0.40, length * 0.075))
+    hub_z = lo.z + target_radius
+    expanded, messages = [], []
+    for tyre_role, pattern in ((False, re.compile(r"(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim", re.I)),
+                               (True, TYRE)):
+        matching = [obj for obj in sources if pattern.search(obj.name)]
+        def source_axle(obj: bpy.types.Object) -> str | None:
+            dae = Path(str(obj.get("helix_source_dae", "")))
+            parent = dae.parent.name.lower()
+            stem = dae.stem.lower()
+            if parent in {"f", "front"} or re.search(r"(?:^|_)f$|front", stem):
+                return "f"
+            if parent in {"r", "rear"} or re.search(r"(?:^|_)r$|rear", stem):
+                return "r"
+            return None
+
+        def source_rank(obj: bpy.types.Object) -> tuple[int, int, str]:
+            return (int(bool(obj.get("helix_configured_mesh"))), len(obj.data.polygons), obj.name)
+
+        shared_tyre_source = max(matching, key=source_rank, default=None) if tyre_role else None
+        axle_named = [obj for obj in matching if source_axle(obj) is not None
+                      or re.search(r"(?:^|_)[fr](?:\d|_|$)|front|rear", obj.name, re.I)]
+        shared_rim_source = (max(matching, key=source_rank, default=None)
+                             if not tyre_role and len({source_axle(obj) for obj in axle_named if source_axle(obj)}) < 2
+                             else None)
+        for axle, axle_pattern, target_y in (("f", re.compile(r"(?:^|_)f(?:\d|_|$)|front", re.I), front_y),
+                                              ("r", re.compile(r"(?:^|_)r(?:\d|_|$)|rear", re.I), rear_y)):
+            source = shared_tyre_source if tyre_role else shared_rim_source or max(
+                (obj for obj in matching if source_axle(obj) == axle or axle_pattern.search(obj.name)),
+                key=source_rank, default=None)
+            if source is None:
+                continue
+            for side, x in (("l", half_track), ("r", -half_track)):
+                copy = source.copy()
+                copy.data = source.data.copy()
+                copy.name = f"{'tyre' if tyre_role else 'wheel'}_source_{side}{axle}"
+                copy["helix_expanded_axle"] = True
+                bpy.context.scene.collection.objects.link(copy)
+                target = Vector((x, target_y, hub_z))
+                copy.matrix_world = Matrix.Translation(target - centre(copy)) @ copy.matrix_world
+                # Legacy common libraries often store spare/axle-pair wheels
+                # flat on Z. Canonical road wheels rotate around local X, so
+                # orient the measured thinnest axis before any corner/radius
+                # checks rather than rejecting an otherwise authored tyre.
+                source_size = dimensions(copy)
+                thin_axis = min(range(3), key=lambda index: source_size[index])
+                if thin_axis == 2:
+                    copy.matrix_world = (Matrix.Translation(target) @ Matrix.Rotation(math.pi / 2, 4, "Y")
+                                         @ Matrix.Translation(-target)) @ copy.matrix_world
+                elif thin_axis == 1:
+                    copy.matrix_world = (Matrix.Translation(target) @ Matrix.Rotation(math.pi / 2, 4, "Z")
+                                         @ Matrix.Translation(-target)) @ copy.matrix_world
+                if side == "r":
+                    copy.matrix_world = (Matrix.Translation(target) @ Matrix.Rotation(math.pi, 4, "Z")
+                                         @ Matrix.Translation(-target)) @ copy.matrix_world
+                size = dimensions(copy)
+                radius = max(size.y, size.z) * 0.5
+                if radius > 0 and not 0.22 <= radius <= 0.55:
+                    current = centre(copy)
+                    copy.matrix_world = (Matrix.Translation(current) @ Matrix.Scale(target_radius / radius, 4)
+                                         @ Matrix.Translation(-current)) @ copy.matrix_world
+                expanded.append(copy)
+    if expanded:
+        for source in sources:
+            if source.name in bpy.data.objects:
+                bpy.data.objects.remove(source, do_unlink=True)
+        objects[:] = meshes()
+        print(f"[beamng] expanded wheel nodes={[(obj.name, tuple(round(v, 3) for v in centre(obj)), tuple(round(v, 3) for v in dimensions(obj))) for obj in expanded]}")
+        messages.append(f"expanded authored axle wheel meshes to four measured body-envelope hub placements")
+    return messages
+
+
+def fit_authored_wheels(objects: list[bpy.types.Object], rims: dict[str, bpy.types.Object],
+                        tyres: dict[str, bpy.types.Object], specified_tyre_radius: float | None = None) -> list[str]:
+    candidates = [obj for obj in objects if BRAKE_HARDWARE.search(obj.name)
+                  and not road_wheel_signal(obj) and abs(centre(obj).x) > 0.3 and max(dimensions(obj)) < 1.0]
+    repairs = []
+    if candidates:
+        ys = sorted(centre(obj).y for obj in candidates)
+        split = (ys[0] + ys[-1]) / 2
+        hubs = {}
+        for obj in candidates:
+            tag = tag_for(centre(obj), split)
+            if tag not in hubs or len(obj.data.polygons) > len(hubs[tag].data.polygons):
+                hubs[tag] = obj
+    else:
+        hubs = {}
+    body = semantic_object(objects, re.compile(r"(?:^|_)(?:body|bodyshell|shell|chassis)(?:$|_)", re.I))
+    target_radius = max(0.24, min(0.46, dimensions(body).y * 0.075)) if body else 0.32
+    for tag in ("lf", "rf", "lr", "rr"):
+        authored = {obj for obj in (rims.get(tag), tyres.get(tag)) if obj is not None}
+        measured_tyre = tyres.get(tag)
+        measured_tyre_radius = (max(dimensions(measured_tyre).y, dimensions(measured_tyre).z) * 0.5
+                                if measured_tyre is not None else None)
+        configured_scale = (specified_tyre_radius / measured_tyre_radius
+                            if specified_tyre_radius and measured_tyre_radius else 1.0)
+        # Four authored per-corner discs/drums/hubs are stronger evidence than
+        # a body-envelope estimate. A partial/ambiguous legacy set is not.
+        expanded_corner = rims.get(tag) if rims.get(tag) is not None and rims[tag].get("helix_expanded_axle") else None
+        measured_hub = hubs.get(tag) if len(hubs) == 4 else None
+        hub = centre(measured_hub) if measured_hub else (centre(expanded_corner) if expanded_corner else (
+            centre(rims[tag]) if tag in rims else None))
+        for obj in authored:
+            lo, hi = world_bounds(obj)
+            current_centre = (lo + hi) * 0.5
+            radius = max(hi.y-lo.y, hi.z-lo.z) * 0.5
+            fitted_radius = target_radius
+            needs_radius_fit = not 0.22 <= radius <= 0.55 or abs(configured_scale - 1.0) > 0.04
+            if abs(configured_scale - 1.0) > 0.04:
+                fitted_radius = radius * configured_scale
+            rim = rims.get(tag)
+            if TYRE.search(obj.name) and rim is not None and rim is not obj:
+                rim_size = dimensions(rim)
+                rim_radius = max(rim_size.y, rim_size.z) * 0.5
+                ratio = radius / max(0.001, rim_radius)
+                # A shared dependency tyre must wrap the selected trim rim,
+                # not merely fall inside a broad road-wheel range. The first
+                # common-asset Porsche pass produced a 0.362 m tyre around a
+                # 0.274 m rim and visibly pushed through the GT3 RS arch.
+                if ratio < 1.08 or ratio > 1.28:
+                    fitted_radius = rim_radius * 1.22
+                    needs_radius_fit = True
+            scale = fitted_radius / radius if radius > 0 and needs_radius_fit else 1.0
+            target = hub or current_centre
+            obj.matrix_world = (Matrix.Translation(target) @ Matrix.Scale(scale, 4)
+                                @ Matrix.Translation(-current_centre)) @ obj.matrix_world
+            if abs(scale - 1.0) > 0.01 or (target-current_centre).length > 0.02:
+                repairs.append(f"fitted authored {obj.name} to measured {tag} hub at {fitted_radius:.3f} m radius")
+    return repairs
+
+
+def configured_tyre_radius(parts: list[str]) -> float | None:
+    """Return the physical outside radius encoded by common BeamNG tyre part IDs."""
+    sizes = []
+    for part in parts:
+        match = re.search(r"(?:tire|tyre)[^\d]*(\d{3})_(\d{2})_(\d{2})(?:_|$)", part, re.I)
+        if not match:
+            continue
+        width_mm, aspect, rim_inches = map(float, match.groups())
+        radius = rim_inches * 0.0127 + width_mm * (aspect / 100.0) / 1000.0
+        if 0.22 <= radius <= 0.55:
+            sizes.append(radius)
+    return sum(sizes) / len(sizes) if sizes else None
+
+
+def normalize_wheel_hardware(objects: list[bpy.types.Object],
+                             rims: dict[str, bpy.types.Object]) -> tuple[list[str], dict | None]:
+    """Keep or instance selected authored brake/hub hardware at exactly four wheel corners."""
+    candidates = [obj for obj in objects if BRAKE_HARDWARE.search(obj.name) and not road_wheel_signal(obj)]
+    if not candidates or len(rims) != 4:
+        return [], None
+    def rank(obj: bpy.types.Object) -> tuple:
+        strong_brake = int(bool(re.search(r"disc|rotor|drum", obj.name, re.I)))
+        size = max(dimensions(obj))
+        return strong_brake, -abs(size-0.38), len(obj.data.polygons)
+    measured = [obj for obj in candidates if abs(centre(obj).x) > 0.3]
+    selected: dict[str, bpy.types.Object] = {}
+    if measured:
+        ys = sorted(centre(obj).y for obj in measured)
+        split = (ys[0] + ys[-1]) / 2
+        for obj in measured:
+            tag = tag_for(centre(obj), split)
+            if tag not in selected or rank(obj) > rank(selected[tag]):
+                selected[tag] = obj
+    instances: dict[str, bpy.types.Object] = {}
+    if len(selected) == 4:
+        instances = selected
+    else:
+        front_pattern = re.compile(r"(?:^|_)f(?:_|$)|front", re.I)
+        rear_pattern = re.compile(r"(?:^|_)r(?:_|$)|rear", re.I)
+        axle_sources = {
+            "f": max((obj for obj in candidates if front_pattern.search(obj.name)), key=rank, default=None),
+            "r": max((obj for obj in candidates if rear_pattern.search(obj.name)), key=rank, default=None),
+        }
+        shared = max(candidates, key=rank)
+        for tag in ("lf", "rf", "lr", "rr"):
+            source = axle_sources[tag[1]] or shared
+            target = centre(rims[tag])
+            copy = source.copy()
+            copy.data = source.data.copy()
+            copy["helix_brake_source_identity"] = f"{Path(str(source.get('helix_source_dae', 'unknown'))).name}:{source.name}"
+            bpy.context.scene.collection.objects.link(copy)
+            copy.matrix_world = Matrix.Translation(target-centre(copy)) @ copy.matrix_world
+            if tag[0] == "r":
+                copy.matrix_world = (Matrix.Translation(target) @ Matrix.Rotation(math.pi, 4, "Z")
+                                     @ Matrix.Translation(-target)) @ copy.matrix_world
+            instances[tag] = copy
+    chosen = set(instances.values())
+    sources = []
+    for tag, obj in instances.items():
+        identity = str(obj.get("helix_brake_source_identity",
+                               f"{Path(str(obj.get('helix_source_dae', 'unknown'))).name}:{obj.name}"))
+        obj["helix_brake_source"] = identity
+        obj.name = f"brake_{tag}"
+        sources.append(identity)
+    for candidate in candidates:
+        if candidate not in chosen and candidate.name in bpy.data.objects:
+            bpy.data.objects.remove(candidate, do_unlink=True)
+    objects[:] = meshes()
+    receipt = {"sources": sorted(set(sources)), "instances": [f"brake_{tag}" for tag in ("lf", "rf", "lr", "rr")]}
+    print(f"[beamng] normalized wheel hardware custody={receipt}")
+    action = "retained four authored per-corner brake/hub meshes" if len(selected) == 4 else \
+        "instanced selected authored axle brake/hub templates to four measured wheel centres"
+    return [action], receipt
+
+
+def rename_wheels(rims: dict[str, bpy.types.Object], tyres: dict[str, bpy.types.Object]) -> None:
+    chosen = set(rims.values()) | set(tyres.values())
+    for obj in chosen:
+        obj.name = f"source_{obj.name}"
+    for tag, obj in rims.items():
+        obj.name = f"rim_{tag}"
+    for tag, obj in tyres.items():
+        if obj not in rims.values():
+            obj.name = f"tyre_{tag}"
+
+
+def seat_points(objects: list[bpy.types.Object]) -> tuple[dict[str, Vector], list[str]]:
+    candidates = [obj for obj in objects if re.search(r"seat", obj.name, re.I)
+                  and not re.search(r"seat.?belt|belt.*seat|seat.?rail|seat.?bracket|seat.?mount", obj.name, re.I)
+                  and max(dimensions(obj)) >= 0.25]
+    if not candidates:
+        return {}, []
+    # Collapse multi-piece seats by side/row, keeping the most substantial authored mesh.
+    ys = sorted(centre(obj).y for obj in candidates)
+    split = (ys[0] + ys[-1]) / 2 if len(ys) > 2 and ys[-1] - ys[0] > 0.45 else math.inf
+    selected: dict[str, bpy.types.Object] = {}
+    for obj in candidates:
+        c = centre(obj)
+        # A singular `seat_R` is normally the right-front seat (CCF); plural
+        # `seats_R` and `bench_R` are the common rear-bench conventions.
+        explicitly_rear = bool(re.search(r"(?:seats|bench)_R(?:$|_)|rear", obj.name, re.I))
+        front = not explicitly_rear and c.y <= split
+        if abs(c.x) < 0.08 and dimensions(obj).x >= 0.5:
+            # One authored rear bench represents two real seating positions.
+            selected["dr" if not front else "df"] = obj
+            selected["pr" if not front else "pf"] = obj
+            continue
+        key = ("d" if c.x >= 0 else "p") + ("f" if front else "r")
+        if key not in selected or len(obj.data.polygons) > len(selected[key].data.polygons):
+            selected[key] = obj
+    sockets: dict[str, Vector] = {}
+    names = {"df": "seat_dside_f", "pf": "seat_pside_f", "dr": "seat_dside_r1", "pr": "seat_pside_r1"}
+    for key, obj in selected.items():
+        lo, hi = world_bounds(obj)
+        lateral = centre(obj).x
+        if abs(lateral) < 0.08 and hi.x-lo.x >= 0.5:
+            lateral = (hi.x-lo.x) * (0.25 if key.startswith("d") else -0.25)
+        # A source seat mesh centre is usually the backrest; the H-point is over the cushion.
+        sockets[names[key]] = Vector((lateral, lo.y * 0.35 + hi.y * 0.65, lo.z + min(0.42, (hi.z-lo.z) * 0.38)))
+    return sockets, [obj.name for obj in selected.values()]
+
+
+def semantic_object(objects: list[bpy.types.Object], pattern: re.Pattern) -> bpy.types.Object | None:
+    candidates = [obj for obj in objects if pattern.search(obj.name)]
+    return max(candidates, key=lambda obj: len(obj.data.polygons), default=None)
+
+
+def vehicle_shell(objects: list[bpy.types.Object]) -> bpy.types.Object | None:
+    named = semantic_object(objects, re.compile(r"(?:^|_)(?:body|bodyshell|shell|chassis)(?:$|_)", re.I))
+    if named:
+        return named
+    candidates = [obj for obj in objects if dimensions(obj).x >= 1.2 and dimensions(obj).y >= 3.0
+                  and dimensions(obj).z >= 0.55 and not road_wheel_signal(obj)]
+    return max(candidates, key=lambda obj: len(obj.data.polygons), default=None)
+
+
+def decimate(objects: list[bpy.types.Object], limit: int = 285_000) -> tuple[int, int]:
+    before = sum(len(obj.data.polygons) for obj in objects)
+    if before <= limit:
+        return before, before
+    # Preserve first-person cabin controls and wheels. Exterior panels may receive a shallow
+    # source-mesh decimation so a high-detail body cannot make the whole vehicle miss budget.
+    protected = [obj for obj in objects if INTERIOR.search(obj.name) or road_wheel_signal(obj)]
+    protected_count = sum(len(obj.data.polygons) for obj in protected)
+    reducible = [obj for obj in objects if obj not in protected and len(obj.data.polygons) > 200]
+    reducible_count = max(1, before - protected_count)
+    target_reducible = max(5_000, limit - protected_count)
+    ratio = min(1.0, target_reducible / reducible_count)
+    for obj in reducible:
+        bpy.context.view_layer.objects.active = obj
+        obj.select_set(True)
+        modifier = obj.modifiers.new("HELIX_web_budget", "DECIMATE")
+        modifier.ratio = max(0.04, ratio)
+        try:
+            bpy.ops.object.modifier_apply(modifier=modifier.name)
+        except Exception as error:
+            print(f"[beamng] decimation skipped for {obj.name}: {error}")
+        obj.select_set(False)
+    return before, sum(len(obj.data.polygons) for obj in objects)
+
+
+def main() -> None:
+    args = arguments()
+    source_root = Path(args.source_root).resolve()
+    vehicle_root = Path(args.vehicle_root).resolve()
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    for dae in args.dae:
+        print(f"[beamng] importing {dae}")
+        build_collada(Path(dae).resolve())
+    objects = meshes()
+    if not objects:
+        raise RuntimeError("selected BeamNG DAE contains no renderable meshes")
+    wanted, config = configured_meshes(vehicle_root, source_root, args.dae,
+                                       args.configuration_hint, {obj.name for obj in objects},
+                                       [Path(value).resolve() for value in args.material_root],
+                                       Path(args.part_index).resolve(), args.bridge_plan_key,
+                                       args.source_sha, args.common_closure)
+    has_dedicated_wheels = any("wheels" in [part.lower() for part in Path(dae).parts] for dae in args.dae)
+    objects, missing_meshes = filter_configuration(objects, wanted, has_dedicated_wheels,
+                                                    args.configuration_hint)
+    config["missingMeshes"] = missing_meshes
+    print(f"[beamng] default config {config['file']}: {len(config['parts'])} parts, "
+          f"{len(objects)} present meshes, {len(missing_meshes)} missing")
+
+    if args.mirror_z:
+        reflection = Matrix.Scale(-1.0, 4, Vector((0.0, 1.0, 0.0)))
+        for obj in objects:
+            obj.matrix_world = reflection @ obj.matrix_world
+
+    # Put the measured tyre contact patch at zero. Underbody/optional meshes can extend below
+    # the tyres and must not lift the whole cabin (the original RX-7 roof-seat defect).
+    axle_repairs = expand_axle_wheels(objects)
+    initial_rims, initial_tyres = select_wheels(objects)
+    wheel_repairs = fit_authored_wheels(objects, initial_rims, initial_tyres,
+                                        configured_tyre_radius(config.get("parts", [])))
+    brake_repairs, brake_custody = normalize_wheel_hardware(objects, initial_rims)
+    grounding = list(initial_tyres.values()) or list(initial_rims.values())
+    if len(initial_rims) != 4:
+        raise RuntimeError(f"default configuration exposes {len(initial_rims)}/4 measurable wheel corners")
+    ground = min(world_bounds(obj)[0].z for obj in grounding)
+    lowest = min(objects, key=lambda obj: world_bounds(obj)[0].z)
+    highest = max(objects, key=lambda obj: world_bounds(obj)[1].z)
+    print(f"[beamng] ground={ground:.4f} from tyres; vertical extremes "
+          f"{lowest.name}={world_bounds(lowest)[0].z:.4f}, {highest.name}={world_bounds(highest)[1].z:.4f}")
+    shift = Matrix.Translation(Vector((0.0, 0.0, -ground)))
+    for obj in objects:
+        obj.matrix_world = shift @ obj.matrix_world
+        obj.select_set(True)
+    bpy.context.view_layer.objects.active = objects[0]
+    bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
+
+    tyre_repairs, tyre_custody, rim_custody = normalize_authored_tyres(objects)
+
+    material_roots = [source_root, *(Path(value).resolve() for value in args.material_root)]
+    materials = restore_materials(material_roots, Path(args.palette).resolve(), vehicle_root,
+                                  config.get("paintBaseColor"))
+    rims, tyres = select_wheels(objects)
+    rename_wheels(rims, tyres)
+    before, after = decimate(objects)
+    lo, hi = bounds_of(objects)
+    sockets_raw, seat_sources = seat_points(objects)
+    steering_obj = semantic_object(objects, re.compile(r"steer(?:ing)?(?:wheel|rim)?", re.I))
+    engine_obj = semantic_object(objects, re.compile(r"(?:^|[_-])engine(?:[_-]|\d|$)", re.I))
+    exhaust_obj = semantic_object(objects, re.compile(r"exhaust|muffler|tail.?pipe", re.I))
+    steering = centre(steering_obj) if steering_obj else None
+    seat_side_repaired = False
+    if steering is not None and "seat_dside_f" in sockets_raw and "seat_pside_f" in sockets_raw:
+        driver_distance = abs(sockets_raw["seat_dside_f"].x-steering.x)
+        passenger_distance = abs(sockets_raw["seat_pside_f"].x-steering.x)
+        if passenger_distance + 0.05 < driver_distance:
+            sockets_raw["seat_dside_f"], sockets_raw["seat_pside_f"] = (
+                sockets_raw["seat_pside_f"], sockets_raw["seat_dside_f"])
+            if "seat_dside_r1" in sockets_raw and "seat_pside_r1" in sockets_raw:
+                sockets_raw["seat_dside_r1"], sockets_raw["seat_pside_r1"] = (
+                    sockets_raw["seat_pside_r1"], sockets_raw["seat_dside_r1"])
+            seat_side_repaired = True
+
+    # Preserve what was genuinely authored before any ergonomic repair. Runtime
+    # sockets may be repaired, but those repairs must never make an incomplete
+    # source look eligible to the Bridge acceptance gate.
+    authored_seat_count = len(sockets_raw)
+    authored_steering_mesh = steering_obj is not None
+
+    repairs: list[str] = list(axle_repairs) + list(wheel_repairs) + list(brake_repairs) + list(tyre_repairs)
+    if seat_side_repaired:
+        repairs.append("assigned driver/passenger sockets from the authored steering-wheel side")
+    driver = sockets_raw.get("seat_dside_f")
+    cabin_shell = vehicle_shell(objects)
+    roof = world_bounds(cabin_shell)[1].z if cabin_shell else hi.z
+    interior_objects = [obj for obj in objects if INTERIOR.search(obj.name)]
+    if driver is None and len(interior_objects) >= 8 and cabin_shell and len(rims) == 4:
+        shell_lo, shell_hi = world_bounds(cabin_shell)
+        front = (canonical(centre(rims["lf"]))[2] + canonical(centre(rims["rf"]))[2]) / 2
+        rear = (canonical(centre(rims["lr"]))[2] + canonical(centre(rims["rr"]))[2]) / 2
+        if steering is not None:
+            # Combined legacy cabins may not expose separate seat nodes. Anchor
+            # their H-point behind the actual authored steering rim instead of
+            # guessing from the body midpoint; this supports both LHD and RHD
+            # layouts and keeps the cockpit lens behind the controls.
+            seat_z = canonical(steering)[2] - 0.45
+            seat_x = steering.x
+        else:
+            seat_z = (front + rear) / 2 + 0.16
+            seat_x = (shell_hi.x-shell_lo.x) * 0.178
+        seat_height = roof - 0.86
+        sockets_raw = {"seat_dside_f": Vector((seat_x, -seat_z, seat_height)),
+                       "seat_pside_f": Vector((-seat_x, -seat_z, seat_height))}
+        driver = sockets_raw["seat_dside_f"]
+        if steering is None:
+            steering = Vector((driver.x, driver.y - 0.45, driver.z + 0.30))
+        seat_sources = [obj.name for obj in interior_objects]
+        repairs.append("inferred two H-points and control anchor inside source-authored combined cabin geometry")
+    if driver is not None and roof - driver.z < 0.86:
+        delta = 0.86 - (roof - driver.z)
+        for key in list(sockets_raw):
+            sockets_raw[key].z -= delta
+        driver = sockets_raw["seat_dside_f"]
+        repairs.append(f"lowered measured H-points {delta:.3f} m for occupant headroom")
+    if driver is not None and steering is not None:
+        driver_gltf, steering_gltf = canonical(driver), canonical(steering)
+        reach = math.dist(driver_gltf, steering_gltf)
+        if not (0.30 <= reach <= 0.80 and steering.z-driver.z >= 0.14 and -steering.y-(-driver.y) >= 0.20):
+            # Keep source lateral placement; refit only the interaction point from the measured H-point.
+            steering = Vector((steering.x if abs(steering.x-driver.x) <= 0.18 else driver.x,
+                               driver.y - 0.45, driver.z + 0.30))
+            repairs.append("re-fitted steering interaction point from measured driver H-point")
+
+    wheel_sockets = {f"wheel_{tag}": canonical(centre(obj)) for tag, obj in rims.items()}
+    sockets = {**wheel_sockets, **{key: canonical(value) for key, value in sockets_raw.items()}}
+    if steering is not None:
+        sockets["steering"] = canonical(steering)
+    if engine_obj is not None:
+        sockets["engine"] = canonical(centre(engine_obj))
+    rear_axle = min(sockets["wheel_lr"][2], sockets["wheel_rr"][2])
+    body_length = dimensions(cabin_shell).y if cabin_shell else hi.y-lo.y
+    if exhaust_obj:
+        exhaust_lo, exhaust_hi = world_bounds(exhaust_obj)
+        authored_exhaust = [round(float(centre(exhaust_obj).x), 4),
+                            round(float(exhaust_lo.z + min(0.12, (exhaust_hi.z-exhaust_lo.z) * 0.25)), 4),
+                            round(float(-exhaust_hi.y), 4)]
+        if authored_exhaust[2] < rear_axle - 0.3:
+            sockets["exhaust"] = authored_exhaust
+        else:
+            sockets["exhaust"] = [authored_exhaust[0], authored_exhaust[1],
+                                  round(float(rear_axle - max(0.45, body_length * 0.20)), 4)]
+            repairs.append("extended exhaust interaction point from source assembly to measured rear overhang")
+    else:
+        sockets["exhaust"] = [0.0, round(float(lo.z + 0.35), 4),
+                              round(float(rear_axle - max(0.45, body_length * 0.20)), 4)]
+        repairs.append("derived exhaust interaction point from measured rear axle and source body length")
+    if driver is not None:
+        driver_canonical = canonical(driver)
+        pedal_y = max(float(lo.z + 0.12), driver_canonical[1] - 0.40)
+        pedal_z = min(float(-lo.y - 0.18), driver_canonical[2] + 0.72)
+        sockets["pedal_throttle"] = [round(driver_canonical[0] - 0.07, 4), round(pedal_y, 4), round(pedal_z, 4)]
+        sockets["pedal_brake"] = [round(driver_canonical[0] + 0.02, 4), round(pedal_y, 4), round(pedal_z, 4)]
+        sockets["pedal_clutch"] = [round(driver_canonical[0] + 0.12, 4), round(pedal_y, 4), round(pedal_z, 4)]
+        # Put the lens at the eye plane and FORWARD of the head centre. The old +2 cm anchor remained inside
+        # the avatar's skull/upper torso on low sports seats, producing a first-person frame filled by skin.
+        cockpit_forward = driver_canonical[2] + 0.04
+        if steering_obj is not None:
+            # The lens must remain behind the actual authored rim, including
+            # legacy cabins whose cushion-derived H-point sits unusually close
+            # to it. Otherwise the QA camera can land beyond the wheel and show
+            # only the hood despite a valid interior.
+            cockpit_forward = min(cockpit_forward, canonical(centre(steering_obj))[2] - 0.32)
+        sockets["cam_cockpit"] = [driver_canonical[0], round(min(float(hi.z - 0.14), driver.z + 0.65), 4),
+                                   round(cockpit_forward, 4)]
+    sockets["cam_chase"] = [0.0, round(float(lo.z + 1.25), 4), round(float(-hi.y - 4.8), 4)]
+    sockets["cam_hood"] = [0.0, round(float(lo.z + (hi.z-lo.z)*0.72), 4), round(float(-lo.y - 0.25), 4)]
+
+    wheel_radii = []
+    for obj in rims.values():
+        size = dimensions(obj)
+        wheel_radii.append(max(size.y, size.z) * 0.5)
+    audio_limits = {extension: AUDIO_SCAN_LIMIT for extension in (".wav", ".ogg", ".flac", ".mp3")}
+    audio_files = len(bounded_asset_paths([vehicle_root], audio_limits))
+    audio_refs = int(bool(config.get("selectedPartSummary", {}).get("semanticEvidence", {}).get("audio")))
+    def geometry_receipt(value: str) -> str:
+        path = Path(value).resolve()
+        try:
+            return str(path.relative_to(source_root))
+        except ValueError:
+            return f"common-dependency:{path.name}"
+
+    receipt = {
+        "HELIX_frame": "+X left, +Y up, +Z forward; metres" + (" (source rear-at-+Z mirrored during import)" if args.mirror_z else ""),
+        "HELIX_bounds": {"min": canonical(Vector((lo.x, hi.y, lo.z))), "max": canonical(Vector((hi.x, lo.y, hi.z)))},
+        "HELIX_vehicle": {
+            "version": 1,
+            "class": "sports-car" if len(sockets_raw) <= 2 else "car",
+            "wheelRadius": round(float(sum(wheel_radii) / len(wheel_radii)), 4) if wheel_radii else None,
+            "sockets": sockets,
+        },
+        "HELIX_import_quality": {
+            "geometry": [geometry_receipt(value) for value in args.dae],
+            "configuration": config,
+            "socketSources": {"wheels": [obj.name for obj in rims.values()], "seats": seat_sources,
+                              "steering": steering_obj.name if steering_obj else None,
+                              "engine": engine_obj.name if engine_obj else None,
+                              "exhaust": exhaust_obj.name if exhaust_obj else "rear-bound fallback"},
+            "tyreCustody": tyre_custody,
+            "rimCustody": rim_custody,
+            "brakeCustody": brake_custody,
+            "materials": materials,
+            "triangles": {"source": before, "export": after},
+            "audio": {"recordedFiles": audio_files, "jbeamReferences": audio_refs},
+            "sourceMeasurements": {
+                "seatHPoints": authored_seat_count,
+                "steeringMesh": authored_steering_mesh,
+                "interiorMeshes": len(interior_objects),
+                "engineMesh": engine_obj is not None,
+                "exhaustMesh": exhaust_obj is not None,
+                "massKg": None,
+            },
+            "repairs": repairs,
+        },
+    }
+
+    for obj in objects:
+        bpy.context.view_layer.objects.active = obj
+        try:
+            bpy.ops.object.shade_auto_smooth(angle=math.radians(35))
+        except Exception:
+            pass
+        obj.select_set(True)
+    bpy.context.view_layer.objects.active = objects[0]
+    bpy.ops.export_scene.gltf(filepath=str(Path(args.output).resolve()), export_format="GLB", use_selection=True,
+                              export_yup=True, export_apply=True, export_image_format="AUTO",
+                              export_materials="EXPORT", export_texcoords=True, export_normals=True,
+                              export_cameras=False, export_lights=False, export_extras=True)
+    Path(args.receipt).write_text(json.dumps(receipt, indent=2) + "\n")
+    print(f"[beamng] exported {after} triangles, {materials['mapped']}/{materials['materials']} mapped materials")
+
+
+if __name__ == "__main__":
+    main()