altium-toolkit 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.0.7",
+    "version": "1.0.8",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/renderers.mjs

@@ -6,6 +6,9 @@ export { BomTableRenderer } from './ui/BomTableRenderer.mjs'
 export { PcbArcUtils } from './ui/PcbArcUtils.mjs'
 export { PcbEdgeFacingGlyphNormalizer } from './ui/PcbEdgeFacingGlyphNormalizer.mjs'
 export { PcbFootprintPrimitiveSelector } from './ui/PcbFootprintPrimitiveSelector.mjs'
+export { PcbInteractionIndex } from './ui/PcbInteractionIndex.mjs'
+export { PcbInteractionItemRegistry } from './ui/PcbInteractionItemRegistry.mjs'
+export { PcbInteractionLayerModel } from './ui/PcbInteractionLayerModel.mjs'
 export {
     PcbSideResolvedRenderModel,
     isCopperPrimitive,

package/src/styles/altium-renderers.css

@@ -137,6 +137,7 @@
     --pcb-copper-fill: rgba(196, 118, 70, 0.24);
     --pcb-copper-solid-fill: rgba(196, 118, 70, 0.78);
     --pcb-track-color: #c7522d;
+    --pcb-track-opacity: 1;
     --pcb-via-ring-fill: rgba(232, 236, 233, 0.92);
     --pcb-via-hole-fill: #0f746c;
     --pcb-footprint-fill: rgba(247, 230, 117, 0.14);
@@ -203,6 +204,11 @@
     stroke-linejoin: round;
 }
 
+.pcb-track,
+.pcb-arc {
+    opacity: var(--pcb-track-opacity, 1);
+}
+
 .pcb-copper--surface .pcb-polygon {
     fill: var(--pcb-surface-copper-fill);
 }

package/src/ui/PcbInteractionGeometry.mjs

@@ -0,0 +1,350 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Provides lightweight hit-test geometry helpers for PCB mil coordinates.
+ */
+export class PcbInteractionGeometry {
+    /**
+     * Builds a circular geometry descriptor.
+     * @param {{ x?: unknown, y?: unknown }} center Center point.
+     * @param {unknown} radius Radius.
+     * @returns {object}
+     */
+    static circle(center, radius) {
+        return {
+            kind: 'circle',
+            center: PcbInteractionGeometry.point(center),
+            radius: Math.max(0, Number(radius) || 0)
+        }
+    }
+
+    /**
+     * Builds a stroked segment geometry descriptor.
+     * @param {{ x?: unknown, y?: unknown }} start Start point.
+     * @param {{ x?: unknown, y?: unknown }} end End point.
+     * @param {unknown} radius Stroke radius.
+     * @returns {object}
+     */
+    static segment(start, end, radius = 0) {
+        return {
+            kind: 'segment',
+            start: PcbInteractionGeometry.point(start),
+            end: PcbInteractionGeometry.point(end),
+            radius: Math.max(0, Number(radius) || 0)
+        }
+    }
+
+    /**
+     * Builds a polygon geometry descriptor.
+     * @param {{ x?: unknown, y?: unknown }[]} points Polygon points.
+     * @returns {object}
+     */
+    static polygon(points) {
+        return {
+            kind: 'polygon',
+            points: (Array.isArray(points) ? points : []).map((point) =>
+                PcbInteractionGeometry.point(point)
+            )
+        }
+    }
+
+    /**
+     * Builds an axis-aligned bounds geometry descriptor.
+     * @param {object} bounds Bounds.
+     * @returns {object}
+     */
+    static bounds(bounds) {
+        return {
+            kind: 'bounds',
+            bounds: PcbInteractionGeometry.normalizeBounds(bounds)
+        }
+    }
+
+    /**
+     * Builds a rotated rectangle polygon geometry descriptor.
+     * @param {object} rectangle Rectangle.
+     * @returns {object}
+     */
+    static rotatedRectangle(rectangle) {
+        const center = PcbInteractionGeometry.point(rectangle)
+        const width = Math.max(0, Number(rectangle?.width) || 0)
+        const height = Math.max(0, Number(rectangle?.height) || 0)
+        const rotation = (Number(rectangle?.rotation) || 0) * (Math.PI / 180)
+        const cos = Math.cos(rotation)
+        const sin = Math.sin(rotation)
+        const halfWidth = width / 2
+        const halfHeight = height / 2
+
+        return PcbInteractionGeometry.polygon(
+            [
+                { x: -halfWidth, y: -halfHeight },
+                { x: halfWidth, y: -halfHeight },
+                { x: halfWidth, y: halfHeight },
+                { x: -halfWidth, y: halfHeight }
+            ].map((point) => ({
+                x: center.x + point.x * cos - point.y * sin,
+                y: center.y + point.x * sin + point.y * cos
+            }))
+        )
+    }
+
+    /**
+     * Normalizes a point value.
+     * @param {{ x?: unknown, y?: unknown }} point Point-like value.
+     * @returns {{ x: number, y: number }}
+     */
+    static point(point) {
+        return {
+            x: Number(point?.x) || 0,
+            y: Number(point?.y) || 0
+        }
+    }
+
+    /**
+     * Returns bounds for a geometry descriptor.
+     * @param {object | null | undefined} geometry Geometry descriptor.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number, width: number, height: number }}
+     */
+    static boundsFor(geometry) {
+        if (!geometry || typeof geometry !== 'object') {
+            return PcbInteractionGeometry.normalizeBounds(null)
+        }
+
+        if (geometry.kind === 'bounds') {
+            return PcbInteractionGeometry.normalizeBounds(geometry.bounds)
+        }
+
+        const points = PcbInteractionGeometry.#pointsForBounds(geometry)
+        if (!points.length) return PcbInteractionGeometry.normalizeBounds(null)
+
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+        const minX = Math.min(...xs)
+        const minY = Math.min(...ys)
+        const maxX = Math.max(...xs)
+        const maxY = Math.max(...ys)
+
+        return {
+            minX,
+            minY,
+            maxX,
+            maxY,
+            width: maxX - minX,
+            height: maxY - minY
+        }
+    }
+
+    /**
+     * Normalizes an axis-aligned bounds value.
+     * @param {object | null | undefined} bounds Bounds-like value.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number, width: number, height: number }}
+     */
+    static normalizeBounds(bounds) {
+        const minX = Number(bounds?.minX) || 0
+        const minY = Number(bounds?.minY) || 0
+        const width = Number(bounds?.widthMil ?? bounds?.width) || 0
+        const height = Number(bounds?.heightMil ?? bounds?.height) || 0
+        const maxX = Number.isFinite(Number(bounds?.maxX))
+            ? Number(bounds.maxX)
+            : minX + width
+        const maxY = Number.isFinite(Number(bounds?.maxY))
+            ? Number(bounds.maxY)
+            : minY + height
+
+        return {
+            minX: Math.min(minX, maxX),
+            minY: Math.min(minY, maxY),
+            maxX: Math.max(minX, maxX),
+            maxY: Math.max(minY, maxY),
+            width: Math.abs(maxX - minX),
+            height: Math.abs(maxY - minY)
+        }
+    }
+
+    /**
+     * Returns whether a point intersects a geometry descriptor.
+     * @param {object | null | undefined} geometry Geometry descriptor.
+     * @param {{ x?: unknown, y?: unknown }} point Point-like value.
+     * @param {number} [tolerance] Extra tolerance.
+     * @returns {boolean}
+     */
+    static containsPoint(geometry, point, tolerance = 0) {
+        const normalizedPoint = PcbInteractionGeometry.point(point)
+        if (!geometry || typeof geometry !== 'object') return false
+
+        if (
+            !PcbInteractionGeometry.#boundsContainsPoint(
+                PcbInteractionGeometry.boundsFor(geometry),
+                normalizedPoint,
+                tolerance
+            )
+        ) {
+            return false
+        }
+
+        if (geometry.kind === 'circle') {
+            return (
+                PcbInteractionGeometry.#distance(
+                    normalizedPoint,
+                    geometry.center
+                ) <=
+                (Number(geometry.radius) || 0) + tolerance
+            )
+        }
+
+        if (geometry.kind === 'segment') {
+            return (
+                PcbInteractionGeometry.#pointToSegmentDistance(
+                    normalizedPoint,
+                    geometry.start,
+                    geometry.end
+                ) <=
+                (Number(geometry.radius) || 0) + tolerance
+            )
+        }
+
+        if (geometry.kind === 'polygon') {
+            return PcbInteractionGeometry.#pointInPolygon(
+                normalizedPoint,
+                geometry.points || []
+            )
+        }
+
+        if (geometry.kind === 'bounds') {
+            return true
+        }
+
+        return false
+    }
+
+    /**
+     * Returns geometry points used for bounds calculations.
+     * @param {object} geometry Geometry descriptor.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #pointsForBounds(geometry) {
+        if (geometry.kind === 'circle') {
+            const center = PcbInteractionGeometry.point(geometry.center)
+            const radius = Math.max(0, Number(geometry.radius) || 0)
+            return [
+                { x: center.x - radius, y: center.y - radius },
+                { x: center.x + radius, y: center.y + radius }
+            ]
+        }
+
+        if (geometry.kind === 'segment') {
+            const start = PcbInteractionGeometry.point(geometry.start)
+            const end = PcbInteractionGeometry.point(geometry.end)
+            const radius = Math.max(0, Number(geometry.radius) || 0)
+            return [
+                {
+                    x: Math.min(start.x, end.x) - radius,
+                    y: Math.min(start.y, end.y) - radius
+                },
+                {
+                    x: Math.max(start.x, end.x) + radius,
+                    y: Math.max(start.y, end.y) + radius
+                }
+            ]
+        }
+
+        if (geometry.kind === 'polygon') {
+            return (Array.isArray(geometry.points) ? geometry.points : []).map(
+                (point) => PcbInteractionGeometry.point(point)
+            )
+        }
+
+        return []
+    }
+
+    /**
+     * Returns whether bounds contain a point.
+     * @param {object} bounds Bounds.
+     * @param {{ x: number, y: number }} point Point.
+     * @param {number} tolerance Tolerance.
+     * @returns {boolean}
+     */
+    static #boundsContainsPoint(bounds, point, tolerance) {
+        return (
+            point.x >= bounds.minX - tolerance &&
+            point.x <= bounds.maxX + tolerance &&
+            point.y >= bounds.minY - tolerance &&
+            point.y <= bounds.maxY + tolerance
+        )
+    }
+
+    /**
+     * Returns Euclidean distance between two points.
+     * @param {{ x?: unknown, y?: unknown }} first First point.
+     * @param {{ x?: unknown, y?: unknown }} second Second point.
+     * @returns {number}
+     */
+    static #distance(first, second) {
+        const a = PcbInteractionGeometry.point(first)
+        const b = PcbInteractionGeometry.point(second)
+        return Math.hypot(a.x - b.x, a.y - b.y)
+    }
+
+    /**
+     * Computes point-to-segment distance.
+     * @param {{ x: number, y: number }} point Point.
+     * @param {{ x?: unknown, y?: unknown }} start Segment start.
+     * @param {{ x?: unknown, y?: unknown }} end Segment end.
+     * @returns {number}
+     */
+    static #pointToSegmentDistance(point, start, end) {
+        const first = PcbInteractionGeometry.point(start)
+        const second = PcbInteractionGeometry.point(end)
+        const dx = second.x - first.x
+        const dy = second.y - first.y
+        const lengthSquared = dx * dx + dy * dy
+        if (lengthSquared === 0) {
+            return PcbInteractionGeometry.#distance(point, first)
+        }
+
+        const t = Math.max(
+            0,
+            Math.min(
+                1,
+                ((point.x - first.x) * dx + (point.y - first.y) * dy) /
+                    lengthSquared
+            )
+        )
+        return PcbInteractionGeometry.#distance(point, {
+            x: first.x + t * dx,
+            y: first.y + t * dy
+        })
+    }
+
+    /**
+     * Returns whether a point is inside a polygon.
+     * @param {{ x: number, y: number }} point Point.
+     * @param {{ x?: unknown, y?: unknown }[]} polygon Polygon.
+     * @returns {boolean}
+     */
+    static #pointInPolygon(point, polygon) {
+        const points = (Array.isArray(polygon) ? polygon : []).map((entry) =>
+            PcbInteractionGeometry.point(entry)
+        )
+        let inside = false
+        for (
+            let index = 0, previous = points.length - 1;
+            index < points.length;
+            previous = index++
+        ) {
+            const current = points[index]
+            const before = points[previous]
+            const intersects =
+                current.y > point.y !== before.y > point.y &&
+                point.x <
+                    ((before.x - current.x) * (point.y - current.y)) /
+                        (before.y - current.y || Number.EPSILON) +
+                        current.x
+            if (intersects) inside = !inside
+        }
+
+        return inside
+    }
+}

package/src/ui/PcbInteractionIndex.mjs

@@ -0,0 +1,588 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbInteractionGeometry } from './PcbInteractionGeometry.mjs'
+import { PcbInteractionItemRegistry } from './PcbInteractionItemRegistry.mjs'
+
+const TYPE_PRIORITY = {
+    track: 100,
+    pad: 90,
+    via: 80,
+    component: 50,
+    text: 30,
+    zone: 10
+}
+
+const PLURAL_TYPE_KEYS = {
+    component: 'components',
+    pad: 'pads',
+    text: 'footprint-text',
+    track: 'tracks',
+    via: 'vias',
+    zone: 'zones'
+}
+
+/**
+ * Builds and queries selectable PCB items.
+ */
+export class PcbInteractionIndex {
+    /**
+     * Builds all selectable items for a PCB document.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {object[]}
+     */
+    static build(documentModel) {
+        const pcb = documentModel?.pcb || {}
+        const context = PcbInteractionIndex.#context(pcb)
+
+        return PcbInteractionIndex.#defaultRegistry()
+            .extract(documentModel, context)
+            .map((item, index) =>
+                PcbInteractionIndex.#normalizeItem(item, index)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Returns all hit candidates at the requested point.
+     * @param {object} documentModel Toolkit document model.
+     * @param {{ x?: unknown, y?: unknown }} point Hit-test point.
+     * @param {object} [options] Hit-test options.
+     * @returns {object[]}
+     */
+    static hitTest(documentModel, point, options = {}) {
+        return PcbInteractionIndex.build(documentModel)
+            .filter((item) =>
+                PcbInteractionIndex.#isVisibleCandidate(item, options)
+            )
+            .filter((item) =>
+                PcbInteractionGeometry.containsPoint(
+                    item.geometry,
+                    point,
+                    Number(options?.tolerance) || 0
+                )
+            )
+            .sort(PcbInteractionIndex.#compareCandidates)
+    }
+
+    /**
+     * Picks the highest-priority candidate at the requested point.
+     * @param {object} documentModel Toolkit document model.
+     * @param {{ x?: unknown, y?: unknown }} point Hit-test point.
+     * @param {object} [options] Hit-test options.
+     * @returns {object | null}
+     */
+    static pick(documentModel, point, options = {}) {
+        return (
+            PcbInteractionIndex.hitTest(documentModel, point, options)[0] ||
+            null
+        )
+    }
+
+    /**
+     * Creates extraction context for one PCB model.
+     * @param {object} pcb PCB model.
+     * @returns {object}
+     */
+    static #context(pcb) {
+        return {
+            components: Array.isArray(pcb.components) ? pcb.components : [],
+            layerNameFor: PcbInteractionIndex.#layerNameResolver(pcb)
+        }
+    }
+
+    /**
+     * Creates the default item extractor registry.
+     * @returns {PcbInteractionItemRegistry}
+     */
+    static #defaultRegistry() {
+        return PcbInteractionItemRegistry.create()
+            .register('zones', PcbInteractionIndex.#extractZones)
+            .register('tracks', PcbInteractionIndex.#extractTracks)
+            .register('pads', PcbInteractionIndex.#extractPads)
+            .register('vias', PcbInteractionIndex.#extractVias)
+            .register('components', PcbInteractionIndex.#extractComponents)
+            .register('footprint-text', PcbInteractionIndex.#extractTexts)
+    }
+
+    /**
+     * Extracts selectable copper zones.
+     * @param {object} documentModel Toolkit document model.
+     * @param {object} context Extraction context.
+     * @returns {object[]}
+     */
+    static #extractZones(documentModel, context) {
+        const pcb = documentModel?.pcb || {}
+        const zones = [
+            ...(Array.isArray(pcb.regions) ? pcb.regions : []),
+            ...(Array.isArray(pcb.shapeBasedRegions)
+                ? pcb.shapeBasedRegions
+                : []),
+            ...(Array.isArray(pcb.polygons) ? pcb.polygons : [])
+        ]
+
+        return zones
+            .map((zone, index) => {
+                const geometry = PcbInteractionIndex.#zoneGeometry(zone)
+                if (!geometry) return null
+
+                return {
+                    id: PcbInteractionIndex.#itemId('zone', zone, index),
+                    type: 'zone',
+                    label: PcbInteractionIndex.#label('Zone', index),
+                    layerKeys: PcbInteractionIndex.#layerKeys(zone, context),
+                    netName: PcbInteractionIndex.#netName(zone),
+                    side: PcbInteractionIndex.#sideForLayer(zone, context),
+                    geometry,
+                    source: zone
+                }
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Extracts selectable tracks.
+     * @param {object} documentModel Toolkit document model.
+     * @param {object} context Extraction context.
+     * @returns {object[]}
+     */
+    static #extractTracks(documentModel, context) {
+        const tracks = Array.isArray(documentModel?.pcb?.tracks)
+            ? documentModel.pcb.tracks
+            : []
+
+        return tracks.map((track, index) => ({
+            id: PcbInteractionIndex.#itemId('track', track, index),
+            type: 'track',
+            label: PcbInteractionIndex.#label('Track', index),
+            layerKeys: PcbInteractionIndex.#layerKeys(track, context),
+            netName: PcbInteractionIndex.#netName(track),
+            side: PcbInteractionIndex.#sideForLayer(track, context),
+            geometry: PcbInteractionGeometry.segment(
+                { x: track.x1, y: track.y1 },
+                { x: track.x2, y: track.y2 },
+                Math.max(0.5, Number(track.width) / 2 || 0.5)
+            ),
+            source: track
+        }))
+    }
+
+    /**
+     * Extracts selectable pads.
+     * @param {object} documentModel Toolkit document model.
+     * @param {object} context Extraction context.
+     * @returns {object[]}
+     */
+    static #extractPads(documentModel, context) {
+        const pads = Array.isArray(documentModel?.pcb?.pads)
+            ? documentModel.pcb.pads
+            : []
+
+        return pads.map((pad, index) => {
+            const component = PcbInteractionIndex.#componentForPad(pad, context)
+
+            return {
+                id: PcbInteractionIndex.#itemId('pad', pad, index),
+                type: 'pad',
+                label: PcbInteractionIndex.#padLabel(pad, index),
+                layerKeys: PcbInteractionIndex.#layerKeys(pad, context),
+                netName: PcbInteractionIndex.#netName(pad),
+                componentKey: PcbInteractionIndex.#componentKey(component),
+                componentId: PcbInteractionIndex.#componentKey(component),
+                side: PcbInteractionIndex.#sideForLayer(pad, context),
+                geometry: PcbInteractionGeometry.rotatedRectangle({
+                    x: pad.x,
+                    y: pad.y,
+                    width: PcbInteractionIndex.#padWidth(pad),
+                    height: PcbInteractionIndex.#padHeight(pad),
+                    rotation: pad.rotation
+                }),
+                source: pad
+            }
+        })
+    }
+
+    /**
+     * Extracts selectable vias.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {object[]}
+     */
+    static #extractVias(documentModel) {
+        const vias = Array.isArray(documentModel?.pcb?.vias)
+            ? documentModel.pcb.vias
+            : []
+
+        return vias.map((via, index) => ({
+            id: PcbInteractionIndex.#itemId('via', via, index),
+            type: 'via',
+            label: PcbInteractionIndex.#label('Via', index),
+            layerKeys: [],
+            netName: PcbInteractionIndex.#netName(via),
+            side: 'both',
+            geometry: PcbInteractionGeometry.circle(
+                { x: via.x, y: via.y },
+                Math.max(0.5, Number(via.diameter) / 2 || 0.5)
+            ),
+            source: via
+        }))
+    }
+
+    /**
+     * Extracts selectable component body estimates.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {object[]}
+     */
+    static #extractComponents(documentModel) {
+        const components = Array.isArray(documentModel?.pcb?.components)
+            ? documentModel.pcb.components
+            : []
+
+        return components.map((component, index) => {
+            const size = PcbInteractionIndex.#componentSize(component)
+            return {
+                id: PcbInteractionIndex.#itemId('component', component, index),
+                type: 'component',
+                label: PcbInteractionIndex.#componentKey(component),
+                componentKey: PcbInteractionIndex.#componentKey(component),
+                componentId: PcbInteractionIndex.#componentKey(component),
+                layerKeys: [],
+                side:
+                    String(component?.layer || '').toUpperCase() === 'BOTTOM'
+                        ? 'back'
+                        : 'front',
+                geometry: PcbInteractionGeometry.rotatedRectangle({
+                    x: component.x,
+                    y: component.y,
+                    width: size.width,
+                    height: size.height,
+                    rotation: component.rotation
+                }),
+                source: component
+            }
+        })
+    }
+
+    /**
+     * Extracts selectable footprint text.
+     * @param {object} documentModel Toolkit document model.
+     * @param {object} context Extraction context.
+     * @returns {object[]}
+     */
+    static #extractTexts(documentModel, context) {
+        const texts = Array.isArray(documentModel?.pcb?.texts)
+            ? documentModel.pcb.texts
+            : []
+
+        return texts
+            .filter((text) => text?.visible !== false)
+            .map((text, index) => {
+                const component = PcbInteractionIndex.#componentForPad(
+                    text,
+                    context
+                )
+                const height = Math.max(1, Number(text?.height) || 1)
+                const width =
+                    Math.max(1, String(text?.text || '').length) * height * 0.6
+
+                return {
+                    id: PcbInteractionIndex.#itemId('text', text, index),
+                    type: 'text',
+                    label: String(text?.text || 'Text'),
+                    layerKeys: PcbInteractionIndex.#layerKeys(text, context),
+                    componentKey: PcbInteractionIndex.#componentKey(component),
+                    componentId: PcbInteractionIndex.#componentKey(component),
+                    side: PcbInteractionIndex.#sideForLayer(text, context),
+                    geometry: PcbInteractionGeometry.rotatedRectangle({
+                        x: text.x,
+                        y: text.y,
+                        width,
+                        height,
+                        rotation: text.rotation
+                    }),
+                    source: text
+                }
+            })
+    }
+
+    /**
+     * Builds geometry for a zone-like object.
+     * @param {object} zone Zone-like object.
+     * @returns {object | null}
+     */
+    static #zoneGeometry(zone) {
+        if (Array.isArray(zone?.points) && zone.points.length >= 3) {
+            return PcbInteractionGeometry.polygon(zone.points)
+        }
+        if (Array.isArray(zone?.segments) && zone.segments.length >= 3) {
+            return PcbInteractionGeometry.polygon(
+                zone.segments.map((segment) => ({
+                    x: segment.x1,
+                    y: segment.y1
+                }))
+            )
+        }
+        if (
+            Number.isFinite(Number(zone?.x1)) &&
+            Number.isFinite(Number(zone?.y1)) &&
+            Number.isFinite(Number(zone?.x2)) &&
+            Number.isFinite(Number(zone?.y2))
+        ) {
+            return PcbInteractionGeometry.bounds({
+                minX: Math.min(Number(zone.x1), Number(zone.x2)),
+                minY: Math.min(Number(zone.y1), Number(zone.y2)),
+                maxX: Math.max(Number(zone.x1), Number(zone.x2)),
+                maxY: Math.max(Number(zone.y1), Number(zone.y2))
+            })
+        }
+
+        return null
+    }
+
+    /**
+     * Normalizes item metadata.
+     * @param {object | null} item Extracted item.
+     * @param {number} index Stable item order.
+     * @returns {object | null}
+     */
+    static #normalizeItem(item, index) {
+        if (!item || typeof item !== 'object' || !item.geometry) return null
+
+        return {
+            priority: TYPE_PRIORITY[item.type] || 0,
+            order: index,
+            bounds: PcbInteractionGeometry.boundsFor(item.geometry),
+            ...item
+        }
+    }
+
+    /**
+     * Returns whether an item is visible under hit-test filters.
+     * @param {object} item Interaction item.
+     * @param {object} options Hit-test options.
+     * @returns {boolean}
+     */
+    static #isVisibleCandidate(item, options) {
+        const side = PcbInteractionIndex.#normalizeSide(options?.side)
+        if (item.side !== 'both' && item.side !== side) return false
+
+        const hiddenObjects = new Set(
+            (Array.isArray(options?.hiddenObjects)
+                ? options.hiddenObjects
+                : []
+            ).map(String)
+        )
+        if (
+            hiddenObjects.has(item.objectKey) ||
+            hiddenObjects.has(PLURAL_TYPE_KEYS[item.type] || item.type)
+        ) {
+            return false
+        }
+
+        const hiddenLayers = new Set(
+            (Array.isArray(options?.hiddenLayers)
+                ? options.hiddenLayers
+                : []
+            ).map(String)
+        )
+        return (
+            !item.layerKeys?.length ||
+            item.layerKeys.some((layerKey) => !hiddenLayers.has(layerKey))
+        )
+    }
+
+    /**
+     * Compares candidates by priority and stable extraction order.
+     * @param {object} first First item.
+     * @param {object} second Second item.
+     * @returns {number}
+     */
+    static #compareCandidates(first, second) {
+        return second.priority - first.priority || first.order - second.order
+    }
+
+    /**
+     * Creates a layer-name resolver for layer-id based primitives.
+     * @param {object} pcb PCB model.
+     * @returns {(item: object) => string[]}
+     */
+    static #layerNameResolver(pcb) {
+        const byId = new Map()
+        const layers = [
+            ...(Array.isArray(pcb?.layers) ? pcb.layers : []),
+            ...(Array.isArray(pcb?.primitiveLayers) ? pcb.primitiveLayers : [])
+        ]
+
+        for (const layer of layers) {
+            const layerId = Number(layer?.layerId)
+            const name = String(layer?.name || '').trim()
+            if (Number.isInteger(layerId) && name) {
+                byId.set(layerId, name)
+            }
+        }
+
+        return (item) => {
+            const directLayer = String(item?.layer || '').trim()
+            if (directLayer) return [directLayer]
+
+            const layerId = Number(item?.layerId ?? item?.layerCode)
+            if (Number.isInteger(layerId) && byId.has(layerId)) {
+                return [byId.get(layerId)]
+            }
+
+            return []
+        }
+    }
+
+    /**
+     * Resolves physical layer keys for an item.
+     * @param {object} item Source item.
+     * @param {object} context Extraction context.
+     * @returns {string[]}
+     */
+    static #layerKeys(item, context) {
+        return context.layerNameFor(item).filter(Boolean)
+    }
+
+    /**
+     * Resolves the board side from the primary layer.
+     * @param {object} item Source item.
+     * @param {object} context Extraction context.
+     * @returns {'front' | 'back' | 'both'}
+     */
+    static #sideForLayer(item, context) {
+        const layerKey = PcbInteractionIndex.#layerKeys(item, context)[0] || ''
+        const normalized = layerKey.toLowerCase()
+        if (normalized.includes('bottom')) return 'back'
+        if (normalized.includes('top')) return 'front'
+
+        return 'both'
+    }
+
+    /**
+     * Resolves a component for a pad-like primitive.
+     * @param {object} primitive Primitive.
+     * @param {object} context Extraction context.
+     * @returns {object | null}
+     */
+    static #componentForPad(primitive, context) {
+        const componentIndex = Number(primitive?.componentIndex)
+        if (!Number.isInteger(componentIndex)) return null
+
+        return (
+            context.components.find(
+                (component, index) =>
+                    Number(component?.componentIndex) === componentIndex ||
+                    index === componentIndex
+            ) || null
+        )
+    }
+
+    /**
+     * Resolves a stable component key.
+     * @param {object | null} component Component.
+     * @returns {string}
+     */
+    static #componentKey(component) {
+        return String(component?.designator || component?.id || '').trim()
+    }
+
+    /**
+     * Resolves a pad display label.
+     * @param {object} pad Pad.
+     * @param {number} index Pad index.
+     * @returns {string}
+     */
+    static #padLabel(pad, index) {
+        const name = String(pad?.name || pad?.number || '').trim()
+        return name || PcbInteractionIndex.#label('Pad', index)
+    }
+
+    /**
+     * Resolves a net name from common primitive fields.
+     * @param {object} item Primitive.
+     * @returns {string}
+     */
+    static #netName(item) {
+        return String(item?.netName || item?.net || '').trim()
+    }
+
+    /**
+     * Resolves a pad width.
+     * @param {object} pad Pad.
+     * @returns {number}
+     */
+    static #padWidth(pad) {
+        return Math.max(
+            1,
+            Number(pad?.sizeTopX) ||
+                Number(pad?.sizeMidX) ||
+                Number(pad?.sizeBottomX) ||
+                Number(pad?.width) ||
+                1
+        )
+    }
+
+    /**
+     * Resolves a pad height.
+     * @param {object} pad Pad.
+     * @returns {number}
+     */
+    static #padHeight(pad) {
+        return Math.max(
+            1,
+            Number(pad?.sizeTopY) ||
+                Number(pad?.sizeMidY) ||
+                Number(pad?.sizeBottomY) ||
+                Number(pad?.height) ||
+                PcbInteractionIndex.#padWidth(pad)
+        )
+    }
+
+    /**
+     * Resolves a footprint body estimate for interaction.
+     * @param {object} component Component.
+     * @returns {{ width: number, height: number }}
+     */
+    static #componentSize(component) {
+        const pattern = String(component?.pattern || '').toUpperCase()
+        if (pattern.includes('QFN') || pattern.includes('QFP')) {
+            return { width: 180, height: 180 }
+        }
+        if (pattern.includes('SOT')) return { width: 140, height: 90 }
+        if (pattern.includes('0805')) return { width: 92, height: 48 }
+        if (pattern.includes('0603')) return { width: 72, height: 36 }
+        if (pattern.includes('0402')) return { width: 52, height: 28 }
+        return { width: 96, height: 60 }
+    }
+
+    /**
+     * Builds a stable fallback id.
+     * @param {string} type Item type.
+     * @param {object} source Source primitive.
+     * @param {number} index Item index.
+     * @returns {string}
+     */
+    static #itemId(type, source, index) {
+        return String(source?.id || source?.uuid || `${type}:${index}`)
+    }
+
+    /**
+     * Builds a fallback label.
+     * @param {string} base Label base.
+     * @param {number} index Item index.
+     * @returns {string}
+     */
+    static #label(base, index) {
+        return `${base} ${index + 1}`
+    }
+
+    /**
+     * Normalizes side input.
+     * @param {unknown} side Side input.
+     * @returns {'front' | 'back'}
+     */
+    static #normalizeSide(side) {
+        return side === 'bottom' || side === 'back' ? 'back' : 'front'
+    }
+}

package/src/ui/PcbInteractionItemRegistry.mjs

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Stores PCB interaction item extractors by rendered object group.
+ */
+export class PcbInteractionItemRegistry {
+    /** @type {{ objectKey: string, extractor: (input: object, context: object) => object[] }[]} */
+    #entries
+
+    /**
+     * Creates an empty registry.
+     */
+    constructor() {
+        this.#entries = []
+    }
+
+    /**
+     * Creates an empty registry.
+     * @returns {PcbInteractionItemRegistry}
+     */
+    static create() {
+        return new PcbInteractionItemRegistry()
+    }
+
+    /**
+     * Adds an extractor for one object group.
+     * @param {string} objectKey Object visibility key.
+     * @param {(input: object, context: object) => object[]} extractor Extractor.
+     * @returns {PcbInteractionItemRegistry}
+     */
+    register(objectKey, extractor) {
+        if (typeof extractor !== 'function') return this
+        this.#entries.push({
+            objectKey: String(objectKey || ''),
+            extractor
+        })
+        return this
+    }
+
+    /**
+     * Extracts interaction items from all registered groups.
+     * @param {object} input Toolkit document model.
+     * @param {object} [context] Shared extraction context.
+     * @returns {object[]}
+     */
+    extract(input, context = {}) {
+        const items = []
+
+        for (const entry of this.#entries) {
+            const extracted = entry.extractor(input, {
+                ...context,
+                objectKey: entry.objectKey
+            })
+            for (const item of Array.isArray(extracted) ? extracted : []) {
+                items.push({
+                    objectKey: entry.objectKey,
+                    ...item
+                })
+            }
+        }
+
+        return items
+    }
+}

package/src/ui/PcbInteractionLayerModel.mjs

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbInteractionIndex } from './PcbInteractionIndex.mjs'
+
+const VIRTUAL_LAYER_DEFINITIONS = [
+    { key: 'tracks', label: 'Tracks' },
+    { key: 'vias', label: 'Vias' },
+    { key: 'pads', label: 'Pads' },
+    { key: 'holes', label: 'Holes' },
+    { key: 'zones', label: 'Zones' },
+    { key: 'footprint-text', label: 'Footprint text' }
+]
+
+/**
+ * Builds a PCB layer summary with physical layers and virtual controls.
+ */
+export class PcbInteractionLayerModel {
+    /**
+     * Resolves physical and virtual interaction layers.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {{ physicalLayers: object[], virtualLayers: object[] }}
+     */
+    static resolve(documentModel) {
+        const pcb = documentModel?.pcb || {}
+        const physicalLayers = PcbInteractionLayerModel.#physicalLayers(pcb)
+        const items = PcbInteractionIndex.build(documentModel)
+        const layersByObject = PcbInteractionLayerModel.#layersByObject(items)
+
+        return {
+            physicalLayers,
+            virtualLayers: VIRTUAL_LAYER_DEFINITIONS.map((definition) => ({
+                ...definition,
+                physicalLayerKeys: Array.from(
+                    layersByObject.get(definition.key) || []
+                )
+            }))
+        }
+    }
+
+    /**
+     * Resolves physical layer rows from board and primitive layer metadata.
+     * @param {object} pcb PCB model.
+     * @returns {object[]}
+     */
+    static #physicalLayers(pcb) {
+        const seen = new Set()
+        const layers = []
+        const sources = [
+            ...(Array.isArray(pcb?.layers) ? pcb.layers : []),
+            ...(Array.isArray(pcb?.primitiveLayers) ? pcb.primitiveLayers : [])
+        ]
+
+        for (const layer of sources) {
+            const key = String(layer?.name || layer?.layer || '').trim()
+            if (!key || seen.has(key)) continue
+            seen.add(key)
+            layers.push({
+                key,
+                label: key,
+                layerId: Number.isFinite(Number(layer?.layerId))
+                    ? Number(layer.layerId)
+                    : null
+            })
+        }
+
+        return layers
+    }
+
+    /**
+     * Collects referenced physical layer keys by virtual object key.
+     * @param {object[]} items Interaction items.
+     * @returns {Map<string, Set<string>>}
+     */
+    static #layersByObject(items) {
+        const layersByObject = new Map()
+
+        for (const item of items) {
+            if (!layersByObject.has(item.objectKey)) {
+                layersByObject.set(item.objectKey, new Set())
+            }
+            const layerSet = layersByObject.get(item.objectKey)
+            for (const layerKey of item.layerKeys || []) {
+                layerSet.add(layerKey)
+            }
+            if (item.type === 'pad' || item.type === 'via') {
+                if (!layersByObject.has('holes')) {
+                    layersByObject.set('holes', new Set())
+                }
+                for (const layerKey of item.layerKeys || []) {
+                    layersByObject.get('holes').add(layerKey)
+                }
+            }
+        }
+
+        return layersByObject
+    }
+}

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -46,17 +46,82 @@ export class PcbScene3dBoardOutlineRefiner {
             return sceneDescription
         }
 
+        const refinedBoard = {
+            ...board,
+            minX: candidate.minX,
+            minY: candidate.minY,
+            widthMil: candidate.widthMil,
+            heightMil: candidate.heightMil,
+            centerX: candidate.minX + candidate.widthMil / 2,
+            centerY: candidate.minY + candidate.heightMil / 2,
+            segments: candidate.segments
+        }
+
         return {
             ...sceneDescription,
-            board: {
-                ...board,
-                minX: candidate.minX,
-                minY: candidate.minY,
-                widthMil: candidate.widthMil,
-                heightMil: candidate.heightMil,
-                centerX: candidate.minX + candidate.widthMil / 2,
-                centerY: candidate.minY + candidate.heightMil / 2,
-                segments: candidate.segments
+            board: refinedBoard,
+            components: PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                sceneDescription?.components,
+                board,
+                refinedBoard
+            ),
+            externalPlacements:
+                PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                    sceneDescription?.externalPlacements,
+                    board,
+                    refinedBoard
+                )
+        }
+    }
+
+    /**
+     * Realigns precomputed local placements to a refined board center.
+     * @param {object[] | undefined} placements Scene placements.
+     * @param {{ centerX?: number, centerY?: number }} previousBoard Previous board.
+     * @param {{ centerX?: number, centerY?: number }} refinedBoard Refined board.
+     * @returns {object[] | undefined}
+     */
+    static #realignLocalPlacements(placements, previousBoard, refinedBoard) {
+        if (!Array.isArray(placements)) {
+            return placements
+        }
+
+        const deltaX =
+            Number(previousBoard?.centerX || 0) -
+            Number(refinedBoard?.centerX || 0)
+        const deltaY =
+            Number(previousBoard?.centerY || 0) -
+            Number(refinedBoard?.centerY || 0)
+
+        if (!deltaX && !deltaY) {
+            return placements
+        }
+
+        return placements.map((placement) =>
+            PcbScene3dBoardOutlineRefiner.#realignLocalPlacement(
+                placement,
+                deltaX,
+                deltaY
+            )
+        )
+    }
+
+    /**
+     * Applies one local origin delta to a scene placement.
+     * @param {object} placement Scene placement.
+     * @param {number} deltaX Local X delta.
+     * @param {number} deltaY Local Y delta.
+     * @returns {object}
+     */
+    static #realignLocalPlacement(placement, deltaX, deltaY) {
+        const positionMil = placement?.positionMil || {}
+
+        return {
+            ...placement,
+            positionMil: {
+                ...positionMil,
+                x: Number(positionMil.x || 0) + deltaX,
+                y: Number(positionMil.y || 0) + deltaY
             }
         }
     }

package/src/ui/PcbScene3dBuilder.mjs

@@ -19,6 +19,9 @@ export class PcbScene3dBuilder {
     static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
     static #DENSE_OVERLAY_KNOCKOUT_COLOR = 0x2f6a2c
     static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 5
+    static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
+    static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
+    static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
 
     /**
@@ -1159,16 +1162,41 @@ export class PcbScene3dBuilder {
     static #isBodyPositionNearBoard(componentBody, board) {
         const bodyX = Number(componentBody?.positionMil?.x || 0)
         const bodyY = Number(componentBody?.positionMil?.y || 0)
-        const minX = Number(board?.minX || 0) - 600
-        const minY = Number(board?.minY || 0) - 600
+        const xOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.widthMil
+        )
+        const yOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.heightMil
+        )
+        const minX = Number(board?.minX || 0) - xOverhang
+        const minY = Number(board?.minY || 0) - yOverhang
         const maxX =
-            Number(board?.minX || 0) + Number(board?.widthMil || 0) + 600
+            Number(board?.minX || 0) + Number(board?.widthMil || 0) + xOverhang
         const maxY =
-            Number(board?.minY || 0) + Number(board?.heightMil || 0) + 600
+            Number(board?.minY || 0) + Number(board?.heightMil || 0) + yOverhang
 
         return bodyX >= minX && bodyX <= maxX && bodyY >= minY && bodyY <= maxY
     }
 
+    /**
+     * Resolves a proportional unresolved-body margin for one board axis.
+     * @param {number | string | undefined} spanMil Board axis span.
+     * @returns {number}
+     */
+    static #resolveUnmatchedBodyOverhang(spanMil) {
+        const proportional =
+            Math.max(Number(spanMil || 0), 0) *
+            PcbScene3dBuilder.#UNMATCHED_BODY_OVERHANG_RATIO
+
+        return Math.min(
+            PcbScene3dBuilder.#UNMATCHED_BODY_MAX_OVERHANG_MIL,
+            Math.max(
+                proportional,
+                PcbScene3dBuilder.#UNMATCHED_BODY_MIN_OVERHANG_MIL
+            )
+        )
+    }
+
     /**
      * Normalizes one angle into the range [0, 360).
      * @param {number} angle

package/src/ui/PcbSvgRenderer.mjs

@@ -341,7 +341,7 @@ export class PcbSvgRenderer {
             '"><path d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" /></clipPath></defs>' +
-            '<path class="board-outline" d="' +
+            '<path class="board-outline pcb-layer pcb-layer--edge-cuts" data-layer-name="Edge.Cuts" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
             '<g class="pcb-copper-layers" clip-path="url(#' +
@@ -380,7 +380,7 @@ export class PcbSvgRenderer {
             '>' +
             textMarkup +
             '</g>' +
-            '<path class="board-outline board-outline--stroke" d="' +
+            '<path class="board-outline board-outline--stroke pcb-layer pcb-layer--edge-cuts" data-layer-name="Edge.Cuts" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
             '</svg></div></section>'