pcb-scene3d-viewer 1.3.1 → 1.3.2

package/README.md

@@ -34,6 +34,14 @@ annulus, mixed top/bottom states remain independent, and fully open Gerber vias
 retain the exposed-copper path. See the
 [1.3.1 release notes](docs/release-notes-v1.3.1.md).
 
+Version 1.3.2 applies render-group and component visibility through a
+self-adjusting dependency graph, so persistent runtimes repair only the stage
+affected by a known toggle or structural revision. It also keeps tented copper
+below mask surfaces, avoids duplicate pad barrels for filtered vias, and
+short-circuits non-subdividing copper-fill clipping without changing its
+observable geometry. See the
+[1.3.2 release notes](docs/release-notes-v1.3.2.md).
+
 ## CircuitJSON 1.1 convergence
 
 Version 1.2.2 accepts the common document and prepared-context shapes returned
@@ -142,6 +150,7 @@ const controller = new PcbScene3dController(viewportNode, document)
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.md)
+- [1.3.2 release notes](docs/release-notes-v1.3.2.md)
 - [1.3.1 release notes](docs/release-notes-v1.3.1.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)

package/docs/api.md

@@ -165,10 +165,26 @@ traversal, absolute paths, and URL schemes are never attached implicitly.
 
 ## Runtime
 
+### `PcbScene3dVisibilityGraph`
+
+Applies render-group visibility and per-component visibility as two ordered
+self-adjusting computations. `apply(state, changedPaths)` starts at readers of
+the supplied toggle or revision roots, reuses unaffected effects, and returns
+the stage result map with each stage's `recomputed` flag. A null change set is
+conservative and repairs both stages. `clear()` reclaims stored traces.
+
+The public root and `/scene3d` entrypoint also re-export the canonical
+`SelfAdjustingComputation` identity from `circuitjson-toolkit`.
+
 ### `new PcbScene3dRuntime(viewportNode, sceneDescription, hooks?)`
 
 Creates the Three.js scene in a browser viewport.
 
+The persistent runtime routes toggle, selection, hidden-component, and model
+topology changes through `PcbScene3dVisibilityGraph`. Changes within mutable
+maps and sets use explicit structural revision roots so identity-stable
+containers cannot cause stale visibility reuse.
+
 Hooks:
 
 - `setDiagnostics(messages)`: receives user-facing diagnostics.

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

@@ -0,0 +1,39 @@
+# pcb-scene3d-viewer 1.3.2
+
+Version 1.3.2 adds persistent self-adjusting visibility propagation and fixes
+several general copper, via, and solder-mask interactions. The changes derive
+from scene topology and authored surface state rather than source filenames or
+project-specific rules.
+
+## Incremental visibility
+
+- `PcbScene3dVisibilityGraph` applies render-group visibility and component
+  visibility as two ordered computations backed by the canonical
+  `SelfAdjustingComputation` runtime from `circuitjson-toolkit` 1.4.1.
+- Known toggle paths repair only render-group effects. Selection,
+  hidden-component, and identity-stable map/set mutations advance an explicit
+  component revision and repair only component effects.
+- Unknown topology changes conservatively repair both stages, and runtime
+  disposal explicitly reclaims retained traces and reverse-reader edges.
+- The package root and `/scene3d` entrypoint export both the canonical runtime
+  identity and the visibility graph.
+
+## Copper and mask correctness
+
+- Tented via faces no longer carry exposed copper geometry through the rendered
+  solder-mask surface. Fully open vias keep their full span, one-sided tenting
+  retains only the exposed half, and fully tented vias retain mask treatment
+  without a visible face-spanning copper annulus.
+- Filtered tented vias still participate in plated-hole identity checks, so a
+  matching through-hole pad cannot create a duplicate copper barrel.
+- Copper-fill clipping with partial subdivision disabled returns as soon as an
+  uncovered sample proves that a triangle must be kept, while fully sampled
+  triangles still use exact boundary crossing checks.
+
+## Verification
+
+- Tests cover stage-level recomputation, conservative invalidation,
+  from-scratch visibility consistency, one- and two-sided tenting, duplicate
+  barrel prevention, and non-subdividing fill overlap behavior.
+- Release gates include the complete package suite, exact-geometry and context
+  asset benchmarks, formatting, and npm package dry run.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.3.1",
+    "version": "1.3.2",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -38,6 +38,7 @@
         "docs/release-notes-v1.2.2.md",
         "docs/release-notes-v1.3.0.md",
         "docs/release-notes-v1.3.1.md",
+        "docs/release-notes-v1.3.2.md",
         "docs/model-format.md",
         "docs/testing.md",
         "spec",
@@ -59,7 +60,7 @@
     },
     "dependencies": {
         "@sunbox/occt-import-js": "^0.0.28",
-        "circuitjson-toolkit": "^1.2.0",
+        "circuitjson-toolkit": "^1.4.1",
         "earcut": "3.0.2",
         "fflate": "^0.8.2",
         "polygon-clipping": "^0.15.7",

package/spec/library-scope.md

@@ -12,6 +12,8 @@ scene descriptions.
   from canonical bytes, session files, or explicitly enabled URLs.
 - Camera presets, view compensation, selection styling, picking, and visibility
   toggles.
+- Ordered self-adjusting render-group and per-component visibility propagation
+  backed by the canonical `circuitjson-toolkit` runtime.
 - Optional DOM shell/controller helpers for hosts that want ready-made scene
   chrome.
 - ZIP export of resolved component model assets.

package/src/PcbScene3dCopperDetailFilter.mjs

@@ -140,7 +140,8 @@ export class PcbScene3dCopperDetailFilter {
 
         return PcbScene3dCopperDetailFilter.#appendPadBarrelSpecs(
             vias,
-            detail.pads
+            detail.pads,
+            detail.vias
         )
     }
 
@@ -322,12 +323,13 @@ export class PcbScene3dCopperDetailFilter {
      * Appends copper barrels for through-hole pads with copper annuli.
      * @param {any[]} vias Visible via list.
      * @param {any[] | undefined} pads Pad list.
+     * @param {any[] | undefined} sourceVias All parsed vias, including tented vias.
      * @returns {any[]}
      */
-    static #appendPadBarrelSpecs(vias, pads) {
+    static #appendPadBarrelSpecs(vias, pads, sourceVias) {
         const output = [...(vias || [])]
         const seen = new Set(
-            output.map((via) =>
+            [...(sourceVias || []), ...output].map((via) =>
                 PcbScene3dCopperDetailFilter.#platedHoleKey(via)
             )
         )

package/src/PcbScene3dCopperFillAreaClipper.mjs

@@ -127,10 +127,17 @@ export class PcbScene3dCopperFillAreaClipper {
             options
         )
         const coverage =
-            PcbScene3dCopperFillAreaClipper.#resolveTriangleCoverage(
-                triangle,
-                areas
+            PcbScene3dCopperFillAreaClipper.#shouldSubdividePartialTriangles(
+                options
             )
+                ? PcbScene3dCopperFillAreaClipper.#resolveTriangleCoverage(
+                      triangle,
+                      areas
+                  )
+                : PcbScene3dCopperFillAreaClipper.#resolveNonSubdividingCoverage(
+                      triangle,
+                      areas
+                  )
 
         if (coverage === 'none') {
             PcbScene3dCopperFillAreaClipper.#appendTriangle(positions, triangle)
@@ -194,6 +201,39 @@ export class PcbScene3dCopperFillAreaClipper {
         return options?.subdividePartialTriangles !== false
     }
 
+    /**
+     * Resolves coverage when partial triangles are kept without subdivision.
+     * Partial and uncovered triangles have the same observable keep result in
+     * this mode, so the first uncovered sample can return without querying area
+     * boundaries. Fully sampled triangles still require the exact boundary
+     * predicate to distinguish complete coverage from a crossing.
+     * @param {{ x: number, y: number }[]} triangle Triangle points.
+     * @param {object[]} areas Filled copper areas.
+     * @returns {'none' | 'full'}
+     */
+    static #resolveNonSubdividingCoverage(triangle, areas) {
+        const samples = [
+            triangle[0],
+            triangle[1],
+            triangle[2],
+            PcbScene3dCopperFillAreaClipper.#centroid(triangle)
+        ]
+        for (const point of samples) {
+            if (
+                !PcbScene3dCopperFillAreaClipper.#isPointInAnyArea(point, areas)
+            ) {
+                return 'none'
+            }
+        }
+
+        return PcbScene3dCopperFillAreaClipper.#triangleCrossesAnyBoundary(
+            triangle,
+            areas
+        )
+            ? 'none'
+            : 'full'
+    }
+
     /**
      * Resolves whether a triangle is outside, inside, or crossing filled areas.
      * @param {{ x: number, y: number }[]} triangle Triangle points.

package/src/PcbScene3dRuntime.mjs

@@ -18,7 +18,6 @@ import { PcbScene3dFallbackVisibility } from './PcbScene3dFallbackVisibility.mjs
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
 import { PcbScene3dModelSearchPlacement } from './PcbScene3dModelSearchPlacement.mjs'
 import { PcbScene3dPresetState } from './PcbScene3dPresetState.mjs'
-import { PcbScene3dRenderGroupVisibility } from './PcbScene3dRenderGroupVisibility.mjs'
 import { PcbScene3dRenderScheduler } from './PcbScene3dRenderScheduler.mjs'
 import { PcbScene3dRuntimeBoardMeshes } from './PcbScene3dRuntimeBoardMeshes.mjs'
 import { PcbScene3dRuntimeHelpers } from './PcbScene3dRuntimeHelpers.mjs'
@@ -29,6 +28,7 @@ import { PcbScene3dSelectionStyler } from './PcbScene3dSelectionStyler.mjs'
 import { PcbScene3dStaticBodyFactory } from './PcbScene3dStaticBodyFactory.mjs'
 import { PcbScene3dViewportResize } from './PcbScene3dViewportResize.mjs'
 import { PcbScene3dViewScale } from './PcbScene3dViewScale.mjs'
+import { PcbScene3dVisibilityGraph } from './PcbScene3dVisibilityGraph.mjs'
 const COPPER_HALF_MIL = PcbScene3dCopperFactory.visualHalfThicknessMil()
 const Z_MIL = {
     paste: COPPER_HALF_MIL + 0.28,
@@ -74,6 +74,7 @@ export class PcbScene3dRuntime {
     #resolveReadyPromise
     #hasSettledReady
     #renderScheduler
+    #visibilityGraph
     /**
      * @param {HTMLElement} viewportNode
      * @param {any} sceneDescription Scene description or CircuitJSON model.
@@ -127,6 +128,7 @@ export class PcbScene3dRuntime {
                 this.#render()
             }
         })
+        this.#visibilityGraph = new PcbScene3dVisibilityGraph()
         this.#resolveReadyPromise = null
         this.#readyPromise = new Promise((resolve) => {
             this.#resolveReadyPromise = resolve
@@ -165,7 +167,7 @@ export class PcbScene3dRuntime {
             return
         }
         this.#toggles[toggleName] = enabled
-        this.#applyToggleVisibility()
+        this.#applyToggleVisibility([['toggles', toggleName]])
         this.#render()
     }
     /** @param {string} designator */
@@ -183,7 +185,7 @@ export class PcbScene3dRuntime {
         ) {
             return
         }
-        this.#applyToggleVisibility()
+        this.#applyToggleVisibility([['componentRevision']])
         this.#updateSelectionMarker()
         this.#render()
     }
@@ -243,6 +245,7 @@ export class PcbScene3dRuntime {
         this.#selectionRoots.clear()
         this.#hiddenComponentDesignators.clear()
         this.#componentAdjustmentRegistry.clear()
+        this.#visibilityGraph.clear()
         this.#fallbackBodyRoots.clear()
         this.#loadedExternalModelDesignators.clear()
         this.#modelSearchExternalModelRoots.clear()
@@ -771,28 +774,24 @@ export class PcbScene3dRuntime {
         this.#render()
     }
 
-    /** @returns {void} */
-    #applyToggleVisibility() {
-        PcbScene3dRenderGroupVisibility.apply({
-            groups: this.#groups,
-            toggles: this.#toggles,
-            fallbackBodyRoots: this.#fallbackBodyRoots,
-            loadedExternalModelDesignators:
-                this.#loadedExternalModelDesignators,
-            modelSearchExternalModelRoots: this.#modelSearchExternalModelRoots,
-            hasLoadedBoardAssemblyModel: this.#hasLoadedBoardAssemblyModel
-        })
-        PcbScene3dComponentVisibility.apply({
-            selectionRoots: this.#selectionRoots,
-            selectedDesignator: this.#selectedDesignator,
-            hiddenDesignators: this.#hiddenComponentDesignators,
-            fallbackBodyRoots: this.#fallbackBodyRoots,
-            loadedExternalModelDesignators:
-                this.#loadedExternalModelDesignators,
-            modelSearchExternalModelRoots: this.#modelSearchExternalModelRoots,
-            toggles: this.#toggles,
-            hasLoadedBoardAssemblyModel: this.#hasLoadedBoardAssemblyModel
-        })
+    /** @param {PropertyKey[][] | null} [changedPaths] @returns {void} */
+    #applyToggleVisibility(changedPaths = null) {
+        this.#visibilityGraph.apply(
+            {
+                groups: this.#groups,
+                toggles: this.#toggles,
+                fallbackBodyRoots: this.#fallbackBodyRoots,
+                loadedExternalModelDesignators:
+                    this.#loadedExternalModelDesignators,
+                modelSearchExternalModelRoots:
+                    this.#modelSearchExternalModelRoots,
+                hasLoadedBoardAssemblyModel: this.#hasLoadedBoardAssemblyModel,
+                selectionRoots: this.#selectionRoots,
+                selectedDesignator: this.#selectedDesignator,
+                hiddenDesignators: this.#hiddenComponentDesignators
+            },
+            changedPaths
+        )
     }
 
     /**
@@ -949,7 +948,7 @@ export class PcbScene3dRuntime {
             SELECTION_HIGHLIGHT_COLOR
         )
         this.#selectedDesignator = normalizedDesignator
-        this.#applyToggleVisibility()
+        this.#applyToggleVisibility([['componentRevision']])
         this.#updateSelectionMarker()
         this.#render()
     }

package/src/PcbScene3dViaFactory.mjs

@@ -39,27 +39,30 @@ export class PcbScene3dViaFactory {
             const renderMode = PcbScene3dViaLayerSpan.renderMode(via)
             if (!renderMode) return
 
-            const geometry = PcbScene3dViaFactory.#resolveGeometry(
-                THREE,
-                geometryCache,
-                via,
-                thicknessMil,
-                renderMode
-            )
-            const mesh = new THREE.Mesh(geometry, copperMaterial)
             const point = normalizeBoardPoint(
                 Number(via?.x || 0),
                 Number(via?.y || 0)
             )
-            mesh.position.set(
-                point.x,
-                point.y,
-                PcbScene3dViaFactory.#centerZ(renderMode, thicknessMil)
+            const copperSpans = PcbScene3dViaFactory.#resolveCopperSpans(
+                via,
+                renderMode,
+                thicknessMil,
+                Boolean(options?.surfaceMaterial)
             )
-            if (geometry.type === 'CylinderGeometry') {
-                mesh.rotation.x = Math.PI / 2
+            for (const copperSpan of copperSpans) {
+                const geometry = PcbScene3dViaFactory.#resolveGeometry(
+                    THREE,
+                    geometryCache,
+                    via,
+                    copperSpan.depth
+                )
+                const mesh = new THREE.Mesh(geometry, copperMaterial)
+                mesh.position.set(point.x, point.y, copperSpan.centerZ)
+                if (geometry.type === 'CylinderGeometry') {
+                    mesh.rotation.x = Math.PI / 2
+                }
+                group.add(mesh)
             }
-            group.add(mesh)
             PcbScene3dViaFactory.#appendMaskSurfaceMeshes(
                 THREE,
                 group,
@@ -75,6 +78,57 @@ export class PcbScene3dViaFactory {
         return group
     }
 
+    /**
+     * Resolves visible copper spans without carrying an open-side barrel
+     * through a solder-mask-covered board face.
+     * @param {object} via Via primitive.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @param {boolean} hasSurfaceMask Whether mask surface geometry is rendered.
+     * @returns {{ depth: number, centerZ: number }[]}
+     */
+    static #resolveCopperSpans(via, renderMode, thicknessMil, hasSurfaceMask) {
+        const fullSpan = {
+            depth: PcbScene3dViaFactory.#geometryDepth(
+                renderMode,
+                thicknessMil
+            ),
+            centerZ: PcbScene3dViaFactory.#centerZ(renderMode, thicknessMil)
+        }
+        if (!hasSurfaceMask) {
+            return [fullSpan]
+        }
+
+        if (renderMode === 'top') {
+            return PcbScene3dViaFactory.#isSideTented(via, 'top')
+                ? []
+                : [fullSpan]
+        }
+        if (renderMode === 'bottom') {
+            return PcbScene3dViaFactory.#isSideTented(via, 'bottom')
+                ? []
+                : [fullSpan]
+        }
+
+        const isTopTented = PcbScene3dViaFactory.#isSideTented(via, 'top')
+        const isBottomTented = PcbScene3dViaFactory.#isSideTented(via, 'bottom')
+        if (isTopTented && isBottomTented) {
+            return []
+        }
+        if (!isTopTented && !isBottomTented) {
+            return [fullSpan]
+        }
+
+        const halfDepth = fullSpan.depth / 2
+        const centerDistance = halfDepth / 2
+        return [
+            {
+                depth: halfDepth,
+                centerZ: isTopTented ? -centerDistance : centerDistance
+            }
+        ]
+    }
+
     /**
      * Resolves the via material.
      * @param {any} THREE
@@ -222,23 +276,12 @@ export class PcbScene3dViaFactory {
      * @param {any} THREE
      * @param {Map<string, any>} geometryCache
      * @param {{ diameter?: number, holeDiameter?: number, barrelOnly?: boolean }} via
-     * @param {number} thicknessMil
-     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {number} depth Copper span depth in mil.
      * @returns {any}
      */
-    static #resolveGeometry(
-        THREE,
-        geometryCache,
-        via,
-        thicknessMil,
-        renderMode
-    ) {
+    static #resolveGeometry(THREE, geometryCache, via, depth) {
         const outerRadius = Math.max(Number(via?.diameter || 0) / 2, 1.2)
         const holeDiameter = Math.max(Number(via?.holeDiameter || 0), 0)
-        const depth = PcbScene3dViaFactory.#geometryDepth(
-            renderMode,
-            thicknessMil
-        )
         const isBarrelOnly = Boolean(via?.barrelOnly)
         const cacheKey = [
             isBarrelOnly ? 'barrel' : 'annulus',

package/src/PcbScene3dVisibilityGraph.mjs

@@ -0,0 +1,102 @@
+import { SelfAdjustingComputation } from 'circuitjson-toolkit'
+import { PcbScene3dComponentVisibility } from './PcbScene3dComponentVisibility.mjs'
+import { PcbScene3dRenderGroupVisibility } from './PcbScene3dRenderGroupVisibility.mjs'
+
+/**
+ * Repairs ordered PCB visibility effects from explicit mutable-state changes.
+ */
+export class PcbScene3dVisibilityGraph {
+    /** @type {SelfAdjustingComputation} */
+    #computation
+
+    /** @type {number} */
+    #groupRevision
+
+    /** @type {number} */
+    #componentRevision
+
+    /**
+     * Creates an empty visibility trace graph.
+     */
+    constructor() {
+        this.#computation = new SelfAdjustingComputation()
+        this.#groupRevision = 0
+        this.#componentRevision = 0
+    }
+
+    /**
+     * Applies affected visibility computations in observable effect order.
+     * Revision paths represent mutations inside otherwise atomic maps and sets.
+     * A null change set conservatively advances both structural revisions.
+     * @param {object} state Current visibility state.
+     * @param {PropertyKey[][] | null} changedPaths Changed roots or null when unknown.
+     * @returns {Map<string, { value: any, recomputed: boolean }>} Stage results.
+     */
+    apply(state, changedPaths = null) {
+        const normalizedPaths = this.#advanceRevisions(changedPaths)
+        const input = {
+            ...state,
+            groupRevision: this.#groupRevision,
+            componentRevision: this.#componentRevision
+        }
+        return this.#computation.propagate(input, normalizedPaths, [
+            {
+                name: 'render-groups',
+                computation: (current) => {
+                    void current.groupRevision
+                    PcbScene3dRenderGroupVisibility.apply(current)
+                }
+            },
+            {
+                name: 'components',
+                computation: (current) => {
+                    void current.componentRevision
+                    PcbScene3dComponentVisibility.apply(current)
+                }
+            }
+        ])
+    }
+
+    /**
+     * Removes all stored visibility traces and reverse-reader edges.
+     * @returns {void}
+     */
+    clear() {
+        this.#computation.clear()
+        this.#groupRevision = 0
+        this.#componentRevision = 0
+    }
+
+    /**
+     * Advances revision roots named by a visibility change set.
+     * @param {PropertyKey[][] | null} changedPaths Changed roots or null.
+     * @returns {PropertyKey[][]} Conservative normalized change paths.
+     */
+    #advanceRevisions(changedPaths) {
+        const normalizedPaths =
+            changedPaths === null
+                ? [['groupRevision'], ['componentRevision']]
+                : changedPaths
+        if (!Array.isArray(normalizedPaths)) {
+            throw new TypeError(
+                'Visibility change sets must be arrays of property paths.'
+            )
+        }
+        const revisionRoots = new Set()
+        normalizedPaths.forEach((path) => {
+            if (!Array.isArray(path)) {
+                throw new TypeError(
+                    'Visibility change-set entries must be property paths.'
+                )
+            }
+            revisionRoots.add(path[0])
+        })
+        if (revisionRoots.has('groupRevision')) {
+            this.#groupRevision += 1
+        }
+        if (revisionRoots.has('componentRevision')) {
+            this.#componentRevision += 1
+        }
+        return normalizedPaths
+    }
+}

package/src/scene3d.mjs

@@ -1,3 +1,4 @@
+export { SelfAdjustingComputation } from 'circuitjson-toolkit'
 export { PcbModelArchiveExporter } from './PcbModelArchiveExporter.mjs'
 export { PcbAssemblyBoardSubstrateBuilder } from './PcbAssemblyBoardSubstrateBuilder.mjs'
 export { PcbAssemblyExportCoordinateFrame } from './PcbAssemblyExportCoordinateFrame.mjs'
@@ -57,4 +58,5 @@ export { PcbScene3dViaFactory } from './PcbScene3dViaFactory.mjs'
 export { PcbScene3dViewCompensation } from './PcbScene3dViewCompensation.mjs'
 export { PcbScene3dViewScale } from './PcbScene3dViewScale.mjs'
 export { PcbScene3dViewportResize } from './PcbScene3dViewportResize.mjs'
+export { PcbScene3dVisibilityGraph } from './PcbScene3dVisibilityGraph.mjs'
 export { PcbScene3dWorkerClient } from './PcbScene3dWorkerClient.mjs'