pcb-scene3d-viewer 1.3.0 → 1.3.2

package/README.md

@@ -28,6 +28,20 @@ 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).
 
+Version 1.3.1 renders side-specific tented Gerber vias without recoloring the
+plated drill wall. Covered surfaces receive a solder-mask ring above the copper
+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
@@ -136,6 +150,8 @@ 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)
 - [1.2.1 release notes](docs/release-notes-v1.2.1.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/model-format.md

@@ -220,3 +220,9 @@ Rounded SMT pads set `hasRoundedRect`, the side-specific
 Route-derived vias use the same `detail.vias` shape as standalone vias, and
 surface route segments use `layerId: 1` for top copper or `layerId: 32` for
 bottom copper.
+
+Via surfaces can set `isTentingTop` and `isTentingBottom` independently. A
+truthy field adds a solder-mask ring on that board surface while the plated
+through-hole barrel remains copper. A mixed via therefore renders one covered
+annulus and one exposed annulus; a via with both fields explicitly false stays
+on the exposed-copper path. The source toolkit owns this classification.

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

@@ -0,0 +1,23 @@
+# pcb-scene3d-viewer 1.3.1
+
+Version 1.3.1 renders source-classified via solder mask as a surface treatment
+without replacing the plated copper barrel material.
+
+## Via rendering
+
+- Gerber vias with either `isTentingTop` or `isTentingBottom` use the covered
+  via rendering path; both fields explicitly false retain the exposed path.
+- Each tented board surface receives its own solder-mask ring above the copper
+  annulus. Mixed top/bottom tenting is preserved.
+- The mask ring keeps the authored drill opening clear and leaves the plated
+  through-hole wall copper-colored.
+- Blind and buried surface reachability remains authoritative, so mask geometry
+  is added only where a via actually reaches the corresponding board surface.
+
+## Compatibility and verification
+
+- Existing CircuitJSON default-tenting and explicit-opening behavior is
+  unchanged.
+- Scene, controller, runtime, export, and package entrypoints are unchanged.
+- Tests cover fully tented, mixed, and fully open Gerber classification plus
+  copper-barrel and one-sided mask-ring material routing.

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.0",
+    "version": "1.3.2",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",
@@ -37,6 +37,8 @@
         "docs/release-notes-v1.2.1.md",
         "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",
@@ -58,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
         )
     }
 
@@ -266,24 +267,37 @@ export class PcbScene3dCopperDetailFilter {
      * @returns {any[]}
      */
     static #filterExposedVias(vias, sceneDescription) {
+        if (PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)) {
+            return (vias || []).filter(
+                (via) =>
+                    via?.isTentingTop === false &&
+                    via?.isTentingBottom === false
+            )
+        }
+
         return (vias || []).filter((via) =>
             PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
         )
     }
 
     /**
-     * Keeps KiCad via annuli that are covered by solder mask.
+     * Keeps KiCad and Gerber via annuli that are covered by solder mask.
      * @param {any[] | undefined} vias Via list.
      * @param {object} sceneDescription 3D scene description.
      * @returns {any[]}
      */
     static #filterMaskCoveredVias(vias, sceneDescription) {
-        if (!PcbScene3dCopperDetailFilter.#isKiCadScene(sceneDescription)) {
+        if (
+            !PcbScene3dCopperDetailFilter.#isKiCadScene(sceneDescription) &&
+            !PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)
+        ) {
             return []
         }
 
-        return (vias || []).filter(
-            (via) => !PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
+        return (vias || []).filter((via) =>
+            PcbScene3dCopperDetailFilter.#isGerberScene(sceneDescription)
+                ? PcbScene3dCopperDetailFilter.#isViaExplicitlyTented(via)
+                : !PcbScene3dCopperDetailFilter.#isViaExplicitlyOpen(via)
         )
     }
 
@@ -296,16 +310,26 @@ export class PcbScene3dCopperDetailFilter {
         return via?.isTentingTop === false || via?.isTentingBottom === false
     }
 
+    /**
+     * Checks whether one via explicitly carries mask on either board side.
+     * @param {object} via Via primitive.
+     * @returns {boolean}
+     */
+    static #isViaExplicitlyTented(via) {
+        return via?.isTentingTop === true || via?.isTentingBottom === true
+    }
+
     /**
      * 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)
             )
         )
@@ -487,6 +511,19 @@ export class PcbScene3dCopperDetailFilter {
         )
     }
 
+    /**
+     * Checks whether one scene was built from Gerber fabrication artwork.
+     * @param {object} sceneDescription Scene description.
+     * @returns {boolean}
+     */
+    static #isGerberScene(sceneDescription) {
+        return (
+            String(sceneDescription?.sourceFormat || '')
+                .trim()
+                .toLowerCase() === 'gerber'
+        )
+    }
+
     /**
      * Checks whether one text primitive belongs to a solder-mask layer.
      * @param {object} text Text primitive.

package/src/PcbScene3dCopperDetailGroupBuilder.mjs

@@ -130,7 +130,7 @@ export class PcbScene3dCopperDetailGroupBuilder {
             sceneDescription?.board?.thicknessMil,
             normalizePoint,
             {
-                material: PcbScene3dMaskCoveredCopperMaterial.build(
+                surfaceMaterial: PcbScene3dMaskCoveredCopperMaterial.build(
                     THREE,
                     PcbScene3dCopperDetailGroupBuilder.#coveredCopperMaterialOptions(
                         sceneDescription

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

@@ -9,6 +9,7 @@ export class PcbScene3dViaFactory {
     static #PAD_BARREL_MIN_WALL_MIL = 1.2
     static #PAD_BARREL_WALL_FRACTION = 0.09
     static #SURFACE_COPPER_DEPTH_MIL = 2
+    static #SURFACE_MASK_Z_OFFSET_MIL = 1.3
 
     /**
      * Builds the via mesh group for one scene.
@@ -16,7 +17,7 @@ export class PcbScene3dViaFactory {
      * @param {{ diameter?: number, holeDiameter?: number, x?: number, y?: number, barrelOnly?: boolean, layers?: unknown[], fromLayer?: unknown, toLayer?: unknown, from_layer?: unknown, to_layer?: unknown }[]} vias
      * @param {number} thicknessMil
      * @param {(x: number, y: number) => { x: number, y: number }} normalizeBoardPoint
-     * @param {{ material?: any }} [options]
+     * @param {{ material?: any, surfaceMaterial?: any }} [options]
      * @returns {any}
      */
     static buildGroup(
@@ -27,39 +28,107 @@ export class PcbScene3dViaFactory {
         options = {}
     ) {
         const group = new THREE.Group()
-        const material = PcbScene3dViaFactory.#resolveMaterial(THREE, options)
+        const copperMaterial = PcbScene3dViaFactory.#resolveMaterial(
+            THREE,
+            options
+        )
         const geometryCache = new Map()
+        const surfaceGeometryCache = new Map()
 
         ;(vias || []).forEach((via) => {
             const renderMode = PcbScene3dViaLayerSpan.renderMode(via)
             if (!renderMode) return
 
-            const geometry = PcbScene3dViaFactory.#resolveGeometry(
-                THREE,
-                geometryCache,
-                via,
-                thicknessMil,
-                renderMode
-            )
-            const mesh = new THREE.Mesh(geometry, material)
             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,
+                surfaceGeometryCache,
+                via,
+                renderMode,
+                thicknessMil,
+                point,
+                options?.surfaceMaterial
+            )
         })
 
         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
@@ -79,27 +148,140 @@ export class PcbScene3dViaFactory {
     }
 
     /**
-     * Resolves one reusable via geometry from the via drill spec.
-     * @param {any} THREE
-     * @param {Map<string, any>} geometryCache
-     * @param {{ diameter?: number, holeDiameter?: number, barrelOnly?: boolean }} via
-     * @param {number} thicknessMil
+     * Adds side-specific solder-mask rings above the copper via surface.
+     * @param {any} THREE Three.js namespace.
+     * @param {any} group Output group.
+     * @param {Map<string, any>} geometryCache Surface geometry cache.
+     * @param {object} via Via primitive.
      * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
-     * @returns {any}
+     * @param {number} thicknessMil Board thickness in mil.
+     * @param {{ x: number, y: number }} point Normalized board point.
+     * @param {any | undefined} material Solder-mask material.
+     * @returns {void}
      */
-    static #resolveGeometry(
+    static #appendMaskSurfaceMeshes(
         THREE,
+        group,
         geometryCache,
         via,
+        renderMode,
         thicknessMil,
-        renderMode
+        point,
+        material
     ) {
+        if (!material) {
+            return
+        }
+
+        const geometry = PcbScene3dViaFactory.#resolveSurfaceGeometry(
+            THREE,
+            geometryCache,
+            via
+        )
+        if (!geometry) {
+            return
+        }
+
+        for (const side of ['top', 'bottom']) {
+            if (
+                !PcbScene3dViaFactory.#renderModeTouchesSide(
+                    renderMode,
+                    side
+                ) ||
+                !PcbScene3dViaFactory.#isSideTented(via, side)
+            ) {
+                continue
+            }
+
+            const mesh = new THREE.Mesh(geometry, material)
+            mesh.position.set(
+                point.x,
+                point.y,
+                PcbScene3dViaFactory.#surfaceZ(side, thicknessMil)
+            )
+            group.add(mesh)
+        }
+    }
+
+    /**
+     * Resolves one reusable annular surface geometry.
+     * @param {any} THREE Three.js namespace.
+     * @param {Map<string, any>} geometryCache Surface geometry cache.
+     * @param {object} via Via primitive.
+     * @returns {any | null}
+     */
+    static #resolveSurfaceGeometry(THREE, geometryCache, via) {
+        const diameter = Number(via?.diameter || 0)
+        const holeDiameter = Number(via?.holeDiameter || 0)
+        if (diameter <= 0 || holeDiameter < 0 || diameter <= holeDiameter) {
+            return null
+        }
+
+        const key = `${diameter.toFixed(4)}:${holeDiameter.toFixed(4)}`
+        const cached = geometryCache.get(key)
+        if (cached) {
+            return cached
+        }
+
+        const shape = PcbScene3dViaFactory.#buildCircleShape(
+            THREE,
+            diameter / 2
+        )
+        if (holeDiameter > 0) {
+            shape.holes.push(
+                PcbScene3dViaFactory.#buildCirclePath(THREE, holeDiameter / 2)
+            )
+        }
+        const geometry = new THREE.ShapeGeometry(shape, 24)
+        geometryCache.set(key, geometry)
+        return geometry
+    }
+
+    /**
+     * Checks whether one rendered via span reaches a board side.
+     * @param {'through' | 'top' | 'bottom'} renderMode Via geometry mode.
+     * @param {'top' | 'bottom'} side Board side.
+     * @returns {boolean}
+     */
+    static #renderModeTouchesSide(renderMode, side) {
+        return renderMode === 'through' || renderMode === side
+    }
+
+    /**
+     * Checks whether one via surface is tented on a board side.
+     * @param {object} via Via primitive.
+     * @param {'top' | 'bottom'} side Board side.
+     * @returns {boolean}
+     */
+    static #isSideTented(via, side) {
+        const fieldName = side === 'bottom' ? 'isTentingBottom' : 'isTentingTop'
+        return via?.[fieldName] !== false
+    }
+
+    /**
+     * Resolves the solder-mask surface Z above the exposed copper stack.
+     * @param {'top' | 'bottom'} side Board side.
+     * @param {number} thicknessMil Board thickness in mil.
+     * @returns {number}
+     */
+    static #surfaceZ(side, thicknessMil) {
+        const distance =
+            Math.max(Number(thicknessMil) || 0, 0) / 2 +
+            PcbScene3dViaFactory.#SURFACE_MASK_Z_OFFSET_MIL
+        return side === 'bottom' ? -distance : distance
+    }
+
+    /**
+     * Resolves one reusable via geometry from the via drill spec.
+     * @param {any} THREE
+     * @param {Map<string, any>} geometryCache
+     * @param {{ diameter?: number, holeDiameter?: number, barrelOnly?: boolean }} via
+     * @param {number} depth Copper span depth in mil.
+     * @returns {any}
+     */
+    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'