altium-toolkit 1.1.31 → 1.1.32

package/src/ui/AltiumScene3dRepeatedModelOwnerRepair.mjs

@@ -8,9 +8,15 @@ const CONNECTOR_TOKENS = new Set([
 ])
 const PASSIVE_BODY_PATTERN =
     /(?:^|[^a-z0-9])(?:cap|capacitor|res|resistor|ind|inductor|ferrite|bead|lqw|lqg)(?:$|[^a-z0-9])/i
+const COMPACT_IC_BODY_PATTERN =
+    /(?:^|[^a-z0-9])(?:u?qfn(?:[-_ ]?\d+)?|dfn(?:[-_ ]?\d+)?|qfp(?:[-_ ]?\d+)?|bga(?:[-_ ]?\d+)?|lga(?:[-_ ]?\d+)?)(?:$|[^a-z0-9])/i
 const TIMING_PACKAGE_PATTERN =
     /(?:^|[^a-z0-9])(?:clock|crystal|osc|oscillator|resonator|tcxo|txco|xtal)(?:$|[^a-z0-9])/i
 const TIMING_DESIGNATOR_PATTERN = /^(?:y|xo)\d+[a-z]?$/i
+const AUTHORED_ANCHOR_IDENTITY_PATTERN =
+    /(?:^|[^a-z0-9])(?:antenna|coax|connector|edge|header|jack|mechanical|module|mount|shield|sma|socket|usb)(?:$|[^a-z0-9])/i
+const PAD_FALLBACK_AUTHORED_ANCHOR_PATTERN =
+    /(?:^|[^a-z0-9])(?:antenna|coax|conn|connector|edge|flex|fpc|frame|hardware|header|jack|mechanical|module|shield|sma|socket|usb)(?:$|[^a-z0-9])/i
 
 /**
  * Repairs repeated Altium model-anchor bodies by matching their shared source
@@ -19,6 +25,7 @@ const TIMING_DESIGNATOR_PATTERN = /^(?:y|xo)\d+[a-z]?$/i
 export class AltiumScene3dRepeatedModelOwnerRepair {
     static #OFFSET_TOLERANCE_MIL = 8
     static #MIN_OWNER_DISTANCE_MIL = 25
+    static #MIN_PAD_FALLBACK_OWNER_OFFSET_MIL = 1
 
     /**
      * Applies repeated-model owner repair to an Altium scene.
@@ -50,7 +57,7 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
         )
         const placements = sceneDescription.externalPlacements.map(
             (placement) =>
-                AltiumScene3dRepeatedModelOwnerRepair.#withPassiveOwnerCenter(
+                AltiumScene3dRepeatedModelOwnerRepair.#withSingleOwnerCenter(
                     placement,
                     componentByDesignator.get(
                         String(placement?.designator || '')
@@ -156,18 +163,18 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
     }
 
     /**
-     * Centers a generic passive body on its resolved owner when the body anchor
-     * carries a moderate source-origin offset.
+     * Centers a single body on its resolved owner when the body anchor carries
+     * a source-origin offset that is not an authored mechanical anchor.
      * @param {object} placement Scene placement.
      * @param {object | undefined} component Resolved owner.
      * @param {object} board Scene board metadata.
      * @returns {object}
      */
-    static #withPassiveOwnerCenter(placement, component, board) {
+    static #withSingleOwnerCenter(placement, component, board) {
         if (
             !component ||
             String(placement?.projection?.source || '') !== 'pad-fallback' ||
-            !AltiumScene3dRepeatedModelOwnerRepair.#isPassivePlacement(
+            AltiumScene3dRepeatedModelOwnerRepair.#isAuthoredAnchorPlacement(
                 placement,
                 component
             )
@@ -185,7 +192,8 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
         }
         if (
             Math.hypot(offset.x, offset.y) <=
-            AltiumScene3dRepeatedModelOwnerRepair.#MIN_OWNER_DISTANCE_MIL
+            AltiumScene3dRepeatedModelOwnerRepair
+                .#MIN_PAD_FALLBACK_OWNER_OFFSET_MIL
         ) {
             return placement
         }
@@ -194,28 +202,87 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
             placement,
             component,
             board,
-            offset
+            offset,
+            { preserveRotation: true }
         )
     }
 
     /**
-     * Checks whether a placement/component pair describes a generic passive.
+     * Checks whether a placement/component pair describes an authored hardware
+     * anchor whose source body position should remain authoritative.
      * @param {object} placement Scene placement.
      * @param {object} component PCB component.
      * @returns {boolean}
      */
-    static #isPassivePlacement(placement, component) {
-        return PASSIVE_BODY_PATTERN.test(
-            [
-                placement?.designator,
-                placement?.externalModel?.name,
-                component?.pattern,
-                component?.source,
-                component?.description
-            ]
-                .map((value) => String(value || ''))
-                .join(' ')
+    static #isAuthoredAnchorPlacement(placement, component) {
+        const identityText =
+            AltiumScene3dRepeatedModelOwnerRepair.#identityTextForPlacement(
+                placement,
+                component
+            )
+        if (PASSIVE_BODY_PATTERN.test(identityText)) {
+            return false
+        }
+
+        if (
+            String(placement?.projection?.source || '').toLowerCase() ===
+            'pad-fallback'
+        ) {
+            return (
+                PAD_FALLBACK_AUTHORED_ANCHOR_PATTERN.test(identityText) ||
+                AltiumScene3dRepeatedModelOwnerRepair.#hasCompactIcSourceOriginOffset(
+                    placement,
+                    component,
+                    identityText
+                )
+            )
+        }
+
+        return AUTHORED_ANCHOR_IDENTITY_PATTERN.test(identityText)
+    }
+
+    /**
+     * Checks whether a compact IC uses a small authored source-origin offset.
+     * @param {object} placement Scene placement.
+     * @param {object} component PCB component.
+     * @param {string} identityText Searchable package identity.
+     * @returns {boolean}
+     */
+    static #hasCompactIcSourceOriginOffset(placement, component, identityText) {
+        const distance = AltiumScene3dRepeatedModelOwnerRepair.#distance(
+            placement?.bodyPositionMil,
+            component
         )
+
+        return (
+            COMPACT_IC_BODY_PATTERN.test(identityText) &&
+            distance >
+                AltiumScene3dRepeatedModelOwnerRepair
+                    .#MIN_PAD_FALLBACK_OWNER_OFFSET_MIL &&
+            distance <
+                AltiumScene3dRepeatedModelOwnerRepair.#MIN_OWNER_DISTANCE_MIL
+        )
+    }
+
+    /**
+     * Builds searchable identity text for placement-owner policy checks.
+     * @param {object} placement Scene placement.
+     * @param {object} component PCB component.
+     * @returns {string}
+     */
+    static #identityTextForPlacement(placement, component) {
+        return [
+            placement?.designator,
+            placement?.externalModel?.name,
+            placement?.externalModel?.relativePath,
+            placement?.externalModel?.sourceStream,
+            component?.pattern,
+            component?.source,
+            component?.description,
+            ...Object.values(component?.parameters || {})
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
     }
 
     /**
@@ -428,20 +495,32 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
      * @param {object} component Resolved owner.
      * @param {object} board Scene board metadata.
      * @param {{ x: number, y: number }} offset Source-origin offset.
+     * @param {{ preserveRotation?: boolean }} [options] Repair options.
      * @returns {object}
      */
-    static #withOwner(placement, component, board, offset) {
+    static #withOwner(placement, component, board, offset, options = {}) {
         const mountSide =
             AltiumScene3dRepeatedModelOwnerRepair.#mountSide(component) ||
             placement.mountSide
+        const rotationDeg = options?.preserveRotation
+            ? AltiumScene3dRepeatedModelOwnerRepair.#normalizeAngle(
+                  placement?.rotationDeg
+              )
+            : AltiumScene3dRepeatedModelOwnerRepair.#normalizeAngle(
+                  component?.rotation
+              )
+        const renderableOffset =
+            AltiumScene3dRepeatedModelOwnerRepair.#renderableOwnerAnchorOffset(
+                { mountSide, rotationDeg },
+                offset,
+                placement?.modelTransform
+            )
 
         return {
             ...placement,
             designator: String(component?.designator || placement.designator),
             mountSide,
-            rotationDeg: AltiumScene3dRepeatedModelOwnerRepair.#normalizeAngle(
-                component?.rotation
-            ),
+            rotationDeg,
             positionMil: {
                 ...placement.positionMil,
                 x: Number(component?.x || 0) - Number(board?.centerX || 0),
@@ -453,6 +532,7 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
             },
             modelTransform: {
                 ...(placement.modelTransform || {}),
+                offsetMil: renderableOffset,
                 ownerAnchorOffsetMil: {
                     x: Number(offset?.x || 0),
                     y: Number(offset?.y || 0)
@@ -461,6 +541,52 @@ export class AltiumScene3dRepeatedModelOwnerRepair {
         }
     }
 
+    /**
+     * Converts a board-space source-origin offset into mount-rig local XY.
+     * @param {{ mountSide?: string, rotationDeg?: number }} placement Resolved placement fields.
+     * @param {{ x: number, y: number }} offset Board-space owner offset.
+     * @param {object | undefined} modelTransform Existing model transform.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #renderableOwnerAnchorOffset(placement, offset, modelTransform) {
+        const rotationRad =
+            (-AltiumScene3dRepeatedModelOwnerRepair.#normalizeAngle(
+                Number(placement?.rotationDeg || 0)
+            ) *
+                Math.PI) /
+            180
+        const cos = Math.cos(rotationRad)
+        const sin = Math.sin(rotationRad)
+        const x = Number(offset?.x || 0) * cos - Number(offset?.y || 0) * sin
+        const y = Number(offset?.x || 0) * sin + Number(offset?.y || 0) * cos
+        const z = Number(
+            modelTransform?.offsetMil?.z ?? modelTransform?.dzMil ?? 0
+        )
+
+        return {
+            x: Math.abs(x) < Number.EPSILON ? 0 : Number(x.toFixed(10)),
+            y: AltiumScene3dRepeatedModelOwnerRepair.#isBottomPlacement(
+                placement
+            )
+                ? Math.abs(y) < Number.EPSILON
+                    ? 0
+                    : Number((-y).toFixed(10))
+                : Math.abs(y) < Number.EPSILON
+                  ? 0
+                  : Number(y.toFixed(10)),
+            z: Number.isFinite(z) ? z : 0
+        }
+    }
+
+    /**
+     * Checks whether one placement mounts on the board bottom face.
+     * @param {{ mountSide?: string } | null | undefined} placement Placement.
+     * @returns {boolean}
+     */
+    static #isBottomPlacement(placement) {
+        return String(placement?.mountSide || '').toLowerCase() === 'bottom'
+    }
+
     /**
      * Scores connector-like identity tokens on one component.
      * @param {object} component PCB component.

package/src/ui/PcbScene3dBuilder.mjs

@@ -26,10 +26,16 @@ export class PcbScene3dBuilder {
     static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
     static #DENSE_OVERLAY_KNOCKOUT_COLOR = 0x2f6a2c
     static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 20
+    static #EXACT_BODY_MISMATCH_TOLERANCE_MIL = 1
+    static #NEAR_PACKAGE_AFFINITY_DISTANCE_MIL = 100
     static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
     static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
     static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
+    static #AUTHORED_BODY_IDENTITY_PATTERN =
+        /(?:^|[^a-z0-9])(?:antenna|coax|conn|connector|edge|flex|fpc|frame|hardware|header|jack|mechanical|module|mount|shield|sma|socket|usb)(?:$|[^a-z0-9])/i
+    static #COMPONENT_PACKAGE_BODY_PATTERN =
+        /(?:^|[^a-z0-9])(?:[a-z0-9]*dfn|[a-z0-9]*qfn|bga|cap|capacitor|crystal|diode|ferrite|ind|inductor|lga|lqg[a-z0-9]*|lqw[a-z0-9]*|osc|qfp|res|resistor|sot|transistor|xtal)(?:$|[^a-z0-9])/i
 
     /**
      * Builds a scene description for host 3D renderers.
@@ -81,10 +87,16 @@ export class PcbScene3dBuilder {
                 : []
         }
         const componentBodyModels = componentBodies.map((componentBody) =>
-            PcbScene3dBuilder.#resolveComponentBodyModel(
+            PcbScene3dBuilder.#shouldSuppressLayerlessBodyPlaceholder(
                 componentBody,
-                modelRegistry
+                componentBodies,
+                board
             )
+                ? null
+                : PcbScene3dBuilder.#resolveComponentBodyModel(
+                      componentBody,
+                      modelRegistry
+                  )
         )
         const bodyMatches = PcbScene3dBuilder.#resolveComponentBodyMatches(
             componentBodies,
@@ -193,12 +205,12 @@ export class PcbScene3dBuilder {
 
     /**
      * Builds one procedural component scene entry.
-     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null, source?: string, modelPath?: string }} component
+     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null, source?: string, description?: string, parameters?: Record<string, unknown>, modelPath?: string }} component
      * @param {{ x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[]} pads
      * @param {{ centerX: number, centerY: number }} board
      * @param {number} thicknessMil
      * @param {{ resolveComponentModel: (component: any) => { name: string, relativePath: string, format: string } | null } | null} modelRegistry
-     * @returns {{ designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, boardPositionMil: { x: number, y: number, z: number }, pattern: string, source: string, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null }}
+     * @returns {{ designator: string, mountSide: string, rotationDeg: number, positionMil: { x: number, y: number, z: number }, boardPositionMil: { x: number, y: number, z: number }, pattern: string, source: string, description: string, parameters: Record<string, unknown>, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null }}
      */
     static #buildComponent(
         component,
@@ -233,6 +245,13 @@ export class PcbScene3dBuilder {
             },
             pattern: String(component.pattern || ''),
             source: String(component.source || ''),
+            description: String(component.description || ''),
+            parameters:
+                component.parameters &&
+                typeof component.parameters === 'object' &&
+                !Array.isArray(component.parameters)
+                    ? { ...component.parameters }
+                    : {},
             body,
             externalModel: modelRegistry
                 ? modelRegistry.resolveComponentModel(component)
@@ -275,6 +294,16 @@ export class PcbScene3dBuilder {
             return null
         }
 
+        if (
+            !matchedComponent &&
+            PcbScene3dBuilder.#shouldDropUnmatchedPackageBody(
+                componentBody,
+                components
+            )
+        ) {
+            return null
+        }
+
         if (
             !matchedComponent &&
             !PcbScene3dBuilder.#isBodyPositionNearBoard(componentBody, board)
@@ -540,6 +569,12 @@ export class PcbScene3dBuilder {
                         bodyIndex,
                         componentIndex,
                         affinityScore,
+                        nearPackageAffinityScore:
+                            PcbScene3dBuilder.#nearPackageAffinityScore(
+                                componentBody,
+                                affinityScore,
+                                distance
+                            ),
                         preciseOwnerScore:
                             precise && (sideCompatible || affinityScore > 0)
                                 ? 1
@@ -555,6 +590,8 @@ export class PcbScene3dBuilder {
         closeCandidates
             .sort(
                 (left, right) =>
+                    right.nearPackageAffinityScore -
+                        left.nearPackageAffinityScore ||
                     right.preciseOwnerScore - left.preciseOwnerScore ||
                     right.sideAffinityScore - left.sideAffinityScore ||
                     right.affinityScore - left.affinityScore ||
@@ -804,7 +841,11 @@ export class PcbScene3dBuilder {
         distanceMil
     ) {
         if (PcbScene3dBuilder.#isPreciseBodyComponentDistance(distanceMil)) {
-            return true
+            return !PcbScene3dBuilder.#isIncompatiblePackageBodyMatch(
+                componentBody,
+                component,
+                distanceMil
+            )
         }
 
         if (
@@ -825,6 +866,242 @@ export class PcbScene3dBuilder {
         return bodyCount > 0 && bodyCount <= candidateCount
     }
 
+    /**
+     * Scores short-range package metadata matches above no-affinity anchors.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @param {number} affinityScore Shared body/component identity score.
+     * @param {number} distanceMil Body/component anchor distance.
+     * @returns {number}
+     */
+    static #nearPackageAffinityScore(
+        componentBody,
+        affinityScore,
+        distanceMil
+    ) {
+        return PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            Number(affinityScore || 0) > 0 &&
+            Number(distanceMil || 0) <=
+                PcbScene3dBuilder.#NEAR_PACKAGE_AFFINITY_DISTANCE_MIL
+            ? 1
+            : 0
+    }
+
+    /**
+     * Checks whether an unmatched package-like body should be suppressed
+     * because it sits on an exact but incompatible component anchor.
+     * @param {{ name?: string, identifier?: string, positionMil?: { x?: number, y?: number } }} componentBody Component-body record.
+     * @param {{ x: number, y: number, pattern?: string, source?: string, modelPath?: string }[]} components PCB components.
+     * @returns {boolean}
+     */
+    static #shouldDropUnmatchedPackageBody(componentBody, components) {
+        if (
+            !PcbScene3dBuilder.#isComponentPackageBody(componentBody) ||
+            PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody)
+        ) {
+            return false
+        }
+
+        const exactComponents = (
+            Array.isArray(components) ? components : []
+        ).filter(
+            (component) =>
+                PcbScene3dBuilder.#distanceBetweenBodyAndComponent(
+                    componentBody,
+                    component
+                ) <= PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL
+        )
+
+        return (
+            exactComponents.length > 0 &&
+            exactComponents.every(
+                (component) =>
+                    PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                        componentBody,
+                        component
+                    ) <= 0
+            )
+        )
+    }
+
+    /**
+     * Checks whether a precise body/component pair is a package-family mismatch.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component PCB component.
+     * @param {number} distanceMil Body/component anchor distance.
+     * @returns {boolean}
+     */
+    static #isIncompatiblePackageBodyMatch(
+        componentBody,
+        component,
+        distanceMil
+    ) {
+        return (
+            Number(distanceMil || 0) <=
+                PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL &&
+            PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            !PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody) &&
+            PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                componentBody,
+                component
+            ) <= 0
+        )
+    }
+
+    /**
+     * Checks whether a component body names a package model rather than an
+     * authored board mechanical.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #isComponentPackageBody(componentBody) {
+        return PcbScene3dBuilder.#COMPONENT_PACKAGE_BODY_PATTERN.test(
+            PcbScene3dBuilder.#componentBodyIdentityText(componentBody)
+        )
+    }
+
+    /**
+     * Checks whether a component body identity describes an authored hardware
+     * or connector anchor that can legitimately sit away from a footprint
+     * center.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #isAuthoredBodyIdentity(componentBody) {
+        return PcbScene3dBuilder.#AUTHORED_BODY_IDENTITY_PATTERN.test(
+            PcbScene3dBuilder.#componentBodyIdentityText(componentBody)
+        )
+    }
+
+    /**
+     * Checks whether a layerless component body is a footprint-library
+     * placeholder rather than a board-side placement.
+     * @param {{ layer?: string, name?: string, identifier?: string, modelId?: string, checksum?: number | null, positionMil?: { x?: number, y?: number } }} componentBody Component body record.
+     * @param {object[]} componentBodies All component body records.
+     * @param {{ minX: number, minY: number, widthMil: number, heightMil: number }} board Board envelope.
+     * @returns {boolean}
+     */
+    static #shouldSuppressLayerlessBodyPlaceholder(
+        componentBody,
+        componentBodies,
+        board
+    ) {
+        if (
+            !PcbScene3dBuilder.#isLayerlessComponentBody(componentBody) ||
+            PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody)
+        ) {
+            return false
+        }
+
+        return (
+            !PcbScene3dBuilder.#isBodyPositionNearBoard(componentBody, board) ||
+            PcbScene3dBuilder.#hasLayeredEquivalentPackageBody(
+                componentBody,
+                componentBodies
+            )
+        )
+    }
+
+    /**
+     * Checks whether a body lacks an authored mechanical layer.
+     * @param {{ layer?: string }} componentBody Component body record.
+     * @returns {boolean}
+     */
+    static #isLayerlessComponentBody(componentBody) {
+        return String(componentBody?.layer || '').trim() === ''
+    }
+
+    /**
+     * Checks whether a layerless body duplicates a real board-side body.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Candidate layerless body.
+     * @param {object[]} componentBodies All component body records.
+     * @returns {boolean}
+     */
+    static #hasLayeredEquivalentPackageBody(componentBody, componentBodies) {
+        return (Array.isArray(componentBodies) ? componentBodies : []).some(
+            (candidate) =>
+                candidate !== componentBody &&
+                !PcbScene3dBuilder.#isLayerlessComponentBody(candidate) &&
+                PcbScene3dBuilder.#componentBodiesShareModelIdentity(
+                    componentBody,
+                    candidate
+                ) &&
+                PcbScene3dBuilder.#distanceBetweenBodies(
+                    componentBody,
+                    candidate
+                ) <= PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL
+        )
+    }
+
+    /**
+     * Checks whether two component bodies refer to the same external package.
+     * @param {{ name?: string, identifier?: string, modelId?: string, checksum?: number | null }} left First body.
+     * @param {{ name?: string, identifier?: string, modelId?: string, checksum?: number | null }} right Second body.
+     * @returns {boolean}
+     */
+    static #componentBodiesShareModelIdentity(left, right) {
+        const leftModelId = PcbScene3dBuilder.#normalizeIdentityToken(
+            left?.modelId
+        )
+        const rightModelId = PcbScene3dBuilder.#normalizeIdentityToken(
+            right?.modelId
+        )
+        if (leftModelId && rightModelId && leftModelId === rightModelId) {
+            return true
+        }
+
+        const leftChecksum = Number(left?.checksum)
+        const rightChecksum = Number(right?.checksum)
+        if (
+            Number.isFinite(leftChecksum) &&
+            Number.isFinite(rightChecksum) &&
+            leftChecksum === rightChecksum
+        ) {
+            return true
+        }
+
+        const leftName = PcbScene3dBuilder.#normalizeBodyNameToken(left)
+        const rightName = PcbScene3dBuilder.#normalizeBodyNameToken(right)
+
+        return Boolean(leftName && rightName && leftName === rightName)
+    }
+
+    /**
+     * Normalizes a body model name or identifier for duplicate detection.
+     * @param {{ name?: string, identifier?: string }} componentBody Component body.
+     * @returns {string}
+     */
+    static #normalizeBodyNameToken(componentBody) {
+        return PcbScene3dBuilder.#normalizeIdentityToken(
+            componentBody?.name || componentBody?.identifier
+        ).replace(/\.[a-z0-9]+$/i, '')
+    }
+
+    /**
+     * Normalizes an identity token for case-insensitive comparisons.
+     * @param {unknown} value Raw token.
+     * @returns {string}
+     */
+    static #normalizeIdentityToken(value) {
+        return String(value || '')
+            .trim()
+            .toLowerCase()
+    }
+
+    /**
+     * Builds searchable identity text for one component body.
+     * @param {{ name?: string, identifier?: string, modelId?: string }} componentBody Component-body record.
+     * @returns {string}
+     */
+    static #componentBodyIdentityText(componentBody) {
+        return [
+            componentBody?.identifier,
+            componentBody?.name,
+            componentBody?.modelId
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
+    }
+
     /**
      * Pairs one unresolved repeated body group with a repeated component group
      * by preserving the dominant ordering axis and choosing the pairing that
@@ -1541,6 +1818,21 @@ export class PcbScene3dBuilder {
         )
     }
 
+    /**
+     * Returns the euclidean distance between two component body anchors.
+     * @param {{ positionMil?: { x?: number, y?: number } }} left First body.
+     * @param {{ positionMil?: { x?: number, y?: number } }} right Second body.
+     * @returns {number}
+     */
+    static #distanceBetweenBodies(left, right) {
+        return Math.hypot(
+            Number(left?.positionMil?.x || 0) -
+                Number(right?.positionMil?.x || 0),
+            Number(left?.positionMil?.y || 0) -
+                Number(right?.positionMil?.y || 0)
+        )
+    }
+
     /**
      * Returns true when one unresolved body anchor still lies close enough to
      * the board envelope to be renderable without a component match.