altium-toolkit 1.1.32 → 1.1.35

package/src/ui/PcbScene3dBuilder.mjs

@@ -9,13 +9,16 @@ import { AltiumScene3dExternalPlacementAdapter } from './AltiumScene3dExternalPl
 import { AltiumScene3dBottomPadRotationAdapter } from './AltiumScene3dBottomPadRotationAdapter.mjs'
 import { AltiumScene3dComponentBodyAdapter } from './AltiumScene3dComponentBodyAdapter.mjs'
 import { AltiumScene3dAuthoredBodyAnchorAdapter } from './AltiumScene3dAuthoredBodyAnchorAdapter.mjs'
+import { AltiumScene3dShapeStackOwnerAdapter } from './AltiumScene3dShapeStackOwnerAdapter.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
 import { PcbScene3dPackages } from './PcbScene3dPackages.mjs'
 import { PcbScene3dPlacementSideResolver } from './PcbScene3dPlacementSideResolver.mjs'
 import { PcbScene3dStaticBodyPlacementBuilder } from './PcbScene3dStaticBodyPlacementBuilder.mjs'
+import { PcbScene3dPadYawResolver } from './PcbScene3dPadYawResolver.mjs'
 import { PcbScene3dTextBoxLayoutResolver } from './PcbScene3dTextBoxLayoutResolver.mjs'
 import { PcbFootprintPadAxisNormalizer } from './PcbFootprintPadAxisNormalizer.mjs'
+import { PcbScene3dCopperRegionDetailBuilder } from './PcbScene3dCopperRegionDetailBuilder.mjs'
 
 /**
  * Builds deterministic 3D scene data from the normalized PCB model.
@@ -31,11 +34,27 @@ export class PcbScene3dBuilder {
     static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
     static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
     static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
+    static #OVERSIZED_GENERIC_FALLBACK_MAX_MIL = 800
+    static #TIMING_STACK_BODY_RADIUS_MIL = 220
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
+    static #LOW_CONFIDENCE_GENERIC_FOOTPRINT_PATTERN =
+        /(?:^|[^a-z0-9])(?:edge|finger|fingers|contact|contacts|mech|mechanical|jumper|jump)(?:$|[^a-z0-9])/i
     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 #AUTHORED_COVER_STACK_IDENTITY_PATTERN =
+        /(?:^|[^a-z0-9])(?:emi|rf|rfi|shield|cover|can)(?:$|[^a-z0-9])/i
+    static #MECHANICAL_SHIELD_FALLBACK_PATTERN =
+        /(?:^|[^a-z0-9])(?:emi|rfi|shield|cover|can)(?:$|[^a-z0-9])/i
+    static #MECHANICAL_SHIELD_FRAME_OWNER_PATTERN =
+        /(?=.*(?:^|[^a-z0-9])(?:emi|rfi|rf|shield|can)(?:$|[^a-z0-9]))(?=.*(?:^|[^a-z0-9])frame(?:$|[^a-z0-9]))/i
+    static #MECHANICAL_SHIELD_FRAME_BODY_PATTERN =
+        /(?:^|[^a-z0-9])(?:frame[0-9]*|leg|rail|side|wall)(?:$|[^a-z0-9])/i
+    static #MECHANICAL_SHIELD_FRAME_OWNER_RADIUS_MIL = 750
     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
+    static #TIMING_STACK_COMPONENT_PATTERN =
+        /(?:^|[^a-z0-9])(?:clock|crystal|osc|oscillator|resonator|tcxo|txco|xtal)(?:$|[^a-z0-9])/i
+    static #TIMING_STACK_DESIGNATOR_PATTERN = /^(?:y|xo)\d+[a-z]?$/i
 
     /**
      * Builds a scene description for host 3D renderers.
@@ -60,6 +79,7 @@ export class PcbScene3dBuilder {
         const tracks = Array.isArray(pcb.tracks) ? pcb.tracks : []
         const arcs = Array.isArray(pcb.arcs) ? pcb.arcs : []
         const fills = Array.isArray(pcb.fills) ? pcb.fills : []
+        const regionFills = PcbScene3dCopperRegionDetailBuilder.build(pcb)
         const texts = Array.isArray(pcb.texts) ? pcb.texts : []
         const vias = Array.isArray(pcb.vias) ? pcb.vias : []
         const silkscreenRegions =
@@ -87,6 +107,7 @@ export class PcbScene3dBuilder {
                 : []
         }
         const componentBodyModels = componentBodies.map((componentBody) =>
+            PcbScene3dBuilder.#shouldRenderStaticGeometryOnly(componentBody) ||
             PcbScene3dBuilder.#shouldSuppressLayerlessBodyPlaceholder(
                 componentBody,
                 componentBodies,
@@ -141,15 +162,17 @@ export class PcbScene3dBuilder {
             boardAssemblyModel:
                 modelRegistry?.resolveBoardAssemblyModel?.(documentModel) ||
                 null,
-            components: components.map((component) =>
-                PcbScene3dBuilder.#buildComponent(
-                    component,
-                    pads,
-                    board,
-                    thicknessMil,
-                    modelRegistry
+            components: components
+                .map((component) =>
+                    PcbScene3dBuilder.#buildComponent(
+                        component,
+                        pads,
+                        board,
+                        thicknessMil,
+                        modelRegistry
+                    )
                 )
-            ),
+                .filter(Boolean),
             externalPlacements: componentBodies
                 .map((componentBody, index) =>
                     PcbScene3dBuilder.#buildExternalPlacement(
@@ -167,6 +190,7 @@ export class PcbScene3dBuilder {
                 componentBodies,
                 bodyMatches,
                 components,
+                pads,
                 board,
                 thicknessMil
             ),
@@ -177,7 +201,7 @@ export class PcbScene3dBuilder {
                 pads,
                 tracks,
                 arcs,
-                fills,
+                fills: [...fills, ...regionFills],
                 vias,
                 polygons: Array.isArray(pcb.polygons) ? pcb.polygons : [],
                 silkscreen: {
@@ -191,8 +215,11 @@ export class PcbScene3dBuilder {
             AltiumScene3dBottomPadRotationAdapter.apply(
                 AltiumScene3dComponentBodyAdapter.apply(
                     AltiumScene3dExternalPlacementAdapter.apply(
-                        PcbScene3dBoardOutlineRefiner.refine(
-                            sceneDescription,
+                        AltiumScene3dShapeStackOwnerAdapter.apply(
+                            PcbScene3dBoardOutlineRefiner.refine(
+                                sceneDescription,
+                                sceneDocumentModel
+                            ),
                             sceneDocumentModel
                         ),
                         sceneDocumentModel
@@ -210,7 +237,7 @@ export class PcbScene3dBuilder {
      * @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, description: string, parameters: Record<string, unknown>, body: { family: string, sizeMil: { width: number, depth: number, height: number } }, externalModel: { name: string, relativePath: string, format: string } | null }}
+     * @returns {{ componentIndex: number | null, 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, renderFallbackBody?: boolean } | null}
      */
     static #buildComponent(
         component,
@@ -220,8 +247,27 @@ export class PcbScene3dBuilder {
         modelRegistry
     ) {
         const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
-        const padSpan = PcbScene3dBuilder.#resolvePadSpan(component, pads)
+        const rotationDeg = PcbScene3dBuilder.#resolveComponentRotation(
+            component,
+            pads,
+            mountSide
+        )
+        const padSpan = PcbScene3dBuilder.#resolvePadSpan(
+            component,
+            pads,
+            rotationDeg
+        )
         const body = PcbScene3dPackages.resolve(component, padSpan)
+        const externalModel = modelRegistry
+            ? modelRegistry.resolveComponentModel(component)
+            : null
+        const suppressFallbackBody =
+            PcbScene3dBuilder.#shouldSuppressProceduralComponent(
+                component,
+                body,
+                externalModel
+            )
+
         const halfBoardThickness = thicknessMil / 2
         const halfBodyHeight = body.sizeMil.height / 2
         const z =
@@ -230,9 +276,12 @@ export class PcbScene3dBuilder {
                 : halfBoardThickness + halfBodyHeight
 
         return {
+            componentIndex: Number.isFinite(Number(component.componentIndex))
+                ? Number(component.componentIndex)
+                : null,
             designator: component.designator,
             mountSide,
-            rotationDeg: Number(component.rotation || 0),
+            rotationDeg,
             positionMil: {
                 x: Number(component.x || 0) - Number(board.centerX || 0),
                 y: Number(component.y || 0) - Number(board.centerY || 0),
@@ -253,12 +302,90 @@ export class PcbScene3dBuilder {
                     ? { ...component.parameters }
                     : {},
             body,
-            externalModel: modelRegistry
-                ? modelRegistry.resolveComponentModel(component)
-                : null
+            externalModel,
+            ...(suppressFallbackBody ? { renderFallbackBody: false } : {})
         }
     }
 
+    /**
+     * Checks whether one generated fallback body is too uncertain to render.
+     * @param {{ pattern?: string, source?: string, description?: string }} component Source component.
+     * @param {{ family?: string, sizeMil?: { width?: number, depth?: number } }} body Procedural body.
+     * @param {object | null} externalModel Resolved external model.
+     * @returns {boolean}
+     */
+    static #shouldSuppressProceduralComponent(component, body, externalModel) {
+        return (
+            !externalModel &&
+            body?.family === 'generic' &&
+            ((PcbScene3dBuilder.#isOversizedGenericFallback(body) &&
+                PcbScene3dBuilder.#isLowConfidenceGenericFootprint(
+                    component
+                )) ||
+                PcbScene3dBuilder.#isMechanicalShieldFallback(component))
+        )
+    }
+
+    /**
+     * Checks whether a generic component row describes authored shield
+     * hardware that should not become a filled fallback box.
+     * @param {{ pattern?: string, source?: string, description?: string, parameters?: Record<string, unknown>, provenance?: Record<string, unknown> }} component Source component.
+     * @returns {boolean}
+     */
+    static #isMechanicalShieldFallback(component) {
+        return PcbScene3dBuilder.#MECHANICAL_SHIELD_FALLBACK_PATTERN.test(
+            PcbScene3dBuilder.#componentIdentityText(component)
+        )
+    }
+
+    /**
+     * Builds normalized free-text identity for component classification.
+     * @param {{ pattern?: string, source?: string, description?: string, parameters?: Record<string, unknown>, provenance?: Record<string, unknown> }} component Source component.
+     * @returns {string}
+     */
+    static #componentIdentityText(component) {
+        return [
+            component?.pattern,
+            component?.source,
+            component?.description,
+            component?.provenance?.sourceLibReference,
+            component?.provenance?.footprintDescription,
+            ...Object.values(component?.parameters || {})
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
+    }
+
+    /**
+     * Checks whether one generic fallback body spans too much of the board.
+     * @param {{ sizeMil?: { width?: number, depth?: number } }} body Procedural body.
+     * @returns {boolean}
+     */
+    static #isOversizedGenericFallback(body) {
+        return (
+            Math.max(
+                Number(body?.sizeMil?.width || 0),
+                Number(body?.sizeMil?.depth || 0)
+            ) > PcbScene3dBuilder.#OVERSIZED_GENERIC_FALLBACK_MAX_MIL
+        )
+    }
+
+    /**
+     * Checks for footprint identities that describe board features or
+     * mechanical placeholders more often than physical package bodies.
+     * @param {{ pattern?: string, source?: string, description?: string }} component Source component.
+     * @returns {boolean}
+     */
+    static #isLowConfidenceGenericFootprint(component) {
+        return PcbScene3dBuilder.#LOW_CONFIDENCE_GENERIC_FOOTPRINT_PATTERN.test(
+            [
+                component?.pattern,
+                component?.source,
+                component?.description
+            ].join(' ')
+        )
+    }
+
     /**
      * Resolves one component-body model through the active registry.
      * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody Component body metadata.
@@ -272,7 +399,7 @@ export class PcbScene3dBuilder {
     /**
      * Builds one explicit external-model placement from normalized component
      * body metadata.
-     * @param {{ modelId?: string, checksum?: number | null, embedded?: boolean, name?: string, identifier?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, modelRotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number }} componentBody
+     * @param {{ modelId?: string, checksum?: number | null, embedded?: boolean, name?: string, identifier?: string, layer?: string, positionMil?: { x?: number, y?: number }, rotationDeg?: number, modelRotationDeg?: { x?: number, y?: number, z?: number }, dzMil?: number, bodyOpacity?: number | string }} componentBody
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, rotation?: number, height?: number | null } | null} matchedComponent
      * @param {{ origin: string, name: string, format: string, payloadText?: string, sourceStream?: string, relativePath?: string } | null} resolvedModel
      * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components
@@ -290,10 +417,24 @@ export class PcbScene3dBuilder {
         board,
         thicknessMil
     ) {
+        if (PcbScene3dBuilder.#shouldRenderStaticGeometryOnly(componentBody)) {
+            return null
+        }
+
         if (!resolvedModel) {
             return null
         }
 
+        if (
+            PcbScene3dBuilder.#isPositiveTimingStackPackageBody(
+                componentBody,
+                matchedComponent,
+                components
+            )
+        ) {
+            return null
+        }
+
         if (
             !matchedComponent &&
             PcbScene3dBuilder.#shouldDropUnmatchedPackageBody(
@@ -352,7 +493,8 @@ export class PcbScene3dBuilder {
             modelTransform: {
                 rotationDeg: modelRotation,
                 dzMil: PcbScene3dBuilder.#resolveComponentBodyVerticalOffset(
-                    componentBody
+                    componentBody,
+                    matchedComponent
                 )
             },
             projection: PcbScene3dBuilder.#resolveProjectionDiagnostics(
@@ -361,24 +503,126 @@ export class PcbScene3dBuilder {
                 pads,
                 resolvedModel
             ),
+            ...PcbScene3dBuilder.#componentBodyDisplayMetadata(componentBody),
             externalModel: resolvedModel
         }
     }
 
+    /**
+     * Resolves optional component-body display metadata for external renderers.
+     * @param {{ bodyOpacity?: number | string }} componentBody Component body.
+     * @returns {{ bodyOpacity?: number }}
+     */
+    static #componentBodyDisplayMetadata(componentBody) {
+        const opacity = Number(componentBody?.bodyOpacity)
+
+        return Number.isFinite(opacity) && opacity > 0 && opacity < 1
+            ? { bodyOpacity: opacity }
+            : {}
+    }
+
     /**
      * Resolves the vertical offset that should remain after the viewer seats
      * raw model bounds on the board face.
      * @param {{ dzMil?: number, standoffHeightMil?: number | null }} componentBody Component-body placement metadata.
+     * @param {object | null} matchedComponent Matched owner component.
      * @returns {number}
      */
-    static #resolveComponentBodyVerticalOffset(componentBody) {
+    static #resolveComponentBodyVerticalOffset(
+        componentBody,
+        matchedComponent = null
+    ) {
         const standoffHeightMil = Number(componentBody?.standoffHeightMil)
         if (Number.isFinite(standoffHeightMil)) {
-            return standoffHeightMil < 0 ? standoffHeightMil : 0
+            return standoffHeightMil < 0 ||
+                PcbScene3dBuilder.#shouldPreservePositiveBodyStandoff(
+                    componentBody,
+                    matchedComponent
+                )
+                ? standoffHeightMil
+                : 0
         }
 
         const dzMil = Number(componentBody?.dzMil)
-        return Number.isFinite(dzMil) && dzMil < 0 ? dzMil : 0
+        return Number.isFinite(dzMil) &&
+            (dzMil < 0 ||
+                PcbScene3dBuilder.#shouldPreservePositiveBodyStandoff(
+                    componentBody,
+                    matchedComponent
+                ))
+            ? dzMil
+            : 0
+    }
+
+    /**
+     * Checks whether a positive shape-body standoff is part of an authored
+     * stack instead of a model-origin quirk that should be seated on the board.
+     * @param {object | null | undefined} componentBody Component-body row.
+     * @param {object | null} matchedComponent Matched owner component.
+     * @returns {boolean}
+     */
+    static #shouldPreservePositiveBodyStandoff(
+        componentBody,
+        matchedComponent
+    ) {
+        return (
+            (!matchedComponent &&
+                PcbScene3dBuilder.#isShapeBasedComponentBody(componentBody)) ||
+            PcbScene3dBuilder.#hasAuthoredCoverStackStandoff(
+                componentBody,
+                matchedComponent
+            )
+        )
+    }
+
+    /**
+     * Checks whether a positive standoff describes a real mechanical cover
+     * stack instead of an embedded model source-origin air gap.
+     * @param {object | null | undefined} componentBody Component-body row.
+     * @param {object | null} matchedComponent Matched owner component.
+     * @returns {boolean}
+     */
+    static #hasAuthoredCoverStackStandoff(componentBody, matchedComponent) {
+        if (!matchedComponent || !componentBody?.embedded) {
+            return false
+        }
+
+        const standoff = Number(componentBody?.standoffHeightMil)
+        const overallHeight = Number(componentBody?.overallHeightMil)
+        if (
+            !Number.isFinite(standoff) ||
+            !Number.isFinite(overallHeight) ||
+            standoff <= 0 ||
+            overallHeight <= standoff
+        ) {
+            return false
+        }
+
+        const identityText = [
+            componentBody?.identifier,
+            componentBody?.name,
+            matchedComponent?.pattern,
+            matchedComponent?.source
+        ].join(' ')
+
+        return PcbScene3dBuilder.#AUTHORED_COVER_STACK_IDENTITY_PATTERN.test(
+            identityText
+        )
+    }
+
+    /**
+     * Checks whether one body row came from shape-based 3D body metadata.
+     * @param {object | null | undefined} componentBody Component-body row.
+     * @returns {boolean}
+     */
+    static #isShapeBasedComponentBody(componentBody) {
+        return (
+            String(componentBody?.sourceStream || '').includes(
+                'ShapeBasedComponentBodies'
+            ) ||
+            Boolean(componentBody?.staticGeometry) ||
+            Boolean(componentBody?.modelTypeName)
+        )
     }
 
     /**
@@ -526,7 +770,8 @@ export class PcbScene3dBuilder {
 
         componentBodies.forEach((componentBody, bodyIndex) => {
             if (
-                !PcbScene3dBuilder.#isResolvableComponentBody(
+                !PcbScene3dBuilder.#isMatchableComponentBody(
+                    componentBody,
                     resolvedBodyModels,
                     bodyIndex
                 )
@@ -613,7 +858,8 @@ export class PcbScene3dBuilder {
         const groupedBodyIndexes = new Map()
         componentBodies.forEach((componentBody, bodyIndex) => {
             if (
-                !PcbScene3dBuilder.#isResolvableComponentBody(
+                !PcbScene3dBuilder.#isMatchableComponentBody(
+                    componentBody,
                     resolvedBodyModels,
                     bodyIndex
                 )
@@ -682,9 +928,115 @@ export class PcbScene3dBuilder {
             })
         })
 
+        PcbScene3dBuilder.#assignStaticShieldFrameBodyMatches(
+            matches,
+            componentBodies,
+            components
+        )
+
         return matches
     }
 
+    /**
+     * Assigns static shield-frame sub-bodies to their nearest shield-frame
+     * component owner. These bodies are renderable without external models, so
+     * the external-model ownership pass does not see them.
+     * @param {({ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string } | null)[]} matches Mutable match array.
+     * @param {{ identifier?: string, name?: string, layer?: string, positionMil?: { x?: number, y?: number }, staticGeometry?: object }[]} componentBodies Component bodies.
+     * @param {{ designator: string, x: number, y: number, layer?: string, pattern?: string, source?: string, modelPath?: string }[]} components PCB components.
+     */
+    static #assignStaticShieldFrameBodyMatches(
+        matches,
+        componentBodies,
+        components
+    ) {
+        componentBodies.forEach((componentBody, bodyIndex) => {
+            if (
+                matches[bodyIndex] ||
+                !PcbScene3dBuilder.#isStaticShieldFrameBody(componentBody)
+            ) {
+                return
+            }
+
+            const owner = components
+                .filter(
+                    (component) =>
+                        PcbScene3dBuilder.#isMechanicalShieldFrameOwner(
+                            component
+                        ) &&
+                        PcbScene3dBuilder.#isBodyComponentSideCompatible(
+                            componentBody,
+                            component
+                        )
+                )
+                .map((component) => ({
+                    component,
+                    affinityScore:
+                        PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                            componentBody,
+                            component
+                        ),
+                    distance:
+                        PcbScene3dBuilder.#distanceBetweenBodyAndComponent(
+                            componentBody,
+                            component
+                        )
+                }))
+                .filter(
+                    ({ distance }) =>
+                        Number.isFinite(distance) &&
+                        distance <=
+                            PcbScene3dBuilder
+                                .#MECHANICAL_SHIELD_FRAME_OWNER_RADIUS_MIL
+                )
+                .sort(
+                    (left, right) =>
+                        right.affinityScore - left.affinityScore ||
+                        left.distance - right.distance
+                )[0]?.component
+
+            if (owner) {
+                matches[bodyIndex] = owner
+            }
+        })
+    }
+
+    /**
+     * Checks whether one component is a mechanical shield-frame owner.
+     * @param {{ pattern?: string, source?: string, description?: string, parameters?: Record<string, unknown>, provenance?: Record<string, unknown> }} component Source component.
+     * @returns {boolean}
+     */
+    static #isMechanicalShieldFrameOwner(component) {
+        return PcbScene3dBuilder.#MECHANICAL_SHIELD_FRAME_OWNER_PATTERN.test(
+            PcbScene3dBuilder.#componentIdentityText(component)
+        )
+    }
+
+    /**
+     * Checks whether one static body is a shield-frame sub-body.
+     * @param {{ identifier?: string, name?: string, staticGeometry?: object }} componentBody Component body.
+     * @returns {boolean}
+     */
+    static #isStaticShieldFrameBody(componentBody) {
+        const geometry = componentBody?.staticGeometry || {}
+        const completeGeometry =
+            geometry.status === 'complete' &&
+            Array.isArray(geometry.verticesMil) &&
+            geometry.verticesMil.length >= 3
+        const recoverableGeometry =
+            geometry.status !== 'complete' && Number(geometry.heightMil) > 0
+
+        return (
+            String(geometry.kind || '').toLowerCase() === 'extruded-polygon' &&
+            (completeGeometry || recoverableGeometry) &&
+            PcbScene3dBuilder.#MECHANICAL_SHIELD_FRAME_BODY_PATTERN.test(
+                [componentBody?.identifier, componentBody?.name]
+                    .map((value) => String(value || ''))
+                    .join(' ')
+            )
+        )
+    }
+
     /**
      * Builds reusable identity statistics for body/component matching.
      * @param {{ modelId?: string, name?: string, identifier?: string }[]} componentBodies
@@ -703,7 +1055,8 @@ export class PcbScene3dBuilder {
 
         componentBodies.forEach((componentBody, bodyIndex) => {
             if (
-                !PcbScene3dBuilder.#isResolvableComponentBody(
+                !PcbScene3dBuilder.#isMatchableComponentBody(
+                    componentBody,
                     resolvedBodyModels,
                     bodyIndex
                 )
@@ -740,6 +1093,29 @@ export class PcbScene3dBuilder {
         return { bodyGroupCounts, candidateComponentCounts }
     }
 
+    /**
+     * Returns true when one body row can participate in owner matching.
+     * @param {object | null | undefined} componentBody Component body row.
+     * @param {unknown[]} resolvedBodyModels Resolved body-model entries.
+     * @param {number} bodyIndex Body index.
+     * @returns {boolean}
+     */
+    static #isMatchableComponentBody(
+        componentBody,
+        resolvedBodyModels,
+        bodyIndex
+    ) {
+        return (
+            PcbScene3dBuilder.#isResolvableComponentBody(
+                resolvedBodyModels,
+                bodyIndex
+            ) ||
+            PcbScene3dBuilder.#isAnonymousLayerlessStaticBodyGeometry(
+                componentBody
+            )
+        )
+    }
+
     /**
      * Returns true when one body row can produce a renderable external model.
      * @param {unknown[]} resolvedBodyModels Resolved body-model entries.
@@ -754,6 +1130,26 @@ export class PcbScene3dBuilder {
         )
     }
 
+    /**
+     * Checks whether one anonymous layerless body row already carries
+     * renderable static geometry.
+     * @param {object | null | undefined} componentBody Component body row.
+     * @returns {boolean}
+     */
+    static #isAnonymousLayerlessStaticBodyGeometry(componentBody) {
+        const identityText = [componentBody?.identifier, componentBody?.name]
+            .map((value) => String(value || '').trim())
+            .join('')
+
+        return (
+            identityText.length === 0 &&
+            String(componentBody?.layer || '').trim().length === 0 &&
+            Boolean(componentBody?.staticGeometry) &&
+            String(componentBody.staticGeometry?.status || '').toLowerCase() ===
+                'complete'
+        )
+    }
+
     /**
      * Returns true when the body/component anchors are close enough to be
      * considered an explicit placement match.
@@ -923,6 +1319,154 @@ export class PcbScene3dBuilder {
         )
     }
 
+    /**
+     * Checks whether a package-like shape body is an authored timing-stack
+     * sub-body that should stay represented by its carrier static geometry.
+     * @param {object} componentBody Component-body record.
+     * @param {object | null} matchedComponent Matched component.
+     * @param {{ designator?: string, x?: number, y?: number, pattern?: string, source?: string, description?: string, provenance?: object, parameters?: object }[]} components PCB components.
+     * @returns {boolean}
+     */
+    static #isPositiveTimingStackPackageBody(
+        componentBody,
+        matchedComponent,
+        components
+    ) {
+        const standoff = Number(componentBody?.standoffHeightMil)
+        const hasTimingOwner = matchedComponent
+            ? PcbScene3dBuilder.#isTimingStackComponent(matchedComponent)
+            : PcbScene3dBuilder.#hasNearbyTimingStackOwner(
+                  componentBody,
+                  components
+              )
+        const hasLocalComponentOwner =
+            PcbScene3dBuilder.#hasNearbyNonTimingPackageOwner(
+                componentBody,
+                components
+            )
+
+        return (
+            PcbScene3dBuilder.#isShapeBasedComponentBody(componentBody) &&
+            componentBody?.embedded === true &&
+            Number.isFinite(standoff) &&
+            standoff > 0 &&
+            PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            !PcbScene3dBuilder.#isTimingStackBodyIdentity(componentBody) &&
+            !PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody) &&
+            hasTimingOwner &&
+            !hasLocalComponentOwner
+        )
+    }
+
+    /**
+     * Checks whether a shape-based sub-body is the actual timing package
+     * rather than a passive support part inside the timing stack.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #isTimingStackBodyIdentity(componentBody) {
+        return PcbScene3dBuilder.#TIMING_STACK_COMPONENT_PATTERN.test(
+            [componentBody?.identifier, componentBody?.name]
+                .map((value) => String(value || ''))
+                .join(' ')
+        )
+    }
+
+    /**
+     * Checks whether one package-like body is the authored timing package for
+     * a timing-stack component.
+     * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
+     * @param {object} component PCB component.
+     * @returns {boolean}
+     */
+    static #isTimingStackBodyComponentPair(componentBody, component) {
+        return (
+            PcbScene3dBuilder.#isTimingStackBodyIdentity(componentBody) &&
+            PcbScene3dBuilder.#isTimingStackComponent(component)
+        )
+    }
+
+    /**
+     * Checks whether a positive package body has its own nearby non-timing
+     * component and should not be treated as an unowned timing-stack detail.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component-body record.
+     * @param {object[]} components PCB components.
+     * @returns {boolean}
+     */
+    static #hasNearbyNonTimingPackageOwner(componentBody, components) {
+        return (Array.isArray(components) ? components : []).some(
+            (component) =>
+                !PcbScene3dBuilder.#isTimingStackComponent(component) &&
+                PcbScene3dBuilder.#distanceBetweenBodyAndComponent(
+                    componentBody,
+                    component
+                ) <= PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL &&
+                PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
+                    componentBody,
+                    component
+                ) > 0
+        )
+    }
+
+    /**
+     * Checks whether an unmatched body sits inside a timing-package stack.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component-body record.
+     * @param {object[]} components PCB components.
+     * @returns {boolean}
+     */
+    static #hasNearbyTimingStackOwner(componentBody, components) {
+        return (Array.isArray(components) ? components : []).some(
+            (component) =>
+                PcbScene3dBuilder.#isTimingStackComponent(component) &&
+                PcbScene3dBuilder.#distanceBetweenBodyAndComponent(
+                    componentBody,
+                    component
+                ) <= PcbScene3dBuilder.#TIMING_STACK_BODY_RADIUS_MIL
+        )
+    }
+
+    /**
+     * Checks whether one component is a timing-package stack owner.
+     * @param {object} component PCB component.
+     * @returns {boolean}
+     */
+    static #isTimingStackComponent(component) {
+        const designator = String(component?.designator || '').trim()
+        if (
+            PcbScene3dBuilder.#TIMING_STACK_DESIGNATOR_PATTERN.test(designator)
+        ) {
+            return true
+        }
+
+        return PcbScene3dBuilder.#TIMING_STACK_COMPONENT_PATTERN.test(
+            [
+                component?.pattern,
+                component?.source,
+                component?.description,
+                component?.provenance?.footprintDescription,
+                ...Object.values(component?.parameters || {})
+            ]
+                .map((value) => String(value || ''))
+                .join(' ')
+        )
+    }
+
+    /**
+     * Checks whether a body already has complete static geometry and should
+     * not also be emitted as an external model placement.
+     * @param {{ embedded?: boolean, staticGeometry?: { status?: string } }} componentBody Component-body record.
+     * @returns {boolean}
+     */
+    static #shouldRenderStaticGeometryOnly(componentBody) {
+        return (
+            PcbScene3dBuilder.#isShapeBasedComponentBody(componentBody) &&
+            !componentBody?.embedded &&
+            String(
+                componentBody?.staticGeometry?.status || ''
+            ).toLowerCase() === 'complete'
+        )
+    }
+
     /**
      * Checks whether a precise body/component pair is a package-family mismatch.
      * @param {{ name?: string, identifier?: string }} componentBody Component-body record.
@@ -939,6 +1483,10 @@ export class PcbScene3dBuilder {
             Number(distanceMil || 0) <=
                 PcbScene3dBuilder.#EXACT_BODY_MISMATCH_TOLERANCE_MIL &&
             PcbScene3dBuilder.#isComponentPackageBody(componentBody) &&
+            !PcbScene3dBuilder.#isTimingStackBodyComponentPair(
+                componentBody,
+                component
+            ) &&
             !PcbScene3dBuilder.#isAuthoredBodyIdentity(componentBody) &&
             PcbScene3dPlacementSideResolver.scoreBodyComponentAffinity(
                 componentBody,
@@ -1717,11 +2265,16 @@ export class PcbScene3dBuilder {
 
     /**
      * Resolves the owned or nearby pad-span box around one component.
-     * @param {{ x: number, y: number, componentIndex?: number, layer?: string }} component
+     * @param {{ x: number, y: number, componentIndex?: number, layer?: string, rotation?: number }} component
      * @param {{ x: number, y: number, sizeTopX?: number, sizeTopY?: number, sizeMidX?: number, sizeMidY?: number, sizeBottomX?: number, sizeBottomY?: number }[]} pads
+     * @param {number} [rotationDeg] Body-local rotation used for span measurement.
      * @returns {{ width: number, depth: number }}
      */
-    static #resolvePadSpan(component, pads) {
+    static #resolvePadSpan(
+        component,
+        pads,
+        rotationDeg = Number(component?.rotation || 0)
+    ) {
         const componentPads = PcbScene3dBuilder.#componentPads(component, pads)
         const nearbyPads = pads.filter((pad) =>
             PcbScene3dBuilder.#isPadNearComponent(component, pad)
@@ -1735,13 +2288,27 @@ export class PcbScene3dBuilder {
         const mountSide = PcbScene3dBuilder.#resolveMountSide(component)
         return (
             PcbScene3dPadLocalSpanResolver.resolve(
-                component,
+                { ...component, rotation: rotationDeg },
                 spanPads,
                 mountSide
             ) || { width: 0, depth: 0 }
         )
     }
 
+    /**
+     * Resolves the visible procedural component rotation.
+     * @param {{ componentIndex?: number, rotation?: number }} component PCB component.
+     * @param {object[]} pads PCB pads.
+     * @param {string} mountSide Component mount side.
+     * @returns {number}
+     */
+    static #resolveComponentRotation(component, pads, mountSide) {
+        return (
+            PcbScene3dPadYawResolver.resolve(component, pads, mountSide) ??
+            Number(component?.rotation || 0)
+        )
+    }
+
     /**
      * Resolves pads explicitly owned by one component, preferring pads on the
      * mounted surface when paste-mask side metadata is available.