pcb-scene3d-viewer 1.1.22 → 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/README.md

@@ -17,8 +17,9 @@ runtime.
 
 The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
 is used for browser-based PCB 3D scene rendering. Its runtime, geometry
-factories, model loading, component picking, view presets, archive export, and
-optional DOM shell can be reused by other browser-based ECAD tools.
+factories, model loading, component picking, view presets, archive export,
+GLTF/GLB assembly writing, and optional DOM shell can be reused by other
+browser-based ECAD tools.
 
 ## Install
 

package/docs/api.md

@@ -63,7 +63,15 @@ Methods:
 - `isCircuitJsonModel(value)`: returns true for serialized CircuitJSON arrays.
 - `isDirectCircuitJsonModel(value)`: returns true when the array should bypass
   host `buildScene` callbacks.
-- `build(circuitJson)`: returns a runtime-ready scene description.
+- `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. `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
@@ -121,6 +129,56 @@ worker.postMessage({
 Workers respond with `scene3d:success` and `sceneDescription`, or
 `scene3d:error` and `message`.
 
+## Assembly Geometry Export
+
+### `PcbAssemblyGeometryBuilder.build(sceneDescription, options?)`
+
+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. 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?)`
+
+Writes faceted assembly meshes as GLTF 2.0 JSON or binary GLB.
+
+Options:
+
+- `name`: scene name.
+- `meshes`: export meshes with `vertices`, `faces`, optional RGB or RGBA
+  `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. 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
 
 ### `PcbModelArchiveExporter.buildArchive(options?)`

package/docs/circuitjson.md

@@ -109,6 +109,39 @@ if (PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(circuitJson)) {
 }
 ```
 
+Hosts that need URL policy control can pass a synchronous `modelUrlResolver`.
+The adapter records the returned metadata on each external model but does not
+fetch the referenced file:
+
+```js
+const sceneDescription = PcbScene3dCircuitJsonAdapter.build(circuitJson, {
+    modelUrlResolver(url, context) {
+        return {
+            resolvedUrl: sameOriginProxyUrl(url),
+            sameOrigin: context.format === 'step'
+        }
+    }
+})
+```
+
+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
@@ -120,14 +153,30 @@ CircuitJSON input uses millimeters. The adapter converts all board, component,
 pad, via, trace, and silkscreen dimensions into mils before handing the scene to
 the Three.js runtime.
 
-The board center defaults to `{ x: 0, y: 0 }` when omitted. If no `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.
+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. 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
@@ -135,18 +184,44 @@ 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_board`           | Board size, thickness, center, and optional outline |
-| `source_component`    | Component designator and package metadata           |
-| `pcb_component`       | Fallback component body and selection target        |
-| `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`,
+`model_origin_position`, `model_offset`, `model_origin_alignment`,
+`model_object_fit`, `model_board_normal_direction`, and `size` into normalized
+model transforms, and maps `show_as_translucent_model` into export/display
+opacity metadata.
 
 Board outlines can be supplied as `pcb_board.outline`, using an array of points:
 
@@ -162,8 +237,91 @@ Board outlines can be supplied as `pcb_board.outline`, using an array of points:
 }
 ```
 
-Traces can be supplied as a `route` array. Each adjacent point pair becomes one
-track segment:
+Through-board cutouts can be supplied as polygon, rectangle, or circle
+`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
+{
+    type: 'pcb_cutout',
+    shape: 'rect',
+    center: { x: 25, y: 15 },
+    width: 4,
+    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_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 wire point pair becomes
+one track segment:
 
 ```js
 {
@@ -178,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
@@ -185,6 +368,7 @@ model conversion. Use `PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(value)`
 for a cheap guard when accepting untrusted JSON from users, and catch conversion
 errors around `build(value)` when you need to show a custom diagnostic.
 
-The viewer does not fetch external assets for CircuitJSON input. STEP and WRL
-model matching remains the responsibility of source-specific toolkits or host
-applications that create normalized scene descriptions.
+The viewer does not fetch external assets for CircuitJSON input by itself.
+Model URL matching, same-origin checks, proxying, and file loading remain the
+responsibility of source-specific toolkits or host applications that create or
+post-process normalized scene descriptions.

package/docs/model-format.md

@@ -35,6 +35,10 @@ toolkits are responsible for creating this data.
         silkscreen: {
             top: {},
             bottom: {}
+        },
+        paste: {
+            top: {},
+            bottom: {}
         }
     }
 }
@@ -66,7 +70,7 @@ Components describe fallback package bodies and selection metadata:
 
 ## External Placements
 
-External placements describe STEP or WRL model instances:
+External placements describe STEP, WRL, GLB, GLTF, STL, or OBJ model instances:
 
 ```js
 {
@@ -78,18 +82,63 @@ External placements describe STEP or WRL model instances:
     bodyRotationDeg: 0,
     modelTransform: {
         rotationDeg: { x: 90, y: 0, z: 0 },
-        dzMil: 0
+        offsetMil: { x: 0, y: 0, z: 0 },
+        scale: { x: 1, y: 1, z: 1 },
+        originPositionMil: { x: 0, y: 0, z: 0 },
+        originAlignment: 'center_of_component_on_board_surface',
+        objectFit: 'fill_bounds',
+        boardNormalDirection: 'z+',
+        targetSizeMil: { x: 200, y: 300, z: 60 }
     },
+    bodyOpacity: 0.5,
     externalModel: {
         origin: 'session',
         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. 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:
 
 ```js
@@ -107,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.22",
+    "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/spec/library-scope.md

@@ -8,12 +8,12 @@ scene descriptions.
 - Three.js runtime orchestration for PCB scenes.
 - Board, copper, via, drill, silkscreen, solder-mask, and fallback package mesh
   factories.
-- STEP and WRL model loading and placement.
+- STEP, WRL, GLB, GLTF, STL, and OBJ model loading and placement.
 - Camera presets, view compensation, selection styling, picking, and visibility
   toggles.
 - Optional DOM shell/controller helpers for hosts that want ready-made scene
   chrome.
-- ZIP export of resolved STEP and WRL model assets.
+- ZIP export of resolved component model assets.
 - CSS for the optional scene shell.
 
 ## Out of Scope