pcb-scene3d-viewer 1.2.0 → 1.2.2

package/NOTICE.md

@@ -27,10 +27,13 @@ required by the applicable license:
 For applications with an "About", "Licenses", or "Legal Notices" screen,
 include a reasonable reference to this project and its original author there.
 
-Vendored and third-party components retain their own notices and license terms.
-In particular, preserve the notices in:
-
-- `src/vendor/occt-import-js/dist/license.occt-import-js.txt`;
-- `src/vendor/occt-import-js/dist/license.occt.txt`.
+Third-party package dependencies retain their own notices and license terms.
+In particular, distributions that include `@sunbox/occt-import-js` and Open
+CASCADE Technology must preserve the notices shipped by that installed package
+in:
+
+- `node_modules/@sunbox/occt-import-js/dist/license.occt-import-js.txt`;
+- `node_modules/@sunbox/occt-import-js/dist/license.occt.txt`;
+- `node_modules/@sunbox/occt-import-js/dist/OCCT_LGPL_EXCEPTION.txt`.
 
 Package-manager dependencies retain their own licenses.

package/README.md

@@ -24,7 +24,7 @@ browser-based ECAD tools.
 
 ## CircuitJSON 1.1 convergence
 
-Version 1.2.0 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
@@ -57,6 +64,13 @@ stay on the main model origin; `authHeadersForUrl` is the explicit per-URL
 override. The model ZIP exporter uses the same policy and writes each raw model
 under its original source basename with safe GLTF, OBJ, and WRL companions.
 
+STEP loading uses the installed `@sunbox/occt-import-js` package directly. Its
+package-owned worker is reused for browser imports, while runtimes without Web
+Workers dynamically import the same ESM factory. Hosts only need to serve the
+package `dist/` directory at
+`/node_modules/@sunbox/occt-import-js/dist/`; no copied runtime, global script,
+or host-owned worker is required.
+
 ## Install
 
 ```bash
@@ -116,6 +130,8 @@ 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)
 - [Testing](docs/testing.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.
@@ -163,6 +171,14 @@ the model, preventing implicit texture networking. STL, OBJ, GLTF, and GLB use
 the shared faceted mesh pipeline so runtime and assembly export preserve the
 same units, material color, opacity, and vertex-color behavior.
 
+STEP imports resolve `occt-import-js.js`, `occt-import-js.wasm`, and
+`occt-import-js-worker.js` from the installed `@sunbox/occt-import-js` package.
+The package worker is persistent and serialized per loader. When Web Workers
+are unavailable, the viewer dynamically imports the ESM factory directly; it
+does not inject a classic script or depend on a global factory. Worker transfer
+uses a loader-owned byte snapshot, and rejected ESM initialization is evicted
+so callers retain their input and can retry transient failures.
+
 Static `authHeaders` are sent only to the main model origin. A host that
 intentionally authorizes another origin can return headers from
 `authHeadersForUrl(url, { mainUrl, sameOrigin, label })`. Each fetch scope

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.1.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# PCB Scene3D Viewer 1.2.1
+
+Version 1.2.1 removes the host-specific OCCT integration layer and consumes the
+installed importer package directly.
+
+## Compatibility changes
+
+- Requires `@sunbox/occt-import-js ^0.0.28`.
+- STEP workers now load from the scoped package path
+  `/node_modules/@sunbox/occt-import-js/dist/occt-import-js-worker.js`.
+- The no-worker path dynamically imports the package ESM factory and resolves
+  its WASM through the same package directory.
+- Classic script injection, global `occtimportjs` lookup, unscoped package
+  aliases, and app-vendored importer paths are no longer used.
+- The package worker stays persistent across imports and failed model or worker
+  requests remain retryable through the existing cache/reset behavior.
+- Byte-backed model inputs are copied into loader ownership before worker
+  transfer, so the caller's typed arrays and buffers are never detached.
+- Rejected no-worker ESM initialization attempts are evicted, allowing a later
+  load to recover from transient module or WASM delivery failures.
+
+Hosts serving browser dependencies must expose the installed package `dist/`
+directory byte-for-byte at
+`/node_modules/@sunbox/occt-import-js/dist/`. No copied JavaScript, WASM, or
+custom worker is required.
+
+## Performance
+
+The viewer consumes the optimized 0.0.28 importer build and continues to retain
+typed mesh arrays, compact face-color runs, persistent worker reuse, and parsed
+model caching. This avoids script duplication and keeps large STEP payloads off
+the main browser thread when workers are available.

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/docs/testing.md

@@ -12,6 +12,7 @@ The test suite covers:
   copper, and silkscreen;
 - runtime camera, preset, resizing, selection, and visibility behavior;
 - external STEP/STP, WRL/VRML, STL, OBJ, GLTF/GLB, and 3MF live loading;
+- direct ESM and package-owned worker loading for the installed OCCT importer;
 - model ZIP archive export;
 - optional shell renderer and CSS contract;
 - worker-client request routing.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.2.0",
+    "version": "1.2.2",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -34,6 +34,8 @@
         "docs/api.md",
         "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",
@@ -54,8 +56,8 @@
         "check:format": "prettier --check ."
     },
     "dependencies": {
-        "@sunbox/occt-import-js": "^0.0.25",
-        "circuitjson-toolkit": "^1.1.0",
+        "@sunbox/occt-import-js": "^0.0.28",
+        "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.

package/src/PcbScene3dOcctImporterLoader.mjs

@@ -0,0 +1,79 @@
+/**
+ * Loads the ESM-shaped OCCT browser package without relying on global scripts.
+ */
+export class PcbScene3dOcctImporterLoader {
+    /** @type {Map<string, Promise<Record<string, any>>>} */
+    static #cachedImports = new Map()
+
+    /**
+     * Imports and instantiates the OCCT module from its installed package.
+     * @param {{ resolveAssetUrl: (fileName: string) => string, loadModule?: (url: string) => Promise<Record<string, any>> }} options Loader options.
+     * @returns {Promise<Record<string, any>>} Initialized OCCT importer.
+     */
+    static async load(options) {
+        const resolveAssetUrl = options?.resolveAssetUrl
+        if (typeof resolveAssetUrl !== 'function') {
+            throw new TypeError('OCCT asset URL resolver is required.')
+        }
+
+        const loadModule =
+            options?.loadModule ||
+            ((url) => PcbScene3dOcctImporterLoader.#importModule(url))
+        const module = await loadModule(resolveAssetUrl('occt-import-js.js'))
+        const factory = module?.default || module?.occtimportjs
+        if (typeof factory !== 'function') {
+            throw new Error('occt-import-js did not export a factory.')
+        }
+
+        return await factory({
+            locateFile: (fileName) => resolveAssetUrl(fileName)
+        })
+    }
+
+    /**
+     * Loads one importer per resolved module URL and evicts rejected attempts.
+     * @param {{ resolveAssetUrl: (fileName: string) => string, loadModule?: (url: string) => Promise<Record<string, any>> }} options Loader options.
+     * @returns {Promise<Record<string, any>>} Cached initialized OCCT importer.
+     */
+    static async loadCached(options) {
+        const resolveAssetUrl = options?.resolveAssetUrl
+        if (typeof resolveAssetUrl !== 'function') {
+            throw new TypeError('OCCT asset URL resolver is required.')
+        }
+
+        const moduleUrl = resolveAssetUrl('occt-import-js.js')
+        let pendingImport =
+            PcbScene3dOcctImporterLoader.#cachedImports.get(moduleUrl)
+        if (!pendingImport) {
+            pendingImport = PcbScene3dOcctImporterLoader.load(options)
+            PcbScene3dOcctImporterLoader.#cachedImports.set(
+                moduleUrl,
+                pendingImport
+            )
+        }
+
+        try {
+            return await pendingImport
+        } catch (error) {
+            if (
+                PcbScene3dOcctImporterLoader.#cachedImports.get(moduleUrl) ===
+                pendingImport
+            ) {
+                PcbScene3dOcctImporterLoader.#cachedImports.delete(moduleUrl)
+            }
+            throw error
+        }
+    }
+
+    /**
+     * Dynamically imports one browser module URL.
+     * @param {string} url Module URL.
+     * @returns {Promise<Record<string, any>>} Imported namespace.
+     */
+    static async #importModule(url) {
+        return await import(url)
+    }
+}
+
+Object.freeze(PcbScene3dOcctImporterLoader.prototype)
+Object.freeze(PcbScene3dOcctImporterLoader)

package/src/PcbScene3dStepLoader.mjs

@@ -1,18 +1,10 @@
 import { PcbScene3dModelIdentity } from './PcbScene3dModelIdentity.mjs'
+import { PcbScene3dOcctImporterLoader } from './PcbScene3dOcctImporterLoader.mjs'
 
 /**
  * Browser-side STEP mesh loader backed by occt-import-js.
  */
 export class PcbScene3dStepLoader {
-    /** @type {(() => Promise<{ ReadStepFile?: (content: Uint8Array, params: Record<string, any> | null) => any }>) | null} */
-    static #browserImporterLoader
-
-    /** @type {Promise<{ ReadStepFile?: (content: Uint8Array, params: Record<string, any> | null) => any }> | null} */
-    static #browserImporterPromise
-
-    /** @type {Promise<void> | null} */
-    static #browserScriptPromise
-
     /** @type {() => Promise<{ ReadStepFile?: (content: Uint8Array, params: Record<string, any> | null) => any }>} */
     #importerLoader
 
@@ -182,7 +174,7 @@ export class PcbScene3dStepLoader {
 
     /**
      * Reads one importer result through the loader-owned persistent worker.
-     * Requests are serialized because the vendored worker does not echo a
+     * Requests are serialized because the package worker does not echo a
      * request id back in its response payload.
      * @param {Uint8Array} content
      * @returns {Promise<any>}
@@ -347,20 +339,20 @@ export class PcbScene3dStepLoader {
             return null
         }
         if (value instanceof Uint8Array) {
-            return value
+            return new Uint8Array(value)
         }
         if (value instanceof ArrayBuffer) {
-            return new Uint8Array(value)
+            return new Uint8Array(value.slice(0))
         }
         if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
             return new Uint8Array(
                 value.buffer,
                 value.byteOffset,
                 value.byteLength
-            )
+            ).slice()
         }
         if (typeof value.arrayBuffer === 'function') {
-            return new Uint8Array(await value.arrayBuffer())
+            return new Uint8Array(await value.arrayBuffer()).slice()
         }
         return null
     }
@@ -599,39 +591,10 @@ export class PcbScene3dStepLoader {
      * @returns {Promise<{ ReadStepFile?: (content: Uint8Array, params: Record<string, any> | null) => any }>}
      */
     static async #loadBrowserImporter() {
-        if (!PcbScene3dStepLoader.#browserImporterLoader) {
-            PcbScene3dStepLoader.#browserImporterLoader = async () => {
-                if (
-                    typeof window === 'undefined' ||
-                    typeof document === 'undefined'
-                ) {
-                    throw new Error(
-                        'Browser STEP importer requires window and document.'
-                    )
-                }
-
-                await PcbScene3dStepLoader.#ensureBrowserScript()
-
-                const factory = globalThis.occtimportjs
-                if (typeof factory !== 'function') {
-                    throw new Error(
-                        'occt-import-js did not register a browser factory.'
-                    )
-                }
-
-                return await factory({
-                    locateFile: (fileName) =>
-                        PcbScene3dStepLoader.#resolveVendorAssetUrl(fileName)
-                })
-            }
-        }
-
-        if (!PcbScene3dStepLoader.#browserImporterPromise) {
-            PcbScene3dStepLoader.#browserImporterPromise =
-                PcbScene3dStepLoader.#browserImporterLoader()
-        }
-
-        return await PcbScene3dStepLoader.#browserImporterPromise
+        return await PcbScene3dOcctImporterLoader.loadCached({
+            resolveAssetUrl: (fileName) =>
+                PcbScene3dStepLoader.#resolveImporterAssetUrl(fileName)
+        })
     }
 
     /**
@@ -645,77 +608,24 @@ export class PcbScene3dStepLoader {
 
         return () =>
             new globalThis.Worker(
-                PcbScene3dStepLoader.#resolveVendorAssetUrl(
+                PcbScene3dStepLoader.#resolveImporterAssetUrl(
                     'occt-import-js-worker.js'
                 )
             )
     }
 
     /**
-     * Ensures the browser importer script has been loaded once.
-     * @returns {Promise<void>}
-     */
-    static async #ensureBrowserScript() {
-        if (PcbScene3dStepLoader.#browserScriptPromise) {
-            return await PcbScene3dStepLoader.#browserScriptPromise
-        }
-
-        PcbScene3dStepLoader.#browserScriptPromise = new Promise(
-            (resolve, reject) => {
-                const existingScript = document.querySelector(
-                    'script[data-occt-import-js]'
-                )
-                if (existingScript) {
-                    existingScript.addEventListener('load', () => resolve(), {
-                        once: true
-                    })
-                    existingScript.addEventListener(
-                        'error',
-                        () =>
-                            reject(
-                                new Error(
-                                    'STEP importer script failed to load.'
-                                )
-                            ),
-                        { once: true }
-                    )
-                    if (typeof globalThis.occtimportjs === 'function') {
-                        resolve()
-                    }
-                    return
-                }
-
-                const script = document.createElement('script')
-                script.async = true
-                script.dataset.occtImportJs = 'true'
-                script.src =
-                    PcbScene3dStepLoader.#resolveVendorAssetUrl(
-                        'occt-import-js.js'
-                    )
-                script.addEventListener('load', () => resolve(), { once: true })
-                script.addEventListener(
-                    'error',
-                    () =>
-                        reject(
-                            new Error('STEP importer script failed to load.')
-                        ),
-                    { once: true }
-                )
-                document.head.append(script)
-            }
-        )
-
-        return await PcbScene3dStepLoader.#browserScriptPromise
-    }
-
-    /**
-     * Resolves one vendored importer asset URL with the current app version.
+     * Resolves one installed importer asset URL with the current app version.
      * @param {string} fileName
      * @returns {string}
      */
-    static #resolveVendorAssetUrl(fileName) {
+    static #resolveImporterAssetUrl(fileName) {
         const versionKey = new URL(import.meta.url).searchParams.get('v') || ''
         const suffix = versionKey ? '?v=' + encodeURIComponent(versionKey) : ''
-        return '/vendor/occt-import-js/dist/' + String(fileName || '') + suffix
+        return (
+            '/node_modules/@sunbox/occt-import-js/dist/' +
+            String(fileName || '') +
+            suffix
+        )
     }
 }