pcb-scene3d-viewer 1.1.20 → 1.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pcb-scene3d-viewer",
-    "version": "1.1.20",
+    "version": "1.1.21",
     "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
     "keywords": [
         "pcb",

package/src/PcbScene3dCameraRig.mjs

@@ -267,12 +267,18 @@ export class PcbScene3dCameraRig {
      */
     static #applyOrthographicProjection(camera, state) {
         const zoom = Math.max(Number(camera.zoom || 1), 0.0001)
-        const height = Math.max(Number(state.orthographicHeight || 0) / zoom, 1)
+        const height = Math.max(Number(state.orthographicHeight || 0), 1)
         const width = height * Math.max(Number(camera.aspect || 1), 0.0001)
         const left = -width / 2
         const right = width / 2
         const top = height / 2
         const bottom = -height / 2
+        // Keep camera bounds unzoomed for OrbitControls pan math; apply zoom
+        // only to the projection matrix so dragging stays cursor-locked.
+        const projectedLeft = left / zoom
+        const projectedRight = right / zoom
+        const projectedTop = top / zoom
+        const projectedBottom = bottom / zoom
 
         camera.left = left
         camera.right = right
@@ -281,10 +287,10 @@ export class PcbScene3dCameraRig {
         camera.isPerspectiveCamera = false
         camera.isOrthographicCamera = true
         camera.projectionMatrix?.makeOrthographic?.(
-            left,
-            right,
-            top,
-            bottom,
+            projectedLeft,
+            projectedRight,
+            projectedTop,
+            projectedBottom,
             camera.near,
             camera.far
         )

package/src/PcbScene3dComponentVisibility.mjs

@@ -0,0 +1,161 @@
+/**
+ * Applies per-component hidden state on top of existing 3D visibility toggles.
+ */
+export class PcbScene3dComponentVisibility {
+    /**
+     * Stores one component hidden state.
+     * @param {Set<string>} hiddenDesignators Hidden designator set.
+     * @param {string} designator Component designator.
+     * @param {boolean} hidden Whether the component should be hidden.
+     * @returns {boolean}
+     */
+    static setHidden(hiddenDesignators, designator, hidden) {
+        if (!(hiddenDesignators instanceof Set)) {
+            return false
+        }
+
+        const normalizedDesignator =
+            PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+        if (!normalizedDesignator) {
+            return false
+        }
+
+        const wasHidden = hiddenDesignators.has(normalizedDesignator)
+        if (hidden) {
+            hiddenDesignators.add(normalizedDesignator)
+        } else {
+            hiddenDesignators.delete(normalizedDesignator)
+        }
+        return wasHidden !== hiddenDesignators.has(normalizedDesignator)
+    }
+
+    /**
+     * Checks whether one component is hidden.
+     * @param {Set<string>} hiddenDesignators Hidden designator set.
+     * @param {string} designator Component designator.
+     * @returns {boolean}
+     */
+    static isHidden(hiddenDesignators, designator) {
+        return (
+            hiddenDesignators instanceof Set &&
+            hiddenDesignators.has(
+                PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+            )
+        )
+    }
+
+    /**
+     * Applies component visibility to all selectable render roots.
+     * @param {{ selectionRoots?: Map<string, Set<any>>, hiddenDesignators?: Set<string>, fallbackBodyRoots?: Map<string, Set<any>>, loadedExternalModelDesignators?: Set<string>, modelSearchExternalModelRoots?: Set<any>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, 'model-search-models'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
+     * @returns {void}
+     */
+    static apply(state) {
+        const selectionRoots = state?.selectionRoots
+        if (!(selectionRoots instanceof Map)) {
+            return
+        }
+
+        selectionRoots.forEach((roots, designator) => {
+            roots?.forEach?.((rootObject) => {
+                if (!rootObject) {
+                    return
+                }
+
+                rootObject.visible =
+                    !PcbScene3dComponentVisibility.isHidden(
+                        state?.hiddenDesignators,
+                        designator
+                    ) &&
+                    PcbScene3dComponentVisibility.#resolveRootVisible(
+                        state,
+                        designator,
+                        rootObject
+                    )
+            })
+        })
+    }
+
+    /**
+     * Resolves root-level visibility before selected-component hiding.
+     * @param {{ fallbackBodyRoots?: Map<string, Set<any>>, loadedExternalModelDesignators?: Set<string>, modelSearchExternalModelRoots?: Set<any>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean, 'model-search-models'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
+     * @param {string} designator Component designator.
+     * @param {any} rootObject Render root.
+     * @returns {boolean}
+     */
+    static #resolveRootVisible(state, designator, rootObject) {
+        if (
+            PcbScene3dComponentVisibility.#isFallbackRoot(
+                state?.fallbackBodyRoots,
+                designator,
+                rootObject
+            )
+        ) {
+            return PcbScene3dComponentVisibility.#resolveFallbackVisible(
+                state,
+                designator
+            )
+        }
+
+        if (state?.modelSearchExternalModelRoots?.has?.(rootObject)) {
+            return (
+                Boolean(state?.toggles?.['external-models']) &&
+                state?.toggles?.['model-search-models'] !== false
+            )
+        }
+
+        return true
+    }
+
+    /**
+     * Resolves fallback root visibility from current detail toggles.
+     * @param {{ loadedExternalModelDesignators?: Set<string>, toggles?: { 'external-models'?: boolean, 'fallback-bodies'?: boolean }, hasLoadedBoardAssemblyModel?: boolean }} state Visibility state.
+     * @param {string} designator Component designator.
+     * @returns {boolean}
+     */
+    static #resolveFallbackVisible(state, designator) {
+        const boardAssemblyActive =
+            Boolean(state?.hasLoadedBoardAssemblyModel) &&
+            Boolean(state?.toggles?.['external-models'])
+        const showFallbackBodies =
+            Boolean(state?.toggles?.['fallback-bodies']) && !boardAssemblyActive
+        const hideForLoadedExternal =
+            Boolean(state?.toggles?.['external-models']) &&
+            state?.loadedExternalModelDesignators?.has?.(
+                PcbScene3dComponentVisibility.#normalizeDesignator(designator)
+            )
+
+        return showFallbackBodies && !hideForLoadedExternal
+    }
+
+    /**
+     * Checks whether a root belongs to fallback-body tracking.
+     * @param {Map<string, Set<any>> | undefined} fallbackBodyRoots Fallback roots.
+     * @param {string} designator Component designator.
+     * @param {any} rootObject Render root.
+     * @returns {boolean}
+     */
+    static #isFallbackRoot(fallbackBodyRoots, designator, rootObject) {
+        if (!(fallbackBodyRoots instanceof Map)) {
+            return false
+        }
+
+        return Boolean(
+            fallbackBodyRoots
+                .get(
+                    PcbScene3dComponentVisibility.#normalizeDesignator(
+                        designator
+                    )
+                )
+                ?.has?.(rootObject)
+        )
+    }
+
+    /**
+     * Normalizes component designator keys.
+     * @param {string} designator Raw designator.
+     * @returns {string}
+     */
+    static #normalizeDesignator(designator) {
+        return String(designator || '').trim()
+    }
+}

package/src/PcbScene3dController.mjs

@@ -4,6 +4,7 @@ import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs
 import { PcbScene3dInteractionHints } from './PcbScene3dInteractionHints.mjs'
 import { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
 import { PcbScene3dSelectionInspectorRenderer } from './PcbScene3dSelectionInspectorRenderer.mjs'
+import { PcbScene3dSelectionVisibilityBinder } from './PcbScene3dSelectionVisibilityBinder.mjs'
 import { PcbScene3dText } from './PcbScene3dText.mjs'
 
 /**
@@ -31,6 +32,8 @@ export class PcbScene3dController {
     /** @type {PcbScene3dAdjustmentControlBinder | null} */
     #adjustmentControls
 
+    /** @type {PcbScene3dSelectionVisibilityBinder | null} */
+    #visibilityControls
     /** @type {Array<{ node: EventTarget, type: string, listener: (event: any) => void }>} */
     #listeners
 
@@ -43,7 +46,7 @@ export class PcbScene3dController {
     /** @type {string} */
     #selectedComponentKey
 
-    /** @type {{ setPreset?: (preset: string) => void, setToggle?: (toggleName: string, enabled: boolean) => void, setSelectedDesignator?: (designator: string) => void, setComponentAdjustment?: (designator: string, adjustment: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }) => void, dispose?: () => void } | null} */
+    /** @type {any | null} */
     #runtime
 
     /** @type {any | null} */
@@ -151,19 +154,36 @@ export class PcbScene3dController {
                     suppressed ? '' : this.#selectedComponentKey
                 )
             },
-            refreshSelection: (designator) => {
+            refreshSelection: (designator, sourceType) => {
                 this.#setSelection({
                     designator,
-                    sourceType: this.#resolveSelectionSourceType(designator)
+                    sourceType:
+                        sourceType ||
+                        this.#resolveSelectionSourceType(designator)
+                })
+            }
+        })
+        this.#visibilityControls = new PcbScene3dSelectionVisibilityBinder({
+            resolveDesignator: () => this.#selectedComponentKey,
+            resolveHidden: (designator) =>
+                Boolean(this.#runtime?.isComponentHidden?.(designator)),
+            setHidden: (designator, hidden) => {
+                this.#runtime?.setComponentHidden?.(designator, hidden)
+            },
+            refreshSelection: (designator, source) => {
+                this.#setSelection({
+                    designator,
+                    sourceType:
+                        source || this.#resolveSelectionSourceType(designator)
                 })
             }
         })
-
         this.#bindPresets()
         this.#setActivePresetButton('isometric')
         this.#bindToggles()
         this.#bindExportAction()
         this.#adjustmentControls.bindSelectionNode(this.#selectionNode)
+        this.#visibilityControls.bindSelectionNode(this.#selectionNode)
         this.#setSelection(null)
         this.#setLoadingVisible(true)
         const circuitJsonModel = PcbScene3dController.#resolveCircuitJsonModel(
@@ -287,6 +307,8 @@ export class PcbScene3dController {
         this.#scenePrepClient = null
         this.#adjustmentControls?.dispose()
         this.#adjustmentControls = null
+        this.#visibilityControls?.dispose()
+        this.#visibilityControls = null
         this.#runtime?.dispose?.()
         this.#runtime = null
         this.#sceneDescription = null
@@ -739,6 +761,9 @@ export class PcbScene3dController {
             this.#selectionNode.innerHTML =
                 PcbScene3dSelectionInspectorRenderer.renderSelected({
                     designator,
+                    hidden: Boolean(
+                        this.#runtime?.isComponentHidden?.(designator)
+                    ),
                     selection,
                     selectionEntry,
                     adjustment,

package/src/PcbScene3dExternalModelPlacementRepair.mjs

@@ -13,7 +13,7 @@ export class PcbScene3dExternalModelPlacementRepair {
         '#333333',
         '#3f3f3f'
     ])
-    static #MIN_CENTER_ERROR_MIL = 25
+    static #MIN_CENTER_ERROR_MIL = 1
     static #MIN_TERMINAL_SIZE_MIL = 1
     static #SOURCE_ORIGIN_SHIFT_EPSILON_MIL = 0.01
     static #SOURCE_Z_DEPTH_MIN_RATIO = 1.5

package/src/PcbScene3dInteractionHints.mjs

@@ -6,24 +6,32 @@ export class PcbScene3dInteractionHints {
      * Applies explicit OrbitControls input mappings for desktop and touch.
      * @param {{ mouseButtons?: any, touches?: any }} controls
      * @param {{ MOUSE?: any, TOUCH?: any }} THREE
+     * @param {string} [preset] Active camera preset.
      * @returns {void}
      */
-    static configureControls(controls, THREE) {
+    static configureControls(controls, THREE, preset = 'isometric') {
         if (!controls) {
             return
         }
 
+        const inspectionPreset =
+            String(preset || '').toLowerCase() === 'top' ||
+            String(preset || '').toLowerCase() === 'bottom'
+
         if (THREE?.MOUSE) {
             controls.mouseButtons = {
-                LEFT: THREE.MOUSE.ROTATE,
+                LEFT: inspectionPreset ? THREE.MOUSE.PAN : THREE.MOUSE.ROTATE,
                 MIDDLE: THREE.MOUSE.DOLLY,
-                RIGHT: THREE.MOUSE.PAN
+                RIGHT: inspectionPreset ? THREE.MOUSE.ROTATE : THREE.MOUSE.PAN
             }
         }
 
         if (THREE?.TOUCH) {
             controls.touches = {
-                ONE: THREE.TOUCH.ROTATE,
+                ONE:
+                    inspectionPreset && THREE.TOUCH.PAN
+                        ? THREE.TOUCH.PAN
+                        : THREE.TOUCH.ROTATE,
                 TWO: THREE.TOUCH.DOLLY_PAN
             }
         }
@@ -44,13 +52,13 @@ export class PcbScene3dInteractionHints {
                 const value = translate('scene3d.touchHint')
                 if (value && value !== 'scene3d.touchHint') return value
             }
-            return 'Drag with one finger to orbit, pinch to zoom, and drag with two fingers to pan.'
+            return 'One-finger drag pans in Top/Bottom and orbits in Isometric. Pinch to zoom.'
         }
 
         if (typeof translate === 'function') {
             const value = translate('scene3d.pointerHint')
             if (value && value !== 'scene3d.pointerHint') return value
         }
-        return 'Drag to orbit, right-drag to pan, and use the wheel to zoom.'
+        return 'Drag pans in Top/Bottom and orbits in Isometric; right-drag uses the alternate action. Use the wheel to zoom.'
     }
 }

package/src/PcbScene3dRenderScheduler.mjs

@@ -0,0 +1,55 @@
+/**
+ * Coalesces high-frequency scene renders into animation frames.
+ */
+export class PcbScene3dRenderScheduler {
+    /** @type {() => void} */
+    #render
+
+    /** @type {number | null} */
+    #pendingFrame
+
+    /**
+     * @param {() => void} render Render callback.
+     */
+    constructor(render) {
+        this.#render = render
+        this.#pendingFrame = null
+    }
+
+    /**
+     * Queues a render for the next animation frame.
+     * @returns {void}
+     */
+    schedule() {
+        if (this.#pendingFrame !== null) {
+            return
+        }
+
+        const requestFrame = globalThis.window?.requestAnimationFrame
+        if (typeof requestFrame !== 'function') {
+            this.#render()
+            return
+        }
+
+        this.#pendingFrame = requestFrame(() => {
+            this.#pendingFrame = null
+            this.#render()
+        })
+    }
+
+    /**
+     * Cancels one pending animation-frame render.
+     * @returns {void}
+     */
+    cancel() {
+        if (this.#pendingFrame === null) {
+            return
+        }
+
+        const cancelFrame = globalThis.window?.cancelAnimationFrame
+        if (typeof cancelFrame === 'function') {
+            cancelFrame(this.#pendingFrame)
+        }
+        this.#pendingFrame = null
+    }
+}

package/src/PcbScene3dRuntime.mjs

@@ -2,6 +2,7 @@ import { PcbScene3dBoardSolderMaskFactory } from './PcbScene3dBoardSolderMaskFac
 import { PcbScene3dBodyColor } from './PcbScene3dBodyColor.mjs'
 import { PcbScene3dCameraRig } from './PcbScene3dCameraRig.mjs'
 import { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs'
+import { PcbScene3dComponentVisibility } from './PcbScene3dComponentVisibility.mjs'
 import { PcbScene3dComponentAdjustment } from './PcbScene3dComponentAdjustment.mjs'
 import { PcbScene3dComponentAdjustmentRegistry } from './PcbScene3dComponentAdjustmentRegistry.mjs'
 import { PcbScene3dCopperDetailGroupBuilder } from './PcbScene3dCopperDetailGroupBuilder.mjs'
@@ -15,6 +16,7 @@ import { PcbScene3dMountRig } from './PcbScene3dMountRig.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 { PcbScene3dSilkscreenChunkedFactory } from './PcbScene3dSilkscreenChunkedFactory.mjs'
 import { PcbScene3dTrueTypeTextFactory } from './PcbScene3dTrueTypeTextFactory.mjs'
@@ -52,6 +54,7 @@ export class PcbScene3dRuntime {
     #pointer
     #pointerDownPosition
     #selectionRoots
+    #hiddenComponentDesignators
     #componentAdjustmentRegistry
     #fallbackBodyRoots
     #loadedExternalModelDesignators
@@ -64,6 +67,7 @@ export class PcbScene3dRuntime {
     #readyPromise
     #resolveReadyPromise
     #hasSettledReady
+    #renderScheduler
     /**
      * @param {HTMLElement} viewportNode
      * @param {any} sceneDescription Scene description or CircuitJSON model.
@@ -96,6 +100,7 @@ export class PcbScene3dRuntime {
         this.#pointer = null
         this.#pointerDownPosition = null
         this.#selectionRoots = new Map()
+        this.#hiddenComponentDesignators = new Set()
         this.#componentAdjustmentRegistry =
             new PcbScene3dComponentAdjustmentRegistry(() => this.#three)
         this.#fallbackBodyRoots = new Map()
@@ -108,6 +113,11 @@ export class PcbScene3dRuntime {
         this.#presetState = new PcbScene3dPresetState()
         this.#isDisposed = false
         this.#hasSettledReady = false
+        this.#renderScheduler = new PcbScene3dRenderScheduler(() => {
+            if (!this.#isDisposed) {
+                this.#render()
+            }
+        })
         this.#resolveReadyPromise = null
         this.#readyPromise = new Promise((resolve) => {
             this.#resolveReadyPromise = resolve
@@ -124,10 +134,14 @@ export class PcbScene3dRuntime {
     setPreset(preset) {
         const normalizedPreset = this.#presetState.set(preset)
         this.#applyViewScale(normalizedPreset)
+        PcbScene3dInteractionHints.configureControls(
+            this.#controls,
+            this.#three,
+            normalizedPreset
+        )
         if (!this.#camera) {
             return
         }
-
         PcbScene3dCameraRig.applyPreset(
             this.#camera,
             this.#controls,
@@ -141,7 +155,6 @@ export class PcbScene3dRuntime {
         if (!(toggleName in this.#toggles)) {
             return
         }
-
         this.#toggles[toggleName] = enabled
         this.#applyToggleVisibility()
         this.#render()
@@ -150,6 +163,27 @@ export class PcbScene3dRuntime {
     setSelectedDesignator(designator) {
         this.#setSelectedDesignator(designator)
     }
+    /** @param {string} designator @param {boolean} hidden */
+    setComponentHidden(designator, hidden) {
+        if (
+            !PcbScene3dComponentVisibility.setHidden(
+                this.#hiddenComponentDesignators,
+                designator,
+                hidden
+            )
+        ) {
+            return
+        }
+        this.#applyToggleVisibility()
+        this.#render()
+    }
+    /** @param {string} designator @returns {boolean} */
+    isComponentHidden(designator) {
+        return PcbScene3dComponentVisibility.isHidden(
+            this.#hiddenComponentDesignators,
+            designator
+        )
+    }
     /**
      * Applies a live model-local adjustment to one component.
      * @param {string} designator Component designator.
@@ -172,6 +206,7 @@ export class PcbScene3dRuntime {
     /** @returns {void} */
     dispose() {
         this.#isDisposed = true
+        this.#renderScheduler.cancel()
         this.#listeners.forEach(({ node, type, listener }) => {
             node.removeEventListener?.(type, listener)
         })
@@ -196,6 +231,7 @@ export class PcbScene3dRuntime {
         this.#pointer = null
         this.#pointerDownPosition = null
         this.#selectionRoots.clear()
+        this.#hiddenComponentDesignators.clear()
         this.#componentAdjustmentRegistry.clear()
         this.#fallbackBodyRoots.clear()
         this.#loadedExternalModelDesignators.clear()
@@ -636,7 +672,11 @@ export class PcbScene3dRuntime {
         this.#controls.minDistance = 140
         this.#controls.maxDistance = this.#initialRadius * 8
         this.#controls.target.set(0, 0, 0)
-        PcbScene3dInteractionHints.configureControls(this.#controls, THREE)
+        PcbScene3dInteractionHints.configureControls(
+            this.#controls,
+            THREE,
+            this.#presetState.get()
+        )
 
         PcbScene3dCameraRig.applyPreset(
             this.#camera,
@@ -645,7 +685,9 @@ export class PcbScene3dRuntime {
             this.#sceneDescription
         )
 
-        this.#bindListener(this.#controls, 'change', () => this.#render())
+        this.#bindListener(this.#controls, 'change', () => {
+            this.#renderScheduler.schedule()
+        })
         this.#bindListener(domElement, 'contextmenu', (event) => {
             event.preventDefault?.()
         })
@@ -726,6 +768,16 @@ export class PcbScene3dRuntime {
             modelSearchExternalModelRoots: this.#modelSearchExternalModelRoots,
             hasLoadedBoardAssemblyModel: this.#hasLoadedBoardAssemblyModel
         })
+        PcbScene3dComponentVisibility.apply({
+            selectionRoots: this.#selectionRoots,
+            hiddenDesignators: this.#hiddenComponentDesignators,
+            fallbackBodyRoots: this.#fallbackBodyRoots,
+            loadedExternalModelDesignators:
+                this.#loadedExternalModelDesignators,
+            modelSearchExternalModelRoots: this.#modelSearchExternalModelRoots,
+            toggles: this.#toggles,
+            hasLoadedBoardAssemblyModel: this.#hasLoadedBoardAssemblyModel
+        })
     }
 
     /** @returns {void} */

package/src/PcbScene3dSelectionInspectorRenderer.mjs

@@ -46,12 +46,13 @@ export class PcbScene3dSelectionInspectorRenderer {
 
     /**
      * Renders selected component details and optional editable transform controls.
-     * @param {{ designator: string, selection?: { sourceType?: string } | null, selectionEntry: { component: any | null, externalPlacement: any | null }, adjustment: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }, includeControls?: boolean, translate: (key: string) => string }} options Render options.
+     * @param {{ designator: string, hidden?: boolean, selection?: { sourceType?: string } | null, selectionEntry: { component: any | null, externalPlacement: any | null }, adjustment: { scale: { x: number, y: number, z: number }, rotationDeg: { x: number, y: number, z: number }, offsetMil: { x: number, y: number, z: number } }, includeControls?: boolean, translate: (key: string) => string }} options Render options.
      * @returns {string}
      */
     static renderSelected(options) {
         const component = options.selectionEntry.component
         const externalPlacement = options.selectionEntry.externalPlacement
+        const hidden = options.hidden === true
         const fields = [
             [options.translate('scene3d.designator'), options.designator],
             [
@@ -127,11 +128,18 @@ export class PcbScene3dSelectionInspectorRenderer {
         ].filter(([, value]) => String(value || '').trim())
 
         return (
-            '<h4 class="scene-3d__selection-title">' +
+            '<div class="scene-3d__selection-header"><h4 class="scene-3d__selection-title">' +
             PcbScene3dSelectionInspectorRenderer.#escapeHtml(
                 options.translate('scene3d.componentInspector')
             ) +
-            '</h4><dl class="scene-3d__selection-list">' +
+            '</h4>' +
+            PcbScene3dSelectionInspectorRenderer.#renderVisibilityToggle(
+                options.designator,
+                options.selection?.sourceType || '',
+                hidden,
+                options.translate
+            ) +
+            '</div><dl class="scene-3d__selection-list">' +
             fields
                 .map(
                     ([label, value]) =>
@@ -461,6 +469,59 @@ export class PcbScene3dSelectionInspectorRenderer {
         )
     }
 
+    /**
+     * Renders the selected-component visibility toggle.
+     * @param {string} designator Selected component designator.
+     * @param {string} sourceType Selection source type.
+     * @param {boolean} hidden Whether the component is hidden.
+     * @param {(key: string) => string} translate Translation lookup.
+     * @returns {string}
+     */
+    static #renderVisibilityToggle(designator, sourceType, hidden, translate) {
+        const label = hidden
+            ? translate('scene3d.showSelectedComponent')
+            : translate('scene3d.hideSelectedComponent')
+        const iconClass = hidden
+            ? 'scene-3d__selection-eye-icon scene-3d__selection-eye-off-icon'
+            : 'scene-3d__selection-eye-icon'
+
+        return (
+            '<button class="scene-3d__selection-visibility" type="button" data-scene-3d-component-visibility="' +
+            PcbScene3dSelectionInspectorRenderer.#escapeHtml(designator) +
+            '" data-scene-3d-component-source="' +
+            PcbScene3dSelectionInspectorRenderer.#escapeHtml(sourceType) +
+            '" aria-label="' +
+            PcbScene3dSelectionInspectorRenderer.#escapeHtml(label) +
+            '" title="' +
+            PcbScene3dSelectionInspectorRenderer.#escapeHtml(label) +
+            '" aria-pressed="' +
+            (hidden ? 'true' : 'false') +
+            '"><span class="' +
+            iconClass +
+            '" aria-hidden="true">' +
+            PcbScene3dSelectionInspectorRenderer.#renderVisibilityIcon(
+                !hidden
+            ) +
+            '</span></button>'
+        )
+    }
+
+    /**
+     * Renders an eye icon for component visibility state.
+     * @param {boolean} visible Whether the component is visible.
+     * @returns {string}
+     */
+    static #renderVisibilityIcon(visible) {
+        const slash = visible ? '' : '<path d="M4 4l16 16" />'
+        return (
+            '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">' +
+            '<path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />' +
+            '<circle cx="12" cy="12" r="2.5" />' +
+            slash +
+            '</svg>'
+        )
+    }
+
     /**
      * Formats a model file label.
      * @param {any} externalPlacement External placement.

package/src/PcbScene3dSelectionVisibilityBinder.mjs

@@ -0,0 +1,119 @@
+/**
+ * Binds the selected-component visibility toggle in the inspector.
+ */
+export class PcbScene3dSelectionVisibilityBinder {
+    /** @type {HTMLElement | null} */
+    #selectionNode
+
+    /** @type {{ node: EventTarget, type: string, listener: (event: any) => void } | null} */
+    #listenerRecord
+
+    /** @type {() => string} */
+    #resolveDesignator
+
+    /** @type {(designator: string) => boolean} */
+    #resolveHidden
+
+    /** @type {(designator: string, hidden: boolean) => void} */
+    #setHidden
+
+    /** @type {(designator: string, sourceType: string) => void} */
+    #refreshSelection
+
+    /**
+     * @param {{ resolveDesignator: () => string, resolveHidden: (designator: string) => boolean, setHidden: (designator: string, hidden: boolean) => void, refreshSelection: (designator: string, sourceType: string) => void }} options Binder callbacks.
+     */
+    constructor(options) {
+        this.#selectionNode = null
+        this.#listenerRecord = null
+        this.#resolveDesignator = options.resolveDesignator
+        this.#resolveHidden = options.resolveHidden
+        this.#setHidden = options.setHidden
+        this.#refreshSelection = options.refreshSelection
+    }
+
+    /**
+     * Binds delegated visibility toggles in the selection inspector.
+     * @param {HTMLElement | null} selectionNode Inspector node.
+     * @returns {void}
+     */
+    bindSelectionNode(selectionNode) {
+        this.dispose()
+        this.#selectionNode =
+            selectionNode && typeof selectionNode === 'object'
+                ? selectionNode
+                : null
+        if (!this.#selectionNode) {
+            return
+        }
+
+        const listener = (event) => this.#handleClick(event)
+        this.#selectionNode.addEventListener?.('click', listener)
+        this.#listenerRecord = {
+            node: this.#selectionNode,
+            type: 'click',
+            listener
+        }
+    }
+
+    /**
+     * Removes the active delegated click listener.
+     * @returns {void}
+     */
+    dispose() {
+        if (this.#listenerRecord) {
+            const { node, type, listener } = this.#listenerRecord
+            node.removeEventListener?.(type, listener)
+        }
+        this.#listenerRecord = null
+        this.#selectionNode = null
+    }
+
+    /**
+     * Handles one delegated visibility-button click.
+     * @param {any} event DOM event.
+     * @returns {void}
+     */
+    #handleClick(event) {
+        const button =
+            PcbScene3dSelectionVisibilityBinder.#closestVisibilityButton(
+                event?.target
+            )
+        if (!button) {
+            return
+        }
+
+        event?.preventDefault?.()
+        const designator = String(
+            button?.getAttribute?.('data-scene-3d-component-visibility') ||
+                this.#resolveDesignator() ||
+                ''
+        ).trim()
+        if (!designator) {
+            return
+        }
+
+        this.#setHidden(designator, !this.#resolveHidden(designator))
+        this.#refreshSelection(
+            designator,
+            String(
+                button?.getAttribute?.('data-scene-3d-component-source') || ''
+            )
+        )
+    }
+
+    /**
+     * Finds a visibility button from an event target.
+     * @param {any} target Event target.
+     * @returns {any | null}
+     */
+    static #closestVisibilityButton(target) {
+        const closest = target?.closest?.(
+            '[data-scene-3d-component-visibility]'
+        )
+        return closest ||
+            target?.getAttribute?.('data-scene-3d-component-visibility')
+            ? closest || target
+            : null
+    }
+}

package/src/PcbScene3dText.mjs

@@ -22,6 +22,7 @@ const FALLBACK_MESSAGES = {
     'scene3d.fallbackBody': 'Fallback body',
     'scene3d.fallbackBodies': 'Fallback bodies',
     'scene3d.footprint': 'Footprint',
+    'scene3d.hideSelectedComponent': 'Hide selected component',
     'scene3d.inspectPrompt': 'Click a component to inspect it.',
     'scene3d.interactiveViewAria': 'Interactive 3D PCB view',
     'scene3d.isometric': 'Isometric',
@@ -39,11 +40,12 @@ const FALLBACK_MESSAGES = {
     'scene3d.picked': 'Picked',
     'scene3d.placements': 'Placements',
     'scene3d.pointerHint':
-        'Drag to orbit, right-drag to pan, and use the wheel to zoom.',
+        'Drag pans in Top/Bottom and orbits in Isometric; right-drag uses the alternate action. Use the wheel to zoom.',
     'scene3d.offset': 'Offset',
     'scene3d.resetTransform': 'Reset',
     'scene3d.rotation': 'Rotation',
     'scene3d.scale': 'Scale',
+    'scene3d.showSelectedComponent': 'Show selected component',
     'scene3d.skipped': 'Skipped',
     'scene3d.source': 'Source',
     'scene3d.startFailed': '3D preview could not start:',
@@ -53,7 +55,7 @@ const FALLBACK_MESSAGES = {
     'scene3d.toolbarAria': '3D camera presets',
     'scene3d.top': 'Top',
     'scene3d.touchHint':
-        'Drag with one finger to orbit, pinch to zoom, and drag with two fingers to pan.',
+        'One-finger drag pans in Top/Bottom and orbits in Isometric. Pinch to zoom.',
     'scene3d.unresolved': 'unresolved'
 }
 

package/src/scene3d.mjs

@@ -17,6 +17,7 @@ export { PcbScene3dBoardSolderMaskFactory } from './PcbScene3dBoardSolderMaskFac
 export { PcbScene3dCameraRig } from './PcbScene3dCameraRig.mjs'
 export { PcbScene3dController } from './PcbScene3dController.mjs'
 export { PcbScene3dCircuitJsonAdapter } from './PcbScene3dCircuitJsonAdapter.mjs'
+export { PcbScene3dComponentVisibility } from './PcbScene3dComponentVisibility.mjs'
 export { PcbScene3dCopperDetailFilter } from './PcbScene3dCopperDetailFilter.mjs'
 export { PcbScene3dCopperFactory } from './PcbScene3dCopperFactory.mjs'
 export { PcbScene3dCopperTextFactory } from './PcbScene3dCopperTextFactory.mjs'
@@ -34,9 +35,11 @@ export { PcbScene3dOutlineBuilder } from './PcbScene3dOutlineBuilder.mjs'
 export { PcbScene3dPadFactory } from './PcbScene3dPadFactory.mjs'
 export { PcbScene3dPresetState } from './PcbScene3dPresetState.mjs'
 export { PcbScene3dRenderGroupVisibility } from './PcbScene3dRenderGroupVisibility.mjs'
+export { PcbScene3dRenderScheduler } from './PcbScene3dRenderScheduler.mjs'
 export { PcbScene3dRuntime } from './PcbScene3dRuntime.mjs'
 export { PcbScene3dRuntimeBoardMeshes } from './PcbScene3dRuntimeBoardMeshes.mjs'
 export { PcbScene3dSelectionStyler } from './PcbScene3dSelectionStyler.mjs'
+export { PcbScene3dSelectionVisibilityBinder } from './PcbScene3dSelectionVisibilityBinder.mjs'
 export { PcbScene3dShapePathFactory } from './PcbScene3dShapePathFactory.mjs'
 export { PcbScene3dShellRenderer } from './PcbScene3dShellRenderer.mjs'
 export { PcbScene3dSilkscreenFactory } from './PcbScene3dSilkscreenFactory.mjs'

package/src/styles/scene3d.css

@@ -173,11 +173,59 @@ body.is-viewer-mode.is-viewer-3d .scene-3d {
     border: 1px solid rgba(95, 112, 124, 0.12);
 }
 
+.scene-3d__selection-header {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) 2.1rem;
+    align-items: center;
+    gap: 0.5rem;
+}
+
 .scene-3d__selection-title {
     margin: 0;
     font-size: 0.9rem;
 }
 
+.scene-3d__selection-visibility {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.1rem;
+    height: 2.1rem;
+    border: 1px solid rgba(95, 112, 124, 0.16);
+    border-radius: 8px;
+    background: rgba(255, 255, 255, 0.78);
+    color: #425d70;
+    cursor: pointer;
+}
+
+.scene-3d__selection-visibility:hover,
+.scene-3d__selection-visibility[aria-pressed='true'] {
+    border-color: rgba(184, 90, 37, 0.34);
+    color: var(--accent);
+}
+
+.scene-3d__selection-eye-icon {
+    width: 1.1rem;
+    height: 1.1rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.scene-3d__selection-eye-icon .icon {
+    width: 1.05rem;
+    height: 1.05rem;
+}
+
+.scene-3d__selection-eye-icon .icon path,
+.scene-3d__selection-eye-icon .icon circle {
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.8;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+}
+
 .scene-3d__selection-empty {
     margin: 0;
     color: var(--muted);