pcb-scene3d-viewer 1.2.0 → 1.2.1

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.1 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
@@ -57,6 +57,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 +123,7 @@ const controller = new PcbScene3dController(viewportNode, document)
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.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

@@ -163,6 +163,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/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/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.1",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -34,6 +34,7 @@
         "docs/api.md",
         "docs/circuitjson.md",
         "docs/release-notes-v1.2.0.md",
+        "docs/release-notes-v1.2.1.md",
         "docs/model-format.md",
         "docs/testing.md",
         "spec",
@@ -54,7 +55,7 @@
         "check:format": "prettier --check ."
     },
     "dependencies": {
-        "@sunbox/occt-import-js": "^0.0.25",
+        "@sunbox/occt-import-js": "^0.0.28",
         "circuitjson-toolkit": "^1.1.0",
         "earcut": "3.0.2",
         "fflate": "^0.8.2",

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
+        )
     }
 }