pcb-scene3d-viewer 1.2.1 → 1.2.2

package/README.md

@@ -24,7 +24,7 @@ browser-based ECAD tools.
 
 ## CircuitJSON 1.1 convergence
 
-Version 1.2.1 accepts the common document and prepared-context shapes returned
+Version 1.2.2 accepts the common document and prepared-context shapes returned
 by CircuitJSON, Gerber, Altium, and KiCad Toolkit 1.1-compatible APIs. The
 adapter requests the shared `elements` index once and reuses it across repeated
 scene builds. `PcbScene3dCircuitJsonAdapter.prepare()` exposes that proof-aware
@@ -47,6 +47,13 @@ Legal rectangular and square CircuitJSON drill apertures retain their exact
 width, height, and board-space rotation through substrate, pad, and assembly
 export meshes.
 
+Canonical documents retain their exact `source.format` as the scene
+`sourceFormat`; raw element arrays continue to use `circuitjson`. Routed traces
+and copper pours with no authored solder-mask coverage value remain covered,
+while `covered_with_solder_mask: false` keeps an explicit opening exposed.
+Standard vias likewise default to tented and honor `is_tented: false` as an
+explicit opening.
+
 The live runtime loads STEP/STP, WRL/VRML, STL, OBJ, GLTF/GLB, and 3MF from
 canonical text/bytes or browser files. Referenced GLTF buffers, OBJ material
 libraries, and WRL textures are attached from matching document/session assets
@@ -123,6 +130,7 @@ const controller = new PcbScene3dController(viewportNode, document)
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.md)
+- [1.2.2 release notes](docs/release-notes-v1.2.2.md)
 - [1.2.1 release notes](docs/release-notes-v1.2.1.md)
 - [1.2.0 release notes](docs/release-notes-v1.2.0.md)
 - [Model format](docs/model-format.md)

package/docs/api.md

@@ -108,6 +108,14 @@ Methods:
   and courtyard artwork as silkscreen detail. `showPcbPaste: true` renders
   direct solder-paste artwork as a separate top/bottom overlay.
 
+For canonical document and prepared-context inputs, the returned scene's
+`sourceFormat` is the exact canonical `source.format`. Dense element arrays,
+which do not carry source metadata, retain the `circuitjson` fallback. Routed
+traces and copper pours default to covered when their coverage property is
+omitted; an explicit `covered_with_solder_mask: false` remains an exposed
+opening. Standard vias default to tented and honor `is_tented: false` as an
+explicit opening.
+
 `PcbScene3dController` and `PcbScene3dRuntime` call this adapter automatically
 when they receive direct CircuitJSON input. See
 [CircuitJSON usage](circuitjson.md) for supported elements, units, and examples.

package/docs/circuitjson.md

@@ -14,6 +14,10 @@ KiCad, Gerber, or other format-specific scene builder.
 Prepared contexts are the fastest repeated-render path because validation and
 the adapter's `elements` index are built at most once.
 
+Canonical document envelopes and prepared contexts retain `source.format` as
+the normalized scene's `sourceFormat`. Dense element arrays have no canonical
+source metadata and therefore use `circuitjson`.
+
 ## Direct Controller Input
 
 Pass any accepted CircuitJSON shape as the `documentModel`. The controller
@@ -403,13 +407,15 @@ expected capsule outline:
 
 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.
+mask, while `false` exposes the copper on the applicable board side. Standard
+vias also honor `is_tented`; omitted via tenting defaults to covered on both
+sides, while `is_tented: false` retains an explicit opening.
 
 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:
+converted from millimeters to mils. Omitted or true
+`covered_with_solder_mask` renders the zone under solder mask, while an
+explicit false value exposes the copper:
 
 ```js
 {
@@ -450,6 +456,11 @@ one track segment:
 }
 ```
 
+Trace-level or route-entry `covered_with_solder_mask` values control the
+rendered opening. Omitted values default to covered; an explicit false value
+remains exposed. A route-entry value takes precedence over its trace-level
+value.
+
 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

package/docs/release-notes-v1.2.2.md

@@ -0,0 +1,33 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# PCB Scene3D Viewer 1.2.2
+
+Version 1.2.2 preserves canonical source identity and aligns solder-mask
+coverage with the converged CircuitJSON contract.
+
+## API and behavior changes
+
+- Canonical document and prepared-context inputs now retain their exact
+  `source.format` as the rendered scene's `sourceFormat`. Dense CircuitJSON
+  arrays continue to use the `circuitjson` fallback because they carry no
+  canonical source metadata.
+- Routed traces and copper pours now default omitted
+  `covered_with_solder_mask` values to covered. Explicit false values remain
+  exposed through the solder mask.
+- Standard vias now honor canonical `is_tented` metadata. Omitted values
+  default to tented, while `is_tented: false` remains exposed.
+- Covered canonical copper follows the existing solder-mask material palette,
+  including tracks, pours, and via annuli.
+
+Consumers that used the generic `circuitjson` marker for canonical documents
+must now handle the retained source identity such as `gerber`, `altium`, or
+`kicad`.
+
+## Dependencies and validation
+
+- Requires `circuitjson-toolkit ^1.1.2` and Node.js 20 or newer.
+- The full test suite and both owned performance benchmarks cover the canonical
+  source, coverage, material, exact-geometry, and prepared-context paths.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.2.1",
+    "version": "1.2.2",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -35,6 +35,7 @@
         "docs/circuitjson.md",
         "docs/release-notes-v1.2.0.md",
         "docs/release-notes-v1.2.1.md",
+        "docs/release-notes-v1.2.2.md",
         "docs/model-format.md",
         "docs/testing.md",
         "spec",
@@ -56,7 +57,7 @@
     },
     "dependencies": {
         "@sunbox/occt-import-js": "^0.0.28",
-        "circuitjson-toolkit": "^1.1.0",
+        "circuitjson-toolkit": "^1.1.2",
         "earcut": "3.0.2",
         "fflate": "^0.8.2",
         "polygon-clipping": "^0.15.7",

package/src/PcbScene3dCircuitJsonAdapter.mjs

@@ -131,7 +131,7 @@ export class PcbScene3dCircuitJsonAdapter {
         )
 
         return {
-            sourceFormat: 'circuitjson',
+            sourceFormat: context.source?.format || 'circuitjson',
             coordinateSystem: 'circuitjson-mm',
             board,
             components,

package/src/PcbScene3dCircuitJsonCopperPourBuilder.mjs

@@ -257,7 +257,12 @@ export class PcbScene3dCircuitJsonCopperPourBuilder {
      */
     static #isCoveredWithMask(pour) {
         const value = pour?.covered_with_solder_mask
-        return value === true || String(value).toLowerCase() === 'true'
+        if (typeof value === 'boolean') return value
+        if (value === undefined || value === null || value === '') return true
+
+        const text = String(value).trim().toLowerCase()
+        if (text === 'false') return false
+        return true
     }
 
     /**

package/src/PcbScene3dCircuitJsonTraceRouteBuilder.mjs

@@ -85,7 +85,11 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
                 0.1524
             ),
             layerId: PcbScene3dCircuitJsonLayer.layerId(side),
-            solderMaskOpening: true
+            solderMaskOpening:
+                PcbScene3dCircuitJsonTraceRouteBuilder.#solderMaskOpening(
+                    entry,
+                    trace
+                )
         }
     }
 
@@ -199,7 +203,12 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
                 0.1524
             ),
             layerId: PcbScene3dCircuitJsonLayer.layerId(side),
-            solderMaskOpening: true
+            solderMaskOpening:
+                PcbScene3dCircuitJsonTraceRouteBuilder.#solderMaskOpening(
+                    start,
+                    end,
+                    trace
+                )
         }
     }
 
@@ -303,19 +312,50 @@ export class PcbScene3dCircuitJsonTraceRouteBuilder {
      * @returns {boolean}
      */
     static #isSolderMaskCovered(via) {
-        const value =
-            via?.is_covered_with_solder_mask ?? via?.covered_with_solder_mask
-        if (typeof value === 'boolean') {
-            return value
+        if (typeof via?.is_tented === 'boolean') {
+            return via.is_tented
         }
-
         return (
-            String(value || '')
-                .trim()
-                .toLowerCase() === 'true'
+            PcbScene3dCircuitJsonTraceRouteBuilder.#solderMaskCoveredValue(
+                via
+            ) ?? true
         )
     }
 
+    /**
+     * Resolves whether trace-like copper has an explicitly authored opening.
+     * @param {...object} elements Route entries followed by their trace.
+     * @returns {boolean}
+     */
+    static #solderMaskOpening(...elements) {
+        for (const element of elements) {
+            const covered =
+                PcbScene3dCircuitJsonTraceRouteBuilder.#solderMaskCoveredValue(
+                    element
+                )
+            if (covered !== null) return !covered
+        }
+        return false
+    }
+
+    /**
+     * Reads one explicit solder-mask coverage value.
+     * @param {object} element CircuitJSON copper element.
+     * @returns {boolean | null}
+     */
+    static #solderMaskCoveredValue(element) {
+        const value =
+            element?.is_covered_with_solder_mask ??
+            element?.covered_with_solder_mask
+        if (typeof value === 'boolean') return value
+        if (value === undefined || value === null || value === '') return null
+
+        const text = String(value).trim().toLowerCase()
+        if (text === 'true') return true
+        if (text === 'false') return false
+        return null
+    }
+
     /**
      * Converts a route point from millimeters to mils.
      * @param {object | undefined} point Source point.