pcb-scene3d-viewer 1.1.31 → 1.1.44

package/AGENTS.md

@@ -35,9 +35,10 @@
 ## Library Scope
 
 - Include browser-side Three.js scene runtime, geometry factories, STEP/WRL
-  model loading, component picking, view presets, archive export, the optional
-  DOM controller, and the optional 3D shell renderer/styles.
-- Do not include ECAD parser logic or format-specific scene-description
+  model loading, component picking, view presets, archive export, CircuitJSON
+  scene adapters and CAD model asset resolution, the optional DOM controller,
+  and the optional 3D shell renderer/styles.
+- Do not include ECAD parser logic or source-format-specific scene-description
   builders. Altium and KiCad scene descriptions are produced by their own
   toolkits and passed into this package.
 - Keep renderer fixes universal. Never special-case a specific file name,

package/docs/api.md

@@ -65,7 +65,13 @@ Methods:
   host `buildScene` callbacks.
 - `build(circuitJson, options?)`: returns a runtime-ready scene description.
   `options.modelUrlResolver` can attach caller-owned URL resolution metadata to
-  `cad_component` external models without fetching them.
+  `cad_component` external models without fetching them. `projectBaseUrl`
+  resolves relative model URLs and package-style `node_modules/...` model paths,
+  `drawFauxBoard: true` generates a board around component bounds when no board
+  or panel exists, `boardDrillQuality` controls generated circular
+  drill/cutout sampling, and `showPcbNotes: true` renders note, fabrication,
+  and courtyard artwork as silkscreen detail. `showPcbPaste: true` renders
+  direct solder-paste artwork as a separate top/bottom overlay.
 
 `PcbScene3dController` and `PcbScene3dRuntime` call this adapter automatically
 when they receive direct CircuitJSON input. See
@@ -130,7 +136,10 @@ Workers respond with `scene3d:success` and `sceneDescription`, or
 Builds export meshes from a prepared scene description. `options.modelMeshLoader`
 can provide external model meshes, `options.includeModels: false` skips external
 model loading, and `options.renderFallbackBodies: false` disables procedural
-component bodies for unresolved models.
+component bodies for unresolved models. Placements with `renderAsBoundingBox:
+true` are exported as procedural component bodies instead of loading the
+referenced model. Optional solder-paste detail exports as distinct paste meshes
+when present in `sceneDescription.detail.paste`.
 
 ### `PcbAssemblyGltfWriter.write(options?)`
 
@@ -143,9 +152,32 @@ Options:
   `color`, optional `opacity`, and optional board `texture` data URIs.
 - `format`: `gltf` or `glb`.
 - `binary`: optional boolean equivalent to `format: 'glb'`.
+- `includeSceneMetadata`: when `true`, emits a default camera and punctual light
+  for third-party GLTF viewers.
 
 Returns a GLTF JSON object for `gltf` and a `Uint8Array` for `glb`. RGBA colors
-or opacity values below `1` are emitted as blended GLTF materials.
+or opacity values below `1` are emitted as blended GLTF materials. Mesh
+`vertexColors` are exported as `COLOR_0`, and mesh `material` metadata is
+preserved in material extras.
+
+### `new PcbAssemblyModelMeshLoader(options?)`
+
+Loads STEP, WRL, STL, OBJ, GLTF, and GLB external models into assembly meshes.
+By default the loader only reads embedded payloads, session files, and provided
+byte buffers. Network loading is opt-in through either an injected `fetch`
+function or `allowNetworkModelFetch: true`. Remote `.gltf` buffer sidecars are
+resolved relative to the `.gltf` URL and use the same fetch, auth-header,
+timeout, and cache policy as the top-level model.
+
+Options:
+
+- `stepLoader`: custom STEP loader.
+- `fetch`: host-provided fetch function for resolved model URLs.
+- `allowNetworkModelFetch`: use `globalThis.fetch` for `resolvedUrl` or
+  `sourceUrl` models when no local payload is present.
+- `authHeaders`: headers forwarded to network model requests.
+- `fetchTimeoutMs`: abort timeout for network model requests.
+- `modelCache`: optional cache map keyed by resolved model URL.
 
 ## Model Archive Export
 

package/docs/circuitjson.md

@@ -124,6 +124,24 @@ const sceneDescription = PcbScene3dCircuitJsonAdapter.build(circuitJson, {
 })
 ```
 
+Hosts can also pass `projectBaseUrl` to resolve relative model URLs without a
+custom resolver. Package-style `node_modules/...` paths resolve to the
+project-origin `/package_files/download` endpoint with package and file-path
+query parameters. Package download file paths are normalized under `dist/` when
+the source path does not already include it. Model fetching remains a separate
+host/export decision.
+`boardDrillQuality` accepts `low`, `medium`, or `high` and controls generated
+circle sampling for direct CircuitJSON drill/cutout geometry. When a
+CircuitJSON file has components but no board or panel, `drawFauxBoard: true`
+generates a board from component bounds with a 2 mm margin per side.
+Set `showPcbNotes: true` to render `pcb_note_text`,
+`pcb_fabrication_note_text`, note/fabrication path artwork, and courtyard
+artwork as silkscreen detail. Notes are hidden by default so manufacturing
+annotations do not unexpectedly appear in board previews.
+Set `showPcbPaste: true` to render `pcb_solder_paste` as a grey top/bottom
+surface overlay. Paste is hidden by default so stencil-only manufacturing data
+does not clutter normal board previews.
+
 `isDirectCircuitJsonModel(value)` returns `false` for compatibility arrays that
 also carry legacy parser fields such as `pcb`, `schematic`, or `bom`. Those
 arrays continue through the host-provided `buildScene` callback so existing
@@ -138,12 +156,27 @@ the Three.js runtime.
 The board center defaults to `{ x: 0, y: 0 }` when omitted. If no `pcb_panel`
 or `pcb_board` element is present, the adapter creates a 25.4 mm by 25.4 mm
 board with a 1.6 mm thickness so incomplete test or preview models still
-render.
+render. With `drawFauxBoard: true`, that fallback board is instead sized around
+the PCB component bounds with a minimum 10 mm by 10 mm footprint.
+
+`cad_component` records with `show_as_bounding_box: true` are exported as
+procedural component bodies. If `size` or `model_size` is present, those
+dimensions drive the generated body; otherwise the paired `pcb_component`
+footprint dimensions are used.
+
+When a `cad_component` has no explicit model URL, package footprint metadata
+from `footprinter_string`, `footprint_string`, `footprint`, or `package` can
+generate a richer fallback body. Common dual-row, quad-row, SOT-style,
+through-hole pin-header, passive-chip, pushbutton, testpoint, and TO-style
+package strings add simple lead, pin, or terminal geometry while keeping the
+plain box fallback for unrecognized package text.
 
 Layer values resolve as follows:
 
-- `1`, `top`, `front`, and `f.cu` map to the top side.
-- `32`, `bottom`, `back`, and `b.cu` map to the bottom side.
+- `1`, `top`, `front`, `f.cu`, and top-side artwork layer names map to the
+  top side.
+- `32`, `bottom`, `back`, `b.cu`, and bottom-side artwork layer names map to
+  the bottom side.
 - Unknown layer values default to the top side.
 
 ## Supported Elements
@@ -151,21 +184,37 @@ Layer values resolve as follows:
 The adapter focuses on renderer-ready PCB geometry and ignores unsupported
 CircuitJSON elements instead of failing the whole scene.
 
-| Element type          | Rendered as                                                         |
-| --------------------- | ------------------------------------------------------------------- |
-| `pcb_panel`           | Preferred board/panel size, thickness, center, and optional outline |
-| `pcb_board`           | Board size, thickness, center, and optional outline                 |
-| `pcb_cutout`          | Through-board cutout loop                                           |
-| `source_component`    | Component designator and package metadata                           |
-| `pcb_component`       | Fallback component body and selection target                        |
-| `cad_component`       | External model URL metadata and placement data                      |
-| `pcb_smtpad`          | Top or bottom SMT pad copper                                        |
-| `pcb_plated_hole`     | Through-hole pad copper and drill                                   |
-| `pcb_hole`            | Non-plated drill opening                                            |
-| `pcb_via`             | Via copper and drill                                                |
-| `pcb_trace`           | Routed copper track segments                                        |
-| `pcb_silkscreen_line` | Top or bottom silkscreen stroke                                     |
-| `pcb_silkscreen_text` | Top or bottom silkscreen text placeholder                           |
+| Element type                | Rendered as                                                         |
+| --------------------------- | ------------------------------------------------------------------- |
+| `pcb_panel`                 | Preferred board/panel size, thickness, center, and optional outline |
+| `pcb_board`                 | Board size, thickness, center, and optional outline                 |
+| `pcb_cutout`                | Through-board cutout loop                                           |
+| `source_component`          | Component designator and package metadata                           |
+| `pcb_component`             | Fallback component body and selection target                        |
+| `cad_component`             | External model URL metadata and placement data                      |
+| `pcb_smtpad`                | Top or bottom SMT pad copper, including pill pads                   |
+| `pcb_plated_hole`           | Through-hole pad copper and drill                                   |
+| `pcb_hole`                  | Non-plated drill opening                                            |
+| `pcb_via`                   | Via copper and drill                                                |
+| `pcb_trace`                 | Routed copper track segments and route-derived surface vias         |
+| `pcb_copper_pour`           | Top or bottom copper zone polygon                                   |
+| `pcb_solder_paste`          | Optional top or bottom paste fill when `showPcbPaste` is enabled    |
+| `pcb_silkscreen_line`       | Top or bottom silkscreen stroke                                     |
+| `pcb_silkscreen_path`       | Top or bottom routed silkscreen strokes                             |
+| `pcb_silkscreen_circle`     | Top or bottom full-circle silkscreen stroke                         |
+| `pcb_silkscreen_rect`       | Top or bottom rectangular silkscreen outline                        |
+| `pcb_silkscreen_oval`       | Top or bottom oval silkscreen outline                               |
+| `pcb_silkscreen_pill`       | Top or bottom pill silkscreen outline                               |
+| `pcb_silkscreen_text`       | Top or bottom silkscreen text placeholder                           |
+| `pcb_note_text`             | Optional top or bottom note text when `showPcbNotes` is enabled     |
+| `pcb_note_line`             | Optional top or bottom note stroke when `showPcbNotes` is enabled   |
+| `pcb_note_path`             | Optional top or bottom note path when `showPcbNotes` is enabled     |
+| `pcb_note_rect`             | Optional top or bottom note outline when `showPcbNotes` is enabled  |
+| `pcb_fabrication_note_text` | Optional fabrication text when `showPcbNotes` is enabled            |
+| `pcb_fabrication_note_path` | Optional fabrication path when `showPcbNotes` is enabled            |
+| `pcb_courtyard_rect`        | Optional courtyard rectangle when `showPcbNotes` is enabled         |
+| `pcb_courtyard_circle`      | Optional courtyard circle when `showPcbNotes` is enabled            |
+| `pcb_courtyard_outline`     | Optional courtyard outline when `showPcbNotes` is enabled           |
 
 `cad_component` entries can provide external model URLs and model-local
 placement hints. The adapter maps `model_unit_to_mm_scale_factor`,
@@ -189,7 +238,9 @@ Board outlines can be supplied as `pcb_board.outline`, using an array of points:
 ```
 
 Through-board cutouts can be supplied as polygon, rectangle, or circle
-`pcb_cutout` elements:
+`pcb_cutout` elements. A `pcb_cutout` with `pcb_board_id` only applies when that
+board is selected, while cutouts without a board target are global. Rectangular
+cutouts support `ccw_rotation`:
 
 ```js
 {
@@ -197,17 +248,80 @@ Through-board cutouts can be supplied as polygon, rectangle, or circle
     shape: 'rect',
     center: { x: 25, y: 15 },
     width: 4,
-    height: 2
+    height: 2,
+    ccw_rotation: 45
+}
+```
+
+Drills can use circular, pill, or rotated pill geometry. `hole_offset_x` and
+`hole_offset_y` move the drill center independently of the pad/copper center:
+
+```js
+{
+    type: 'pcb_plated_hole',
+    x: 10,
+    y: 8,
+    hole_shape: 'rotated_pill',
+    hole_width: 0.5,
+    hole_height: 1.5,
+    hole_offset_x: 0.1,
+    hole_offset_y: -0.1,
+    outer_diameter: 2
+}
+```
+
+SMT pads can use circular, rectangular, rotated rectangular, or pill geometry.
+Pill pads are normalized as rounded rectangles so their copper keeps the
+expected capsule outline:
+
+```js
+{
+    type: 'pcb_smtpad',
+    layer: 'top',
+    shape: 'rotated_pill',
+    x: 12,
+    y: 8,
+    width: 2,
+    height: 1,
+    ccw_rotation: 30
+}
+```
+
+SMT pads, plated holes, and vias honor `is_covered_with_solder_mask` and
+`covered_with_solder_mask` when present. `true` keeps the copper under solder
+mask, while `false` exposes the copper on the applicable board side. For vias,
+covered values map to tenting metadata on both sides.
+
+Copper pours can use rectangular, polygon, or B-Rep geometry. Rectangular pours
+support `rotation` or `ccw_rotation`; polygon and B-Rep point coordinates are
+converted from millimeters to mils. `covered_with_solder_mask: true` renders the
+zone under solder mask, while false or omitted values expose the copper:
+
+```js
+{
+    type: 'pcb_copper_pour',
+    layer: 'top',
+    shape: 'rect',
+    center: { x: 25, y: 15 },
+    width: 8,
+    height: 5,
+    rotation: 45,
+    covered_with_solder_mask: false
 }
 ```
 
+Silkscreen text uses `anchor_position` when available, falling back to `x` and
+`y`. Common `anchor_alignment` values such as `center`, `bottom_left`, or
+`top_right` are normalized into horizontal and vertical alignment metadata for
+stroke text rendering.
+
 Component model metadata can be supplied on `cad_component` elements with
-`model_step_url`, `model_wrl_url`, `model_glb_url`, `model_gltf_url`,
-`model_stl_url`, or `model_obj_url`. The adapter emits external placement
-metadata for the host runtime or export pipeline to resolve.
+`model_3mf_url`, `model_step_url`, `model_wrl_url`, `model_glb_url`,
+`model_gltf_url`, `model_stl_url`, or `model_obj_url`. The adapter emits
+external placement metadata for the host runtime or export pipeline to resolve.
 
-Traces can be supplied as a `route` array. Each adjacent point pair becomes one
-track segment:
+Traces can be supplied as a `route` array. Each adjacent wire point pair becomes
+one track segment:
 
 ```js
 {
@@ -222,6 +336,31 @@ track segment:
 }
 ```
 
+Route entries with `route_type: 'via'` produce via primitives when their
+`from_layer`, `to_layer`, or `layer` touches the top or bottom surface. Adjacent
+surface wire segments remain visible through those vias. Inner-only vias and
+inner-only wire segments are ignored by the surface-copper view. If a route via
+omits `hole_diameter`, `via_hole_diameter`, or `drill_diameter`, the drill
+diameter defaults to half of `via_diameter`.
+
+```js
+{
+    type: 'pcb_trace',
+    route: [
+        { route_type: 'wire', x: 5, y: 5, width: 0.2, layer: 'top' },
+        {
+            route_type: 'via',
+            x: 8,
+            y: 5,
+            from_layer: 'top',
+            to_layer: 'bottom',
+            via_diameter: 0.4
+        },
+        { route_type: 'wire', x: 8, y: 10, width: 0.2, layer: '32' }
+    ]
+}
+```
+
 ## Diagnostics
 
 Malformed CircuitJSON input is rejected by `circuitjson-toolkit` before render

package/docs/model-format.md

@@ -35,6 +35,10 @@ toolkits are responsible for creating this data.
         silkscreen: {
             top: {},
             bottom: {}
+        },
+        paste: {
+            top: {},
+            bottom: {}
         }
     }
 }
@@ -92,14 +96,48 @@ External placements describe STEP, WRL, GLB, GLTF, STL, or OBJ model instances:
         name: 'soic-8.step',
         relativePath: 'packages/soic-8.step',
         format: 'step',
+        sourceUrl: '/models/soic-8.step',
+        resolvedUrl: 'https://assets.example.invalid/models/soic-8.step',
         file: File
     }
 }
 ```
 
 OBJ models can carry sidecar material libraries in `resources`, `relatedFiles`,
-`assets`, or similar metadata collections. GLTF/GLB material alpha and mesh
-opacity are preserved in exported GLTF/GLB materials.
+`assets`, or similar metadata collections. OBJ diffuse, ambient, specular,
+shininess, alpha, and vertex colors are preserved in the parsed mesh metadata.
+GLTF/GLB material alpha, mesh opacity, and `COLOR_0` vertex colors are
+preserved in imported and exported GLTF/GLB materials and primitives.
+GLTF/GLB import consumes triangle primitives and ignores unsupported primitive
+modes such as points or lines. Remote `.gltf` files can reference external
+`buffers[].uri` sidecars; when URL-backed model loading is enabled, the loader
+resolves those sidecars relative to the `.gltf` URL and fetches them with the
+same cache, timeout, and auth-header policy.
+
+Resolved model URLs are not fetched by default. Hosts that want URL-backed model
+loading must provide an explicit fetch policy through `PcbAssemblyModelMeshLoader`
+or a higher-level export service. Use `authHeaders`, `fetchTimeoutMs`, and a
+caller-owned `modelCache` when remote model requests are enabled.
+
+When `projectBaseUrl` is provided to the CircuitJSON adapter, package-style
+model paths such as `node_modules/package-name/path/to/model.step` are resolved
+to `/package_files/download` on the project origin with
+`package_name_with_version` and `file_path` query parameters. Package download
+file paths are normalized under `dist/` unless they already start there. This
+only records a resolved URL; fetching still requires an explicit loader/export
+fetch policy.
+
+CAD placements can request procedural bounding-box output with
+`show_as_bounding_box: true`. The adapter marks those placements with
+`renderAsBoundingBox: true`, copies `size`/`model_size` into fallback body
+dimensions when present, and the assembly geometry builder skips external model
+loading for that placement.
+
+When package footprint text is available, fallback bodies can derive simple
+package-specific geometry for passive chips, dual-row and quad-row ICs,
+SOT-style packages, pin headers, pushbuttons, testpoints, and TO-style
+through-hole packages. Testpoints and radial capacitors use round fallback
+bodies in both runtime rendering and assembly export.
 
 Embedded STEP models can use:
 
@@ -118,11 +156,24 @@ The runtime expects pre-normalized primitive lists for:
 
 - pads and vias with drill and copper dimensions;
 - tracks and arcs with layer metadata;
-- fills and polygons with point loops;
+- fills and polygons with point loops or B-Rep ring metadata;
 - silkscreen tracks, arcs, fills, and texts;
+- optional solder-paste fills in `detail.paste`;
 - copper text primitives.
 
 The viewer does not infer source-file semantics. When a scene needs
 format-specific layer mapping, solder-mask interpretation, text layout, or
 model matching, the source toolkit should encode those decisions in the scene
 description.
+
+Through-hole pads can describe offset or slotted drills with `holeOffsetX`,
+`holeOffsetY`, `holeSlotLength`, and `holeRotation`. Board substrate export uses
+`detail.drillQuality` values of `low`, `medium`, or `high` to choose circular
+drill sampling density.
+
+Rounded SMT pads set `hasRoundedRect`, the side-specific
+`roundedRectShapeTop`/`roundedRectShapeBottom`, and
+`cornerRadiusTop`/`cornerRadiusBottom` as a percent of the shortest copper side.
+Route-derived vias use the same `detail.vias` shape as standalone vias, and
+surface route segments use `layerId: 1` for top copper or `layerId: 32` for
+bottom copper.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.31",
+    "version": "1.1.44",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -52,7 +52,7 @@
     },
     "dependencies": {
         "@sunbox/occt-import-js": "^0.0.25",
-        "circuitjson-toolkit": "^1.0.1",
+        "circuitjson-toolkit": "^1.0.10",
         "earcut": "^3.0.2",
         "fflate": "^0.8.2",
         "three": "^0.183.2"

package/src/CircuitJsonCadModelAssetResolver.mjs

@@ -0,0 +1,261 @@
+/**
+ * Bridges CAD component model asset metadata to scene model resolution.
+ */
+export class CircuitJsonCadModelAssetResolver {
+    /**
+     * Adds URL fields derived from CAD `model_asset` records.
+     * @param {object | object[]} documentModel Document model.
+     * @returns {object | object[]}
+     */
+    static withModelAssetUrls(documentModel) {
+        const elements =
+            CircuitJsonCadModelAssetResolver.#elements(documentModel)
+        if (
+            !elements.some((element) =>
+                CircuitJsonCadModelAssetResolver.#modelAssetUrlField(element)
+            )
+        ) {
+            return documentModel
+        }
+
+        const nextElements = elements.map((element) =>
+            CircuitJsonCadModelAssetResolver.#withModelAssetUrl(element)
+        )
+
+        if (Array.isArray(documentModel)) {
+            Object.assign(nextElements, {
+                sourceFormat: documentModel.sourceFormat,
+                kind: documentModel.kind,
+                fileName: documentModel.fileName,
+                bom: documentModel.bom
+            })
+            return nextElements
+        }
+
+        if (Array.isArray(documentModel?.elements)) {
+            return { ...documentModel, elements: nextElements }
+        }
+        if (Array.isArray(documentModel?.circuitJson)) {
+            return { ...documentModel, circuitJson: nextElements }
+        }
+        return documentModel
+    }
+
+    /**
+     * Adds a session-asset-aware model URL resolver.
+     * @param {object} options Scene preparation options.
+     * @returns {object}
+     */
+    static withSessionAssetResolver(options = {}) {
+        const sessionAssets = Array.isArray(options.sessionAssets)
+            ? options.sessionAssets
+            : []
+        const callerResolver =
+            typeof options.modelUrlResolver === 'function'
+                ? options.modelUrlResolver
+                : null
+
+        return {
+            ...options,
+            modelUrlResolver: (url, context) =>
+                CircuitJsonCadModelAssetResolver.#resolveModelUrl(
+                    url,
+                    context,
+                    sessionAssets,
+                    callerResolver
+                )
+        }
+    }
+
+    /**
+     * Adds a model URL field to one CAD component when possible.
+     * @param {object} element Element row.
+     * @returns {object}
+     */
+    static #withModelAssetUrl(element) {
+        const field =
+            CircuitJsonCadModelAssetResolver.#modelAssetUrlField(element)
+        if (!field) return element
+        const asset = element.model_asset || {}
+        const sourceUrl = String(
+            asset.project_relative_path || asset.url || ''
+        ).trim()
+        if (!sourceUrl) return element
+        return { ...element, [field]: sourceUrl }
+    }
+
+    /**
+     * Resolves a model URL field for one CAD component asset.
+     * @param {object} element Element row.
+     * @returns {string}
+     */
+    static #modelAssetUrlField(element) {
+        if (element?.type !== 'cad_component') return ''
+        const asset = element.model_asset
+        if (!asset || typeof asset !== 'object') return ''
+        if (CircuitJsonCadModelAssetResolver.#hasModelUrl(element)) return ''
+        const format = CircuitJsonCadModelAssetResolver.#format(asset)
+        return (
+            {
+                '3mf': 'model_3mf_url',
+                glb: 'model_glb_url',
+                gltf: 'model_gltf_url',
+                obj: 'model_obj_url',
+                step: 'model_step_url',
+                stl: 'model_stl_url',
+                wrl: 'model_wrl_url'
+            }[format] || ''
+        )
+    }
+
+    /**
+     * Resolves a URL to a session asset or caller-provided value.
+     * @param {string} url Model URL.
+     * @param {object} context Resolver context.
+     * @param {object[]} sessionAssets Session asset rows.
+     * @param {((url: string, context: object) => any) | null} callerResolver Caller resolver.
+     * @returns {object | string | null}
+     */
+    static #resolveModelUrl(url, context, sessionAssets, callerResolver) {
+        const matchedAsset =
+            CircuitJsonCadModelAssetResolver.#matchingSessionAsset(
+                url,
+                context,
+                sessionAssets
+            )
+        if (matchedAsset) {
+            return matchedAsset
+        }
+        return callerResolver ? callerResolver(url, context) : null
+    }
+
+    /**
+     * Finds a session asset matching one CAD model URL.
+     * @param {string} url Model URL.
+     * @param {object} context Resolver context.
+     * @param {object[]} sessionAssets Session assets.
+     * @returns {object | null}
+     */
+    static #matchingSessionAsset(url, context, sessionAssets) {
+        const candidates = CircuitJsonCadModelAssetResolver.#urlCandidates(
+            url,
+            context
+        )
+        return (
+            sessionAssets.find((asset) =>
+                CircuitJsonCadModelAssetResolver.#assetMatches(
+                    asset,
+                    candidates
+                )
+            ) || null
+        )
+    }
+
+    /**
+     * Builds normalized URL/path candidates for matching.
+     * @param {string} url Model URL.
+     * @param {object} context Resolver context.
+     * @returns {Set<string>}
+     */
+    static #urlCandidates(url, context) {
+        return new Set(
+            [
+                url,
+                context?.cadComponent?.model_asset?.project_relative_path,
+                context?.cadComponent?.model_asset?.url
+            ]
+                .map((value) => CircuitJsonCadModelAssetResolver.#key(value))
+                .filter(Boolean)
+        )
+    }
+
+    /**
+     * Returns true when a session asset matches a model URL.
+     * @param {object} asset Session asset.
+     * @param {Set<string>} candidates URL candidates.
+     * @returns {boolean}
+     */
+    static #assetMatches(asset, candidates) {
+        return [
+            asset?.relativePath,
+            asset?.sourceUrl,
+            asset?.url,
+            asset?.name
+        ].some((value) =>
+            candidates.has(CircuitJsonCadModelAssetResolver.#key(value))
+        )
+    }
+
+    /**
+     * Resolves a supported model format from asset metadata.
+     * @param {object} asset Model asset metadata.
+     * @returns {string}
+     */
+    static #format(asset) {
+        const text = String(
+            asset.format ||
+                asset.mimetype ||
+                asset.project_relative_path ||
+                asset.url ||
+                ''
+        ).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'
+        if (/step|stp|\.step(?:[?#]|$)|\.stp(?:[?#]|$)/u.test(text)) {
+            return 'step'
+        }
+        return ''
+    }
+
+    /**
+     * Returns true when a CAD component already has a model URL.
+     * @param {object} element Element row.
+     * @returns {boolean}
+     */
+    static #hasModelUrl(element) {
+        return [
+            'model_step_url',
+            'model_stp_url',
+            'model_3mf_url',
+            'model_wrl_url',
+            'model_vrml_url',
+            'model_glb_url',
+            'model_gltf_url',
+            'model_stl_url',
+            'model_obj_url'
+        ].some((field) => String(element?.[field] || '').trim())
+    }
+
+    /**
+     * Reads element rows from document wrappers.
+     * @param {object | object[]} documentModel Document model.
+     * @returns {object[]}
+     */
+    static #elements(documentModel) {
+        if (Array.isArray(documentModel)) return documentModel
+        if (Array.isArray(documentModel?.elements))
+            return documentModel.elements
+        if (Array.isArray(documentModel?.circuitJson)) {
+            return documentModel.circuitJson
+        }
+        return []
+    }
+
+    /**
+     * Normalizes a path or URL key.
+     * @param {unknown} value Raw path.
+     * @returns {string}
+     */
+    static #key(value) {
+        return String(value || '')
+            .trim()
+            .split(/[?#]/u)[0]
+            .replace(/^https?:\/\/[^/]+\//iu, '')
+            .replace(/^\/+/u, '')
+            .toLowerCase()
+    }
+}