pcb-scene3d-viewer 1.1.49 → 1.2.0

package/src/PcbScene3dCircuitJsonGeometry.mjs

@@ -23,18 +23,68 @@ export class PcbScene3dCircuitJsonGeometry {
      * @returns {object}
      */
     static buildBoard(index, options = {}) {
-        const explicitBoardElement =
-            index.elementsByType.get('pcb_panel')?.[0] ||
-            index.elementsByType.get('pcb_board')?.[0]
-        const boardElement =
-            explicitBoardElement ||
-            PcbScene3dCircuitJsonGeometry.#fauxBoardElement(index, options) ||
-            {}
-        const widthMil = CircuitJsonUnits.mmToMil(
+        const panelElements = index.elementsByType.get('pcb_panel') || []
+        const boardElements = index.elementsByType.get('pcb_board') || []
+        const explicitElements = panelElements.length
+            ? panelElements
+            : boardElements
+        const elements = explicitElements.length
+            ? explicitElements
+            : [
+                  PcbScene3dCircuitJsonGeometry.#fauxBoardElement(
+                      index,
+                      options
+                  ) || {}
+              ]
+        const sourceContours = elements.map((element) =>
+            PcbScene3dCircuitJsonGeometry.#buildBoardContour(
+                index,
+                element,
+                options
+            )
+        )
+        const bounds =
+            PcbScene3dCircuitJsonGeometry.#contourBounds(sourceContours)
+        const centerX = (bounds.minX + bounds.maxX) / 2
+        const centerY = (bounds.minY + bounds.maxY) / 2
+        const contours = sourceContours.map((contour) => ({
+            ...contour,
+            centerX,
+            centerY
+        }))
+        const primary = contours[0]
+
+        return {
+            widthMil: bounds.maxX - bounds.minX,
+            heightMil: bounds.maxY - bounds.minY,
+            thicknessMil: Math.max(
+                ...contours.map((contour) => contour.thicknessMil)
+            ),
+            minX: bounds.minX,
+            minY: bounds.minY,
+            centerX,
+            centerY,
+            segments: primary.segments,
+            cutouts: PcbScene3dCircuitJsonGeometry.#uniqueCutouts(contours),
+            contours,
+            surfaceColor: null,
+            edgeColor: null
+        }
+    }
+
+    /**
+     * Builds one independently renderable board or panel contour.
+     * @param {{ elementsByType: Map<string, object[]> }} index CircuitJSON index.
+     * @param {object} boardElement Board or panel element.
+     * @param {{ boardDrillQuality?: string }} options Adapter options.
+     * @returns {object}
+     */
+    static #buildBoardContour(index, boardElement, options) {
+        const declaredWidthMil = CircuitJsonUnits.mmToMil(
             boardElement.width,
             DEFAULT_BOARD_WIDTH_MM
         )
-        const heightMil = CircuitJsonUnits.mmToMil(
+        const declaredHeightMil = CircuitJsonUnits.mmToMil(
             boardElement.height,
             DEFAULT_BOARD_HEIGHT_MM
         )
@@ -43,24 +93,35 @@ export class PcbScene3dCircuitJsonGeometry {
             DEFAULT_BOARD_THICKNESS_MM
         )
         const center = CircuitJsonUnits.pointMmToMil(boardElement.center || {})
-        const minX = center.x - widthMil / 2
-        const minY = center.y - heightMil / 2
+        const fallback = {
+            minX: center.x - declaredWidthMil / 2,
+            minY: center.y - declaredHeightMil / 2,
+            widthMil: declaredWidthMil,
+            heightMil: declaredHeightMil
+        }
         const segments = PcbScene3dCircuitJsonGeometry.#buildBoardSegments(
             boardElement,
-            {
-                minX,
-                minY,
-                widthMil,
-                heightMil
-            }
+            fallback
+        )
+        const bounds = PcbScene3dCircuitJsonGeometry.#segmentBounds(
+            segments,
+            fallback
         )
 
         return {
-            widthMil,
-            heightMil,
+            sourceId: String(
+                boardElement?.pcb_panel_id ||
+                    boardElement?.panel_id ||
+                    boardElement?.pcb_board_id ||
+                    boardElement?.board_id ||
+                    ''
+            ),
+            sourceType: String(boardElement?.type || 'pcb_board'),
+            widthMil: bounds.maxX - bounds.minX,
+            heightMil: bounds.maxY - bounds.minY,
             thicknessMil,
-            minX,
-            minY,
+            minX: bounds.minX,
+            minY: bounds.minY,
             centerX: center.x,
             centerY: center.y,
             segments,
@@ -74,6 +135,78 @@ export class PcbScene3dCircuitJsonGeometry {
         }
     }
 
+    /**
+     * Resolves finite bounds around one contour's ordered segments.
+     * @param {object[]} segments Board segments.
+     * @param {{ minX: number, minY: number, widthMil: number, heightMil: number }} fallback Rectangle fallback.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number }}
+     */
+    static #segmentBounds(segments, fallback) {
+        const points = segments.flatMap((segment) => [
+            { x: Number(segment?.x1), y: Number(segment?.y1) },
+            { x: Number(segment?.x2), y: Number(segment?.y2) }
+        ])
+        const finite = points.filter((point) =>
+            Number.isFinite(point.x + point.y)
+        )
+        if (!finite.length) {
+            return {
+                minX: fallback.minX,
+                minY: fallback.minY,
+                maxX: fallback.minX + fallback.widthMil,
+                maxY: fallback.minY + fallback.heightMil
+            }
+        }
+
+        return finite.reduce(
+            (bounds, point) => ({
+                minX: Math.min(bounds.minX, point.x),
+                minY: Math.min(bounds.minY, point.y),
+                maxX: Math.max(bounds.maxX, point.x),
+                maxY: Math.max(bounds.maxY, point.y)
+            }),
+            { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity }
+        )
+    }
+
+    /**
+     * Resolves aggregate bounds around every physical contour.
+     * @param {object[]} contours Board contours.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number }}
+     */
+    static #contourBounds(contours) {
+        return contours.reduce(
+            (bounds, contour) => ({
+                minX: Math.min(bounds.minX, contour.minX),
+                minY: Math.min(bounds.minY, contour.minY),
+                maxX: Math.max(bounds.maxX, contour.minX + contour.widthMil),
+                maxY: Math.max(bounds.maxY, contour.minY + contour.heightMil)
+            }),
+            { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity }
+        )
+    }
+
+    /**
+     * Flattens contour cutouts without duplicating global cutout rows.
+     * @param {object[]} contours Board contours.
+     * @returns {object[]}
+     */
+    static #uniqueCutouts(contours) {
+        const seen = new Set()
+        return contours
+            .flatMap((contour) => contour.cutouts || [])
+            .filter((cutout) => {
+                const key =
+                    cutout.sourceId ||
+                    JSON.stringify(
+                        (cutout.points || []).map((point) => [point.x, point.y])
+                    )
+                if (seen.has(key)) return false
+                seen.add(key)
+                return true
+            })
+    }
+
     /**
      * Builds a generated board element around component bounds when requested.
      * @param {{ elementsByType: Map<string, object[]> }} index CircuitJSON index.
@@ -175,43 +308,61 @@ export class PcbScene3dCircuitJsonGeometry {
     /**
      * Resolves drill opening metadata from circular, pill, and offset fields.
      * @param {object} hole CircuitJSON hole-like element.
-     * @returns {{ center: { x: number, y: number }, diameter: number, slotLength: number, rotationDeg: number }}
+     * @param {object | null} [primitive] Shared normalized hole primitive.
+     * @returns {{ center: { x: number, y: number }, diameter: number, width: number, height: number, shape: 'circle' | 'pill' | 'rect', slotLength: number, rotationDeg: number }}
      */
-    static holeDrillSpec(hole) {
+    static holeDrillSpec(hole, primitive = null) {
         const center = CircuitJsonUnits.pointMmToMil({
             x: Number(hole?.x || 0) + Number(hole?.hole_offset_x || 0),
             y: Number(hole?.y || 0) + Number(hole?.hole_offset_y || 0)
         })
         const width = CircuitJsonUnits.mmToMil(
-            hole?.hole_width || hole?.hole_diameter,
+            primitive?.holeWidth || hole?.hole_width || hole?.hole_diameter,
             0
         )
         const height = CircuitJsonUnits.mmToMil(
-            hole?.hole_height || hole?.hole_diameter || hole?.hole_width,
+            primitive?.holeHeight ||
+                hole?.hole_height ||
+                hole?.hole_diameter ||
+                hole?.hole_width,
             0
         )
         const diameter = PcbScene3dCircuitJsonGeometry.#firstPositive([
-            hole?.hole_diameter
-                ? CircuitJsonUnits.mmToMil(hole.hole_diameter, 0)
-                : 0,
+            primitive?.holeDiameter
+                ? CircuitJsonUnits.mmToMil(primitive.holeDiameter, 0)
+                : hole?.hole_diameter
+                  ? CircuitJsonUnits.mmToMil(hole.hole_diameter, 0)
+                  : 0,
             Math.min(width || Infinity, height || Infinity),
             width,
             height
         ])
+        const shapeText = String(
+            primitive?.holeShape || hole?.hole_shape || ''
+        ).toLowerCase()
+        const isRect =
+            shapeText.includes('rect') || shapeText.includes('square')
         const isPill =
-            String(hole?.hole_shape || '')
-                .toLowerCase()
-                .includes('pill') ||
-            (width > 0 && height > 0 && Math.abs(width - height) > 0.001)
+            !isRect &&
+            (shapeText.includes('pill') ||
+                shapeText.includes('oval') ||
+                (width > 0 && height > 0 && Math.abs(width - height) > 0.001))
+        const shape = isRect ? 'rect' : isPill ? 'pill' : 'circle'
         const slotLength = isPill ? Math.max(width, height, diameter) : 0
         const axisRotation = isPill && height > width ? 90 : 0
 
         return {
             center,
             diameter,
+            width: width || diameter,
+            height: height || diameter,
+            shape,
             slotLength: slotLength > diameter ? slotLength : 0,
             rotationDeg:
-                PcbScene3dCircuitJsonGeometry.#rotationDeg(hole) + axisRotation
+                Number(
+                    primitive?.holeRotation ??
+                        PcbScene3dCircuitJsonGeometry.#rotationDeg(hole)
+                ) + axisRotation
         }
     }
 

package/src/PcbScene3dCircuitJsonInput.mjs

@@ -0,0 +1,132 @@
+import { CircuitJsonDocumentContext } from 'circuitjson-toolkit'
+
+/**
+ * Performs non-mutating CircuitJSON input detection for viewer routing.
+ */
+export class PcbScene3dCircuitJsonInput {
+    /**
+     * Returns true for a raw model, canonical document, or prepared context.
+     * @param {unknown} value Candidate input.
+     * @returns {boolean}
+     */
+    static isModel(value) {
+        try {
+            if (value instanceof CircuitJsonDocumentContext) return true
+            const model = PcbScene3dCircuitJsonInput.#validationModel(value)
+            return Boolean(
+                model && PcbScene3dCircuitJsonInput.#hasElementRows(model)
+            )
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Checks the descriptor-safe structural boundary needed before shared
+     * normalization and validation prepare the model.
+     * @param {object[]} model Dense model candidate.
+     * @returns {boolean} Whether every row exposes an own string type.
+     */
+    static #hasElementRows(model) {
+        for (let index = 0; index < model.length; index += 1) {
+            const element = model[index]
+            const type = PcbScene3dCircuitJsonInput.#ownData(element, 'type')
+            if (typeof type !== 'string' || !type.trim()) return false
+        }
+        return true
+    }
+
+    /**
+     * Returns a non-mutating model view for predicate validation.
+     * @param {unknown} value Model or canonical document candidate.
+     * @returns {object[] | null}
+     */
+    static #validationModel(value) {
+        if (Array.isArray(value)) {
+            return PcbScene3dCircuitJsonInput.#plainModel(value)
+        }
+        if (
+            PcbScene3dCircuitJsonInput.#ownData(value, 'schema') !==
+            'ecad-toolkit.document.v1'
+        ) {
+            return null
+        }
+        const model = PcbScene3dCircuitJsonInput.#ownData(value, 'model')
+        return Array.isArray(model)
+            ? PcbScene3dCircuitJsonInput.#plainModel(model)
+            : null
+    }
+
+    /**
+     * Removes safe legacy array metadata without freezing caller values.
+     * @param {object[]} model CircuitJSON model candidate.
+     * @returns {object[] | null}
+     */
+    static #plainModel(model) {
+        let prototype
+        let descriptors
+        try {
+            prototype = Object.getPrototypeOf(model)
+            descriptors = Object.getOwnPropertyDescriptors(model)
+        } catch {
+            return null
+        }
+        const length = descriptors.length?.value
+        if (
+            prototype !== Array.prototype ||
+            !Number.isSafeInteger(length) ||
+            length < 0
+        ) {
+            return null
+        }
+
+        const keys = Reflect.ownKeys(descriptors)
+        const plain = keys.length === length + 1 ? null : new Array(length)
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = descriptors[String(index)]
+            if (
+                !descriptor ||
+                !Object.hasOwn(descriptor, 'value') ||
+                descriptor.enumerable !== true
+            ) {
+                return null
+            }
+            if (plain) plain[index] = descriptor.value
+        }
+        for (const key of keys) {
+            if (key === 'length') continue
+            const index =
+                typeof key === 'string' && /^(?:0|[1-9]\d*)$/u.test(key)
+                    ? Number(key)
+                    : -1
+            if (Number.isSafeInteger(index) && index < length) continue
+            const descriptor = descriptors[key]
+            if (
+                typeof key !== 'string' ||
+                !Object.hasOwn(descriptor, 'value') ||
+                descriptor.enumerable !== true
+            ) {
+                return null
+            }
+        }
+        return plain || model
+    }
+
+    /**
+     * Reads one own data property without invoking caller accessors.
+     * @param {unknown} value Record candidate.
+     * @param {string} name Property name.
+     * @returns {unknown} Own data value or undefined.
+     */
+    static #ownData(value, name) {
+        if (!value || typeof value !== 'object') return undefined
+        try {
+            const descriptor = Object.getOwnPropertyDescriptor(value, name)
+            return descriptor && Object.hasOwn(descriptor, 'value')
+                ? descriptor.value
+                : undefined
+        } catch {
+            return undefined
+        }
+    }
+}

package/src/PcbScene3dCircuitJsonModelAsset.mjs

@@ -0,0 +1,40 @@
+/**
+ * Normalizes canonical CircuitJSON CAD model asset references.
+ */
+export class PcbScene3dCircuitJsonModelAsset {
+    /**
+     * Resolves one viewer-supported canonical model asset reference.
+     * @param {unknown} asset Model asset candidate.
+     * @returns {{ format: string, sourceUrl: string } | null}
+     */
+    static reference(asset) {
+        if (!asset || typeof asset !== 'object') return null
+        const sourceUrl = String(
+            asset.project_relative_path || asset.url || ''
+        ).trim()
+        const format = PcbScene3dCircuitJsonModelAsset.#format(asset, sourceUrl)
+        return sourceUrl && format ? { format, sourceUrl } : null
+    }
+
+    /**
+     * Resolves a supported CAD format from canonical and retained metadata.
+     * @param {object} asset Model asset metadata.
+     * @param {string} sourceUrl Canonical model asset path.
+     * @returns {string}
+     */
+    static #format(asset, sourceUrl) {
+        const text = [asset.format, asset.mimetype, sourceUrl, asset.url]
+            .map(String)
+            .join(' ')
+            .toLowerCase()
+        if (/\bglb\b|\.glb(?:[?#]|$)/u.test(text)) return 'glb'
+        if (/\bgltf\b|\.gltf(?:[?#]|$)/u.test(text)) return 'gltf'
+        if (/\b3mf\b|\.3mf(?:[?#]|$)/u.test(text)) return '3mf'
+        if (/\bobj\b|\.obj(?:[?#]|$)/u.test(text)) return 'obj'
+        if (/\bstl\b|\.stl(?:[?#]|$)/u.test(text)) return 'stl'
+        if (/\bwrl\b|vrml|\.wrl(?:[?#]|$)/u.test(text)) return 'wrl'
+        return /step|stp|\.step(?:[?#]|$)|\.stp(?:[?#]|$)/u.test(text)
+            ? 'step'
+            : ''
+    }
+}

package/src/PcbScene3dController.mjs

@@ -15,25 +15,19 @@ import { PcbScene3dText } from './PcbScene3dText.mjs'
 export class PcbScene3dController {
     /** @type {HTMLElement | null} */
     #viewportNode
-
     /** @type {any} */
     #documentModel
-
     /** @type {HTMLElement | null} */
     #rootNode
-
     /** @type {HTMLElement | null} */
     #diagnosticsNode
-
     /** @type {HTMLElement | null} */
     #selectionNode
-
     /** @type {HTMLElement | null} */
     #adjustmentHostNode
 
     /** @type {PcbScene3dAdjustmentControlBinder | null} */
     #adjustmentControls
-
     /** @type {PcbScene3dSelectionVisibilityBinder | null} */
     #visibilityControls
     /** @type {Array<{ node: EventTarget, type: string, listener: (event: any) => void }>} */
@@ -41,19 +35,16 @@ export class PcbScene3dController {
 
     /** @type {Map<string, { component: any | null, externalPlacement: any | null, staticBodyPlacement: any | null }>} */
     #selectionIndex
-
     /** @type {Map<string, { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }>} */
     #componentAdjustments
-
     /** @type {string} */
     #selectedComponentKey
-
     /** @type {any | null} */
     #runtime
-
     /** @type {any | null} */
     #sceneDescription
-
+    /** @type {object | undefined} */
+    #modelLoaderOptions
     /** @type {{ prepareScene?: (documentModel: any, sessionAssets?: any[]) => Promise<any>, dispose?: () => void } | null} */
     #scenePrepClient
 
@@ -87,7 +78,7 @@ export class PcbScene3dController {
     /**
      * @param {HTMLElement} viewportNode
      * @param {any} documentModel
-     * @param {{ rootNode?: HTMLElement | null, documentId?: string, onComponentSelectionChange?: ((change: { documentId: string, componentKey: string, source?: string }) => void) | null, sessionAssets?: any[], autoSearchMissingModels?: boolean, circuitJson?: object[], sceneDescription?: any, buildScene?: (documentModel: any, options: { modelRegistry: any }) => any, createModelRegistry?: (documentModel: any, sessionAssets: any[]) => any, createRuntime?: (viewportNode: HTMLElement, sceneDescription: any, hooks: { setDiagnostics: (messages: string[]) => void, setSelection: (selection: any | null) => void, translate?: ((key: string) => string) | null }) => { setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, dispose?: () => void, whenReady?: () => Promise<void> | void }, scenePrepClient?: { prepareScene?: (documentModel: any, sessionAssets?: any[]) => Promise<any>, dispose?: () => void } | null, exportArchive?: (options: { archiveBaseName?: string, sceneDescription?: any }) => Promise<{ archiveName: string, archiveBytes: Uint8Array, exportedEntries: any[], skippedEntries: any[] }>, downloadArchive?: (archiveName: string, archiveBytes: Uint8Array) => Promise<void> | void, renderAdjustmentControlsInSelection?: boolean, setLoadingVisible?: (visible: boolean) => void, translate?: ((key: string) => string) | null }} [options]
+     * @param {{ rootNode?: HTMLElement | null, documentId?: string, onComponentSelectionChange?: ((change: { documentId: string, componentKey: string, source?: string }) => void) | null, sessionAssets?: any[], autoSearchMissingModels?: boolean, circuitJson?: object[], sceneDescription?: any, modelLoaderOptions?: object, buildScene?: (documentModel: any, options: { modelRegistry: any }) => any, createModelRegistry?: (documentModel: any, sessionAssets: any[]) => any, createRuntime?: (viewportNode: HTMLElement, sceneDescription: any, hooks: { setDiagnostics: (messages: string[]) => void, setSelection: (selection: any | null) => void, translate?: ((key: string) => string) | null, modelLoaderOptions?: object }) => { setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, dispose?: () => void, whenReady?: () => Promise<void> | void }, scenePrepClient?: { prepareScene?: (documentModel: any, sessionAssets?: any[]) => Promise<any>, dispose?: () => void } | null, exportArchive?: (options: { archiveBaseName?: string, sceneDescription?: any }) => Promise<{ archiveName: string, archiveBytes: Uint8Array, exportedEntries: any[], skippedEntries: any[] }>, downloadArchive?: (archiveName: string, archiveBytes: Uint8Array) => Promise<void> | void, renderAdjustmentControlsInSelection?: boolean, setLoadingVisible?: (visible: boolean) => void, translate?: ((key: string) => string) | null }} [options]
      */
     constructor(viewportNode, documentModel, options = {}) {
         this.#viewportNode = viewportNode
@@ -107,6 +98,7 @@ export class PcbScene3dController {
         this.#listeners = []
         this.#scenePrepClient = options.scenePrepClient || null
         this.#sceneDescription = null
+        this.#modelLoaderOptions = options.modelLoaderOptions
         this.#exportArchive =
             options.exportArchive ||
             ((exportOptions) =>
@@ -188,15 +180,6 @@ export class PcbScene3dController {
         this.#visibilityControls.bindSelectionNode(this.#selectionNode)
         this.#setSelection(null)
         this.#setLoadingVisible(true)
-        const circuitJsonModel = PcbScene3dController.#resolveCircuitJsonModel(
-            options,
-            this.#documentModel
-        )
-        if (circuitJsonModel) {
-            this.#initializePreparedScene(circuitJsonModel, options)
-            return
-        }
-
         if (options.sceneDescription) {
             this.#initializePreparedScene(options.sceneDescription, options)
             return
@@ -207,6 +190,15 @@ export class PcbScene3dController {
             return
         }
 
+        const circuitJsonModel = PcbScene3dController.#resolveCircuitJsonModel(
+            options,
+            this.#documentModel
+        )
+        if (circuitJsonModel) {
+            this.#initializePreparedScene(circuitJsonModel, options)
+            return
+        }
+
         this.#initializeSceneSync(options)
     }
 
@@ -427,6 +419,12 @@ export class PcbScene3dController {
      * @returns {any}
      */
     #prepareSceneDescriptionSync(options) {
+        const circuitJsonModel = PcbScene3dController.#resolveCircuitJsonModel(
+            options,
+            this.#documentModel
+        )
+        if (circuitJsonModel) return circuitJsonModel
+
         const buildScene = options.buildScene
         if (typeof buildScene !== 'function') {
             throw new Error(
@@ -450,12 +448,14 @@ export class PcbScene3dController {
     /**
      * Mounts the runtime for one prepared scene description.
      * @param {any} sceneDescription
-     * @param {{ createRuntime?: (viewportNode: HTMLElement, sceneDescription: any, hooks: { setDiagnostics: (messages: string[]) => void, setSelection: (selection: any | null) => void, translate?: ((key: string) => string) | null }) => { setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, dispose?: () => void, whenReady?: () => Promise<void> | void } }} options
+     * @param {{ modelLoaderOptions?: object, createRuntime?: (viewportNode: HTMLElement, sceneDescription: any, hooks: { setDiagnostics: (messages: string[]) => void, setSelection: (selection: any | null) => void, translate?: ((key: string) => string) | null, modelLoaderOptions?: object }) => { setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, dispose?: () => void, whenReady?: () => Promise<void> | void } }} options
      * @returns {void}
      */
     #mountScene(sceneDescription, options) {
-        const renderModel =
-            PcbScene3dController.#normalizeSceneDescription(sceneDescription)
+        const renderModel = PcbScene3dController.#normalizeSceneDescription(
+            sceneDescription,
+            options
+        )
         this.#sceneDescription = renderModel
         this.#selectionIndex =
             PcbScene3dSelectionIndexBuilder.build(renderModel)
@@ -472,7 +472,8 @@ export class PcbScene3dController {
             setDiagnostics: (messages) => this.#setDiagnostics(messages),
             setSelection: (selection) =>
                 this.#handleRuntimeSelection(selection),
-            translate: this.#translate
+            translate: this.#translate,
+            modelLoaderOptions: options.modelLoaderOptions
         })
         this.#applyInitialToggles()
         if (!this.#autoSearchMissingModels) {
@@ -621,7 +622,8 @@ export class PcbScene3dController {
                 archiveBaseName: PcbScene3dController.#resolveArchiveBaseName(
                     this.#documentModel
                 ),
-                sceneDescription: this.#sceneDescription
+                sceneDescription: this.#sceneDescription,
+                modelLoaderOptions: this.#modelLoaderOptions
             })
 
             if (this.#isDisposed) {
@@ -908,35 +910,34 @@ export class PcbScene3dController {
         if (
             PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(options.circuitJson)
         ) {
-            return options.circuitJson
+            return PcbScene3dCircuitJsonAdapter.prepare(options.circuitJson)
         }
         if (
             PcbScene3dCircuitJsonAdapter.isDirectCircuitJsonModel(documentModel)
         ) {
-            return documentModel
+            return PcbScene3dCircuitJsonAdapter.prepare(documentModel)
         }
         return null
     }
 
     /**
-     * Converts direct CircuitJSON inputs into the renderer scene model.
      * @param {any} sceneDescription Scene description or CircuitJSON model.
+     * @param {object} options Controller options forwarded to CircuitJSON adaptation.
      * @returns {any}
      */
-    static #normalizeSceneDescription(sceneDescription) {
+    static #normalizeSceneDescription(sceneDescription, options) {
         const normalizedScene =
             PcbScene3dCircuitJsonAdapter.isDirectCircuitJsonModel(
                 sceneDescription
             )
-                ? PcbScene3dCircuitJsonAdapter.build(sceneDescription)
+                ? PcbScene3dCircuitJsonAdapter.build(sceneDescription, options)
                 : sceneDescription
-
         return PcbScene3dExternalPlacementDefaults.apply(normalizedScene)
     }
 
     /**
      * Resolves one archive base name from the mounted document metadata.
-     * @param {{ summary?: { title?: string }, fileName?: string } | null} documentModel
+     * @param {{ summary?: { title?: string }, fileName?: string, source?: { fileName?: string }, document?: { source?: { fileName?: string } } } | null} documentModel
      * @returns {string}
      */
     static #resolveArchiveBaseName(documentModel) {
@@ -945,7 +946,12 @@ export class PcbScene3dController {
             return summaryTitle
         }
 
-        const fileName = String(documentModel?.fileName || '').trim()
+        const fileName = String(
+            documentModel?.source?.fileName ||
+                documentModel?.document?.source?.fileName ||
+                documentModel?.fileName ||
+                ''
+        ).trim()
         if (fileName) {
             return fileName.replace(/\.[^.]+$/, '')
         }