pcb-scene3d-viewer 1.2.2 → 1.3.0

package/README.md

@@ -22,6 +22,12 @@ 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.
 
+Version 1.3.0 renders the CircuitJSON 1.2 fidelity contract directly: exact
+oval and rounded pads, filled and mirrored silkscreen, copper text and cutouts,
+surface-aware blind/buried vias, collision-safe model assets, and a consistent
+light FR-4 substrate edge. See the
+[1.3.0 release notes](docs/release-notes-v1.3.0.md).
+
 ## CircuitJSON 1.1 convergence
 
 Version 1.2.2 accepts the common document and prepared-context shapes returned
@@ -131,6 +137,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.3.0 release notes](docs/release-notes-v1.3.0.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

@@ -68,6 +68,24 @@ controller only and are forwarded to the runtime through
 
 ## CircuitJSON Input
 
+### `PcbScene3dBoardMaterialPalette`
+
+The `pcb-scene3d-viewer/scene3d` subpath exports the shared board-material
+resolver used by both runtime meshes and assembly export.
+
+- `resolveSurfaceColor(board, options?)` returns the authored or fallback
+  solder-mask face color.
+- `resolveBoardSurfaceColor(board, options?)` returns the display-darkened
+  solder-mask face color.
+- `resolveEdgeColor(board)` returns an authored `edgeColor` or the light FR-4
+  substrate fallback `0xc9ca78`.
+- `isGeneratedSurfaceVisible(options?)` and
+  `isGeneratedBodyVisible(options?)` expose the generated-board visibility
+  decision.
+
+Runtime and exported board edges call the same resolver, so a missing edge
+color cannot produce different substrate materials in the two paths.
+
 ### `PcbScene3dCircuitJsonAdapter`
 
 Converts a common CircuitJSON `DocumentResult`, prepared

package/docs/circuitjson.md

@@ -430,10 +430,12 @@ explicit false value exposes the copper:
 }
 ```
 
-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.
+Silkscreen and copper text use `anchor_position` when available, falling back
+to `x` and `y`. Independent `font_width` and `font_height`, `stroke_width`,
+`source_anchor_alignment`, source layer/type provenance, mirroring, and hidden
+state are honored when present. Filled silkscreen shapes retain their fill and
+drill/copper cutouts, and bottom-side artwork is mirrored around its authored
+anchor instead of being repositioned as top-side text.
 
 Component model metadata can be supplied on `cad_component` elements with
 `model_3mf_url`, `model_step_url`, `model_wrl_url`, `model_glb_url`,

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

@@ -0,0 +1,38 @@
+# pcb-scene3d-viewer 1.3.0
+
+This minor release consumes CircuitJSON Toolkit 1.2 directly and restores exact
+PCB surface fidelity without source-format or host-app adapters.
+
+## Rendering and API changes
+
+- Oval, rounded-rectangle, pill, polygon, and independently rotated drilled
+  pads keep their authored copper and drill geometry.
+- Silkscreen strokes, fills, text dimensions, anchors, mirroring, source-layer
+  mapping, and surface cutouts render from canonical CircuitJSON fields.
+- Copper text participates in the same solder-mask and cutout pipeline as other
+  copper detail.
+- Blind and buried vias render only on the board surfaces reached by their
+  explicit layer span.
+- `PcbScene3dBoardMaterialPalette.resolveEdgeColor(board)` is now public on the
+  `scene3d` subpath. Runtime and exported board edges share its authored-color
+  lookup and light FR-4 fallback (`0xc9ca78`).
+
+## Models and diagnostics
+
+- Canonical and session CAD assets preserve exact case-sensitive project-path
+  aliases. Case-insensitive fallback is accepted only when unique, preventing
+  same-name and same-stem collisions across folders.
+- Missing-model diagnostics are deferred until resolution has actually failed;
+  retryable or externally supplied assets are not reported as unavailable
+  prematurely.
+- STEP, WRL, GLTF, and text/binary model payload handling avoids redundant
+  copies and retains the existing opt-in network policy.
+
+## Compatibility and performance
+
+- The runtime baseline is `circuitjson-toolkit@^1.2.0`; the existing
+  `@sunbox/occt-import-js@^0.0.28` WASM package remains compatible and does not
+  require a coordinated rebuild.
+- Existing scene descriptions, document envelopes, controller/runtime
+  parameters, and return shapes remain accepted. The palette method and
+  CircuitJSON fields above are additive.

package/package.json

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

package/src/CircuitJsonCadModelAssetResolver.mjs

@@ -352,7 +352,7 @@ export class CircuitJsonCadModelAssetResolver {
      * Finds the earliest indexed asset matching one CAD model URL.
      * @param {string} url Model URL.
      * @param {object} context Resolver context.
-     * @param {Map<string, object>} assetIndex Asset alias index.
+     * @param {{ exact: Map<string, object | symbol>, folded: Map<string, object | symbol> }} assetIndex Asset alias index.
      * @returns {object | null}
      */
     static #matchingIndexedEntry(url, context, assetIndex) {
@@ -363,7 +363,11 @@ export class CircuitJsonCadModelAssetResolver {
         let match = null
         for (const candidate of candidates) {
             const indexed = assetIndex.exact.get(candidate)
-            if (indexed && (!match || indexed.index < match.index)) {
+            if (
+                indexed &&
+                indexed !== AMBIGUOUS_ASSET &&
+                (!match || indexed.index < match.index)
+            ) {
                 match = indexed
             }
         }
@@ -554,12 +558,13 @@ export class CircuitJsonCadModelAssetResolver {
 
     /**
      * Resolves an exact alias or one unambiguous case-insensitive fallback.
-     * @param {{ exact: Map<string, object>, folded: Map<string, object | symbol> }} index Asset index.
+     * @param {{ exact: Map<string, object | symbol>, folded: Map<string, object | symbol> }} index Asset index.
      * @param {string} key Exact normalized key.
      * @returns {object | null} Indexed asset entry.
      */
     static #indexedAsset(index, key) {
         const exact = index.exact.get(key)
+        if (exact === AMBIGUOUS_ASSET) return null
         if (exact) return exact
         const folded = index.folded.get(key.toLowerCase())
         return folded && folded !== AMBIGUOUS_ASSET ? folded : null
@@ -606,10 +611,10 @@ export class CircuitJsonCadModelAssetResolver {
     }
 
     /**
-     * Builds one descriptor-safe, first-match-preserving asset alias index.
+     * Builds one descriptor-safe asset alias index with collision rejection.
      * @param {object[]} assets Asset rows.
      * @param {boolean} [canonical] Whether rows use the canonical toolkit asset contract.
-     * @returns {{ exact: Map<string, object>, folded: Map<string, object | symbol> }}
+     * @returns {{ exact: Map<string, object | symbol>, folded: Map<string, object | symbol> }}
      */
     static #assetIndex(assets, canonical = false) {
         const exact = new Map()
@@ -625,7 +630,12 @@ export class CircuitJsonCadModelAssetResolver {
             for (const alias of CircuitJsonCadModelAssetResolver.#assetAliases(
                 asset
             )) {
-                if (!exact.has(alias)) exact.set(alias, entry)
+                const exactPrevious = exact.get(alias)
+                if (!exactPrevious) {
+                    exact.set(alias, entry)
+                } else if (exactPrevious !== entry) {
+                    exact.set(alias, AMBIGUOUS_ASSET)
+                }
                 const foldedAlias = alias.toLowerCase()
                 const previous = folded.get(foldedAlias)
                 if (!previous) {
@@ -719,6 +729,9 @@ export class CircuitJsonCadModelAssetResolver {
             asset,
             'source'
         )
+        const explicitAliases = CircuitJsonCadModelAssetResolver.#denseArray(
+            CircuitJsonCadModelAssetResolver.#ownData(asset, 'aliases')
+        ).filter((value) => typeof value === 'string')
         return new Set(
             [
                 CircuitJsonCadModelAssetResolver.#ownData(
@@ -742,7 +755,8 @@ export class CircuitJsonCadModelAssetResolver {
                     'relativePath'
                 ),
                 CircuitJsonCadModelAssetResolver.#ownData(source, 'url'),
-                CircuitJsonCadModelAssetResolver.#ownData(source, 'uri')
+                CircuitJsonCadModelAssetResolver.#ownData(source, 'uri'),
+                ...explicitAliases
             ]
                 .map((value) => CircuitJsonCadModelAssetResolver.#key(value))
                 .filter(Boolean)
@@ -866,10 +880,10 @@ export class CircuitJsonCadModelAssetResolver {
      */
     static #key(value) {
         if (typeof value !== 'string' && typeof value !== 'number') return ''
-        return String(value || '')
+        const key = String(value || '')
             .trim()
             .split(/[?#]/u)[0]
-            .replace(/^https?:\/\/[^/]+\//iu, '')
-            .replace(/^\/+/u, '')
+            .replaceAll('\\', '/')
+        return /^https?:\/\//iu.test(key) ? key : key.replace(/^\/+/u, '')
     }
 }

package/src/PcbAssemblyGltfModelMeshParser.mjs

@@ -1,3 +1,5 @@
+import { PcbScene3dModelContent } from './PcbScene3dModelContent.mjs'
+
 const MM_TO_MIL = 1000 / 25.4
 const GLB_MAGIC = 0x46546c67
 const GLB_VERSION = 2
@@ -887,7 +889,7 @@ export class PcbAssemblyGltfModelMeshParser {
             return bytes
         }
 
-        throw new Error(label + ' model content is not available.')
+        throw PcbScene3dModelContent.unavailableError(label)
     }
 
     /**

package/src/PcbAssemblyModelMeshLoader.mjs

@@ -334,7 +334,7 @@ export class PcbAssemblyModelMeshLoader {
             if (bytes) return new TextDecoder().decode(bytes)
         }
 
-        throw new Error('WRL model content is not available.')
+        throw PcbScene3dModelContent.unavailableError('WRL')
     }
 
     /**

package/src/PcbAssemblyTextModelMeshParser.mjs

@@ -1,3 +1,5 @@
+import { PcbScene3dModelContent } from './PcbScene3dModelContent.mjs'
+
 const MM_TO_MIL = 1000 / 25.4
 
 /**
@@ -548,7 +550,7 @@ export class PcbAssemblyTextModelMeshParser {
             return bytes
         }
 
-        throw new Error(label + ' model content is not available.')
+        throw PcbScene3dModelContent.unavailableError(label)
     }
 
     /**

package/src/PcbScene3dBoardAssemblyPresentation.mjs

@@ -35,8 +35,7 @@ export class PcbScene3dBoardAssemblyPresentation {
                 board,
                 options
             )
-        const edgeColor =
-            PcbScene3dBoardAssemblyPresentation.#resolveEdgeColor(board)
+        const edgeColor = PcbScene3dBoardMaterialPalette.resolveEdgeColor(board)
         const importedSurfaceColor =
             PcbScene3dBoardAssemblyPresentation.#resolveImportedSurfaceColor(
                 meshRecords
@@ -426,15 +425,6 @@ export class PcbScene3dBoardAssemblyPresentation {
         })
     }
 
-    /**
-     * Resolves the app-level substrate edge color for board assembly meshes.
-     * @param {{ edgeColor?: number } | null | undefined} board Board dimensions.
-     * @returns {number}
-     */
-    static #resolveEdgeColor(board) {
-        return Number.isInteger(board?.edgeColor) ? board.edgeColor : 0xc9ca78
-    }
-
     /**
      * Applies display treatment to board substrate material.
      * @param {any | any[]} material Material or material list.

package/src/PcbScene3dBoardMaterialPalette.mjs

@@ -3,6 +3,7 @@
  */
 export class PcbScene3dBoardMaterialPalette {
     static #DEFAULT_SURFACE_COLOR = 0x2a5f27
+    static #DEFAULT_EDGE_COLOR = 0xc9ca78
     static #BOARD_SURFACE_DARKEN_RATIO = 0.88
 
     /**
@@ -39,6 +40,17 @@ export class PcbScene3dBoardMaterialPalette {
         )
     }
 
+    /**
+     * Resolves the visible substrate-core color for board edge faces.
+     * @param {{ edgeColor?: number } | null | undefined} board Board metadata.
+     * @returns {number}
+     */
+    static resolveEdgeColor(board) {
+        return Number.isInteger(board?.edgeColor)
+            ? board.edgeColor
+            : PcbScene3dBoardMaterialPalette.#DEFAULT_EDGE_COLOR
+    }
+
     /**
      * Returns true when the source format supplies display-stable board colors.
      * @param {{ sourceFormat?: string }} options Scene options.

package/src/PcbScene3dCircuitJsonAdapter.mjs

@@ -7,7 +7,8 @@ import { PcbScene3dCircuitJsonGeometry } from './PcbScene3dCircuitJsonGeometry.m
 import { PcbScene3dCircuitJsonDrillDetail } from './PcbScene3dCircuitJsonDrillDetail.mjs'
 import { PcbScene3dCircuitJsonModelTransform } from './PcbScene3dCircuitJsonModelTransform.mjs'
 import { PcbScene3dCircuitJsonCopperPourBuilder } from './PcbScene3dCircuitJsonCopperPourBuilder.mjs'
-import { PcbScene3dCircuitJsonSilkscreenBuilder } from './PcbScene3dCircuitJsonSilkscreenBuilder.mjs'
+import { PcbScene3dCircuitJsonCopperTextBuilder } from './PcbScene3dCircuitJsonCopperTextBuilder.mjs'
+import { PcbScene3dCircuitJsonSilkscreenDetailBuilder } from './PcbScene3dCircuitJsonSilkscreenDetailBuilder.mjs'
 import { PcbScene3dFootprintBodyBuilder } from './PcbScene3dFootprintBodyBuilder.mjs'
 import { PcbScene3dCircuitJsonLayer } from './PcbScene3dCircuitJsonLayer.mjs'
 import { PcbScene3dCircuitJsonInput } from './PcbScene3dCircuitJsonInput.mjs'
@@ -18,6 +19,7 @@ import { PcbScene3dCircuitJsonSolderPasteBuilder } from './PcbScene3dCircuitJson
 import { CircuitJsonCadModelAssetResolver } from './CircuitJsonCadModelAssetResolver.mjs'
 import { PcbScene3dDescriptorSafeRecord } from './PcbScene3dDescriptorSafeRecord.mjs'
 import { PcbScene3dCircuitJsonModelAsset } from './PcbScene3dCircuitJsonModelAsset.mjs'
+import { PcbScene3dCircuitJsonPadCorner } from './PcbScene3dCircuitJsonPadCorner.mjs'
 
 const DEFAULT_COMPONENT_HEIGHT_MIL = 60
 const RECTANGULAR_PAD_SHAPE = 2
@@ -682,27 +684,34 @@ export class PcbScene3dCircuitJsonAdapter {
             index,
             options
         )
+        const pads = [
+            ...PcbScene3dCircuitJsonAdapter.#buildSmtPads(index),
+            ...PcbScene3dCircuitJsonAdapter.#buildPlatedHoles(index),
+            ...PcbScene3dCircuitJsonAdapter.#buildNonPlatedHoles(index)
+        ]
+        const vias = PcbScene3dCircuitJsonTraceRouteBuilder.buildVias(index)
+        const tracks = [
+            ...PcbScene3dCircuitJsonTraceRouteBuilder.buildTracks(index),
+            ...PcbScene3dCircuitJsonThermalSpokeBuilder.build(index)
+        ]
+        const polygons = PcbScene3dCircuitJsonCopperPourBuilder.build(index)
+        const copperTexts = PcbScene3dCircuitJsonCopperTextBuilder.build(index)
+        const silkscreen = PcbScene3dCircuitJsonSilkscreenDetailBuilder.build(
+            index,
+            { pads, vias, tracks, polygons, copperTexts },
+            options
+        )
 
         return {
-            pads: [
-                ...PcbScene3dCircuitJsonAdapter.#buildSmtPads(index),
-                ...PcbScene3dCircuitJsonAdapter.#buildPlatedHoles(index),
-                ...PcbScene3dCircuitJsonAdapter.#buildNonPlatedHoles(index)
-            ],
-            tracks: [
-                ...PcbScene3dCircuitJsonTraceRouteBuilder.buildTracks(index),
-                ...PcbScene3dCircuitJsonThermalSpokeBuilder.build(index)
-            ],
+            pads,
+            tracks,
             arcs: [],
             fills: [],
-            vias: PcbScene3dCircuitJsonTraceRouteBuilder.buildVias(index),
-            polygons: PcbScene3dCircuitJsonCopperPourBuilder.build(index),
-            copperTexts: [],
+            vias,
+            polygons,
+            copperTexts,
             embeddedFonts: [],
-            silkscreen: PcbScene3dCircuitJsonSilkscreenBuilder.build(
-                index,
-                options
-            ),
+            silkscreen,
             ...(paste ? { paste } : {}),
             drillQuality: PcbScene3dCircuitJsonGeometry.normalizeDrillQuality(
                 options?.boardDrillQuality
@@ -745,11 +754,7 @@ export class PcbScene3dCircuitJsonAdapter {
                 holeDiameter: 0,
                 hasTopSolderMaskOpening: !isBottom && exposesCopper,
                 hasBottomSolderMaskOpening: isBottom && exposesCopper,
-                ...PcbScene3dCircuitJsonAdapter.#roundedPadMetadata(
-                    pad,
-                    size,
-                    isBottom
-                )
+                ...PcbScene3dCircuitJsonPadCorner.metadata(pad, size, isBottom)
             }
             return padDetail
         })
@@ -768,7 +773,7 @@ export class PcbScene3dCircuitJsonAdapter {
                     y: Number(hole?.y || 0)
                 })
                 const size =
-                    PcbScene3dCircuitJsonAdapter.#platedHoleOuterSize(geometry)
+                    PcbScene3dCircuitJsonGeometry.platedHoleOuterSize(geometry)
                 const center = CircuitJsonUnits.pointMmToMil({
                     x: hole?.x,
                     y: hole?.y
@@ -796,6 +801,11 @@ export class PcbScene3dCircuitJsonAdapter {
                     sizeMidY: size.height,
                     sizeBottomX: size.width,
                     sizeBottomY: size.height,
+                    ...PcbScene3dCircuitJsonPadCorner.metadata(
+                        geometry,
+                        size,
+                        null
+                    ),
                     ...PcbScene3dCircuitJsonDrillDetail.fields(drill),
                     holeOffsetX: drill.center.x - center.x,
                     holeOffsetY: drill.center.y - center.y,
@@ -852,68 +862,6 @@ export class PcbScene3dCircuitJsonAdapter {
             height: CircuitJsonUnits.mmToMil(pad?.height, 1)
         }
     }
-
-    /**
-     * Builds rounded-rectangle metadata for pill-shaped SMT pads.
-     * @param {object} pad Pad element.
-     * @param {{ width: number, height: number }} size Pad copper size.
-     * @param {boolean} isBottom True when the pad is on the bottom side.
-     * @returns {object}
-     */
-    static #roundedPadMetadata(pad, size, isBottom) {
-        if (!String(pad?.shape || '').endsWith('pill')) {
-            return {}
-        }
-
-        const cornerRadius =
-            PcbScene3dCircuitJsonAdapter.#roundedPadCornerRadiusPercent(
-                pad,
-                size
-            )
-        return {
-            hasRoundedRect: true,
-            roundedRectShapeTop: isBottom ? null : RECTANGULAR_PAD_SHAPE,
-            roundedRectShapeBottom: isBottom ? RECTANGULAR_PAD_SHAPE : null,
-            cornerRadiusTop: isBottom ? null : cornerRadius,
-            cornerRadiusBottom: isBottom ? cornerRadius : null
-        }
-    }
-
-    /**
-     * Resolves a pill-pad corner radius as a percent of the shortest side.
-     * @param {object} pad Pad element.
-     * @param {{ width: number, height: number }} size Pad copper size.
-     * @returns {number}
-     */
-    static #roundedPadCornerRadiusPercent(pad, size) {
-        const width = CircuitJsonUnits.optionalLength(pad?.width)
-        const height = CircuitJsonUnits.optionalLength(pad?.height)
-        const radius = CircuitJsonUnits.optionalLength(pad?.radius)
-        if (width > 0 && height > 0 && radius > 0) {
-            return Math.min((radius / Math.min(width, height)) * 100, 50)
-        }
-
-        const shortestSide = Math.min(Number(size.width), Number(size.height))
-        const radiusMil = CircuitJsonUnits.mmToMil(pad?.radius, 0)
-        if (shortestSide > 0 && radiusMil > 0) {
-            return Math.min((radiusMil / shortestSide) * 100, 50)
-        }
-
-        return 50
-    }
-
-    /**
-     * Resolves plated-hole copper size from CircuitJSON fields.
-     * @param {object} geometry Shared drilled-primitive geometry.
-     * @returns {{ width: number, height: number }}
-     */
-    static #platedHoleOuterSize(geometry) {
-        return {
-            width: CircuitJsonUnits.mmToMil(geometry?.width, 1),
-            height: CircuitJsonUnits.mmToMil(geometry?.height, 1)
-        }
-    }
-
     /**
      * Resolves the viewer pad shape code.
      * @param {object} pad CircuitJSON pad element.