altium-toolkit 1.4.16 → 1.4.17

package/spec/library-scope.md

@@ -7,8 +7,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 # Library Scope
 
 Altium Toolkit provides reusable native Altium parsing behind the common ECAD
-toolkit API. Canonical results use CircuitJSON; source-only facts and all
-historical 1.1.41 contracts remain explicit Altium extensions.
+toolkit API. Canonical results use CircuitJSON; source-only facts and historical
+1.1.41 APIs remain explicit Altium extensions with maintained implementations.
 
 ## In Scope
 
@@ -18,7 +18,8 @@ historical 1.1.41 contracts remain explicit Altium extensions.
   reusable document contexts
 - Shared CircuitJSON render, interaction, query, manufacturing, simulation,
   and data-only 3D scene services
-- Exact `/extensions` preservation of audited Altium 1.1.41 behavior
+- Preservation of audited Altium 1.1.41 `/extensions` API signatures and public
+  asset entrypoints and targets, with tested bug fixes and performance improvements
 - `.SchDoc`, `.PcbDoc`, `.PCBDwf`, `.SchLib`, `.PcbLib`, `.PrjPcb`, `.PrjScr`,
   and `.IntLib` parsing from `ArrayBuffer`
 - OLE and binary stream helpers needed by parser recovery

package/src/convergence/AltiumWorkerClient.mjs

@@ -74,18 +74,9 @@ export class AltiumWorkerClient {
      */
     static #client() {
         if (!client) {
-            client = new ParserWorkerClient({
-                createWorker: () => {
-                    const WorkerConstructor = globalThis.Worker
-                    return Reflect.construct(WorkerConstructor, [
-                        new URL(
-                            '../workers/parser.worker.mjs',
-                            import.meta.url
-                        ),
-                        { type: 'module' }
-                    ])
-                }
-            })
+            client = ParserWorkerClient.fromWorkerUrl(
+                new URL('../workers/parser.worker.mjs', import.meta.url)
+            )
         }
         return client
     }

package/src/ui/AltiumScene3dBodyPlacementIndex.mjs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Matches placements to authored bodies within one adapter invocation. */
+export class AltiumScene3dBodyPlacementIndex {
+    #cells = new Map()
+
+    /**
+     * Groups authored body positions into one-mil cells in source order.
+     * @param {object[]} componentBodies Source component bodies.
+     */
+    constructor(componentBodies) {
+        componentBodies.forEach((componentBody, order) => {
+            const x = Number(componentBody?.positionMil?.x || 0)
+            const y = Number(componentBody?.positionMil?.y || 0)
+            if (!Number.isFinite(x) || !Number.isFinite(y)) return
+            const key = `${Math.floor(x)}:${Math.floor(y)}`
+            const cell = this.#cells.get(key) || []
+            cell.push({ componentBody, x, y, order })
+            this.#cells.set(key, cell)
+        })
+    }
+
+    /**
+     * Selects by identity affinity, distance, then original source order.
+     * @param {object} placement Built external placement.
+     * @returns {object | null}
+     */
+    resolve(placement) {
+        const x = Number(placement?.bodyPositionMil?.x || 0)
+        const y = Number(placement?.bodyPositionMil?.y || 0)
+        if (!Number.isFinite(x) || !Number.isFinite(y)) return null
+        const placementText = AltiumScene3dBodyPlacementIndex.#identityText([
+            placement?.designator,
+            placement?.externalModel?.name
+        ])
+        let best = null
+        let bestScore = -1
+        let bestDistance = Infinity
+        for (const dx of [-1, 0, 1]) {
+            for (const dy of [-1, 0, 1]) {
+                const cell =
+                    this.#cells.get(
+                        `${Math.floor(x) + dx}:${Math.floor(y) + dy}`
+                    ) || []
+                for (const candidate of cell) {
+                    const distance = Math.hypot(
+                        x - candidate.x,
+                        y - candidate.y
+                    )
+                    if (!(distance <= 0.01)) continue
+                    const bodyText =
+                        AltiumScene3dBodyPlacementIndex.#identityText([
+                            candidate.componentBody?.identifier,
+                            candidate.componentBody?.name
+                        ])
+                    const score =
+                        placementText &&
+                        bodyText &&
+                        placementText.includes(bodyText)
+                            ? bodyText.length
+                            : 0
+                    if (
+                        best &&
+                        !(
+                            score > bestScore ||
+                            (score === bestScore &&
+                                (distance < bestDistance ||
+                                    (distance === bestDistance &&
+                                        candidate.order < best.order)))
+                        )
+                    )
+                        continue
+                    best = candidate
+                    bestScore = score
+                    bestDistance = distance
+                }
+            }
+        }
+        return best?.componentBody || null
+    }
+
+    /**
+     * Normalizes metadata with the placement adapter's identity convention.
+     * @param {unknown[]} values Source identity fields.
+     * @returns {string}
+     */
+    static #identityText(values) {
+        return values
+            .map((value) => String(value || '').toLowerCase())
+            .join(' ')
+            .replace(/\.[a-z0-9]+\\b/g, '')
+            .replace(/[^a-z0-9]+/g, '')
+    }
+}

package/src/ui/AltiumScene3dComponentBodyAdapter.mjs

@@ -1,3 +1,4 @@
+import { PcbScene3dComponentGeometryResolver } from './PcbScene3dComponentGeometryResolver.mjs'
 import { PcbScene3dPadLocalSpanResolver } from './PcbScene3dPadLocalSpanResolver.mjs'
 
 const REFINABLE_FAMILIES = new Set(['chip', 'diode', 'generic', 'ic', 'sot'])
@@ -33,6 +34,10 @@ export class AltiumScene3dComponentBodyAdapter {
             return sceneDescription
         }
 
+        const componentGeometry = new PcbScene3dComponentGeometryResolver(
+            sourceComponents,
+            pads
+        )
         const sourceByDesignator = new Map(
             sourceComponents.map((component) => [
                 String(component?.designator || ''),
@@ -46,7 +51,7 @@ export class AltiumScene3dComponentBodyAdapter {
                 AltiumScene3dComponentBodyAdapter.#refineComponent(
                     component,
                     sourceByDesignator.get(String(component?.designator || '')),
-                    pads
+                    componentGeometry
                 )
             )
         }
@@ -56,10 +61,10 @@ export class AltiumScene3dComponentBodyAdapter {
      * Refines one procedural component body when nearby pads overinflated it.
      * @param {object} component Scene component.
      * @param {object | undefined} sourceComponent Source PCB component.
-     * @param {object[]} pads Source PCB pads.
+     * @param {PcbScene3dComponentGeometryResolver} componentGeometry Build-scoped geometry.
      * @returns {object}
      */
-    static #refineComponent(component, sourceComponent, pads) {
+    static #refineComponent(component, sourceComponent, componentGeometry) {
         const family = String(component?.body?.family || '')
         if (
             component?.externalModel ||
@@ -72,7 +77,7 @@ export class AltiumScene3dComponentBodyAdapter {
         const span = AltiumScene3dComponentBodyAdapter.#ownedPadSpan(
             sourceComponent,
             component.mountSide,
-            pads
+            componentGeometry
         )
         const size = component?.body?.sizeMil || {}
         if (
@@ -99,42 +104,17 @@ export class AltiumScene3dComponentBodyAdapter {
      * Resolves the owned surface-pad span for one source component.
      * @param {object} component Source component.
      * @param {string} mountSide Component mount side.
-     * @param {object[]} pads Source PCB pads.
+     * @param {PcbScene3dComponentGeometryResolver} componentGeometry Build-scoped geometry.
      * @returns {{ width: number, depth: number } | null}
      */
-    static #ownedPadSpan(component, mountSide, pads) {
-        const componentIndex = Number(component?.componentIndex)
-        if (!Number.isFinite(componentIndex)) {
-            return null
-        }
-
-        const ownedPads = pads.filter(
-            (pad) => Number(pad?.componentIndex) === componentIndex
-        )
-        const surfacePads = ownedPads.filter((pad) =>
-            AltiumScene3dComponentBodyAdapter.#isSurfacePad(pad, mountSide)
-        )
-        const spanPads = surfacePads.length ? surfacePads : ownedPads
-
+    static #ownedPadSpan(component, mountSide, componentGeometry) {
         return PcbScene3dPadLocalSpanResolver.resolve(
             component,
-            spanPads,
+            componentGeometry.componentPads(component, mountSide),
             mountSide
         )
     }
 
-    /**
-     * Checks whether one pad belongs to the component's mounted surface.
-     * @param {object} pad Source pad.
-     * @param {string} mountSide Component mount side.
-     * @returns {boolean}
-     */
-    static #isSurfacePad(pad, mountSide) {
-        return String(mountSide || '').toLowerCase() === 'bottom'
-            ? Boolean(pad?.hasBottomPasteMaskOpening)
-            : Boolean(pad?.hasTopPasteMaskOpening)
-    }
-
     /**
      * Checks whether the current body is clearly larger than owned pads.
      * @param {object} size Current body size.

package/src/ui/AltiumScene3dExternalPlacementAdapter.mjs

@@ -1,3 +1,4 @@
+import { AltiumScene3dBodyPlacementIndex } from './AltiumScene3dBodyPlacementIndex.mjs'
 import { AltiumScene3dIdentityTokens } from './AltiumScene3dIdentityTokens.mjs'
 import { AltiumScene3dAuthoredConnectorYawPolicy } from './AltiumScene3dAuthoredConnectorYawPolicy.mjs'
 import { AltiumScene3dPlacementRotationPolicy } from './AltiumScene3dPlacementRotationPolicy.mjs'
@@ -59,6 +60,7 @@ export class AltiumScene3dExternalPlacementAdapter {
             ])
         )
 
+        const bodyIndex = new AltiumScene3dBodyPlacementIndex(componentBodies)
         const repairedScene = {
             ...sceneDescription,
             externalPlacements: sceneDescription.externalPlacements
@@ -67,7 +69,7 @@ export class AltiumScene3dExternalPlacementAdapter {
                         placement,
                         components,
                         componentByDesignator,
-                        componentBodies,
+                        bodyIndex,
                         pads,
                         sceneDescription?.board
                     )
@@ -86,7 +88,7 @@ export class AltiumScene3dExternalPlacementAdapter {
         placement,
         components,
         componentByDesignator,
-        componentBodies,
+        bodyIndex,
         pads,
         board
     ) {
@@ -101,11 +103,7 @@ export class AltiumScene3dExternalPlacementAdapter {
             return placement
         }
 
-        const componentBody =
-            AltiumScene3dExternalPlacementAdapter.#resolveComponentBody(
-                placement,
-                componentBodies
-            )
+        const componentBody = bodyIndex.resolve(placement)
         const currentComponent = componentByDesignator.get(
             String(placement?.designator || '')
         )
@@ -1542,60 +1540,6 @@ export class AltiumScene3dExternalPlacementAdapter {
         ]
     }
 
-    /**
-     * Resolves the source component body row for one placement.
-     * @param {object} placement External model placement.
-     * @param {object[]} componentBodies Source component body rows.
-     * @returns {object | null}
-     */
-    static #resolveComponentBody(placement, componentBodies) {
-        const candidates = componentBodies
-            .map((componentBody) => ({
-                componentBody,
-                distance:
-                    AltiumScene3dExternalPlacementAdapter.#distanceBetweenPoints(
-                        placement?.bodyPositionMil,
-                        componentBody?.positionMil
-                    ),
-                identityScore:
-                    AltiumScene3dExternalPlacementAdapter.#bodyPlacementIdentityScore(
-                        placement,
-                        componentBody
-                    )
-            }))
-            .filter((candidate) => candidate.distance <= 0.01)
-            .sort(
-                (left, right) =>
-                    right.identityScore - left.identityScore ||
-                    left.distance - right.distance
-            )
-
-        return candidates[0]?.componentBody || null
-    }
-
-    /**
-     * Scores whether a source body row belongs to one placement.
-     * @param {object} placement External model placement.
-     * @param {object} componentBody Source component body.
-     * @returns {number}
-     */
-    static #bodyPlacementIdentityScore(placement, componentBody) {
-        const placementText =
-            AltiumScene3dExternalPlacementAdapter.#normalizeIdentityText([
-                placement?.designator,
-                placement?.externalModel?.name
-            ])
-        const bodyText =
-            AltiumScene3dExternalPlacementAdapter.#normalizeIdentityText([
-                componentBody?.identifier,
-                componentBody?.name
-            ])
-
-        return placementText && bodyText && placementText.includes(bodyText)
-            ? bodyText.length
-            : 0
-    }
-
     /**
      * Repairs model-local Altium rotation signs for embedded body transforms.
      * @param {object | null | undefined} modelTransform Placement transform.

package/src/ui/PcbInteractionIndex.mjs

@@ -4,6 +4,7 @@
 
 import { PcbInteractionGeometry } from './PcbInteractionGeometry.mjs'
 import { PcbInteractionItemRegistry } from './PcbInteractionItemRegistry.mjs'
+import { PcbInteractionSourceMetadata } from './PcbInteractionSourceMetadata.mjs'
 
 const TYPE_PRIORITY = {
     track: 100,
@@ -67,15 +68,18 @@ export class PcbInteractionIndex {
      * @returns {object[]}
      */
     static hitTestItems(items, point, options = {}) {
+        const visibility = PcbInteractionIndex.#visibilityContext(options)
+        const tolerance = Number(options?.tolerance) || 0
+
         return (Array.isArray(items) ? items : [])
             .filter((item) =>
-                PcbInteractionIndex.#isVisibleCandidate(item, options)
+                PcbInteractionIndex.#isVisibleCandidate(item, visibility)
             )
             .filter((item) =>
                 PcbInteractionGeometry.containsPoint(
                     item.geometry,
                     point,
-                    Number(options?.tolerance) || 0
+                    tolerance
                 )
             )
             .sort(PcbInteractionIndex.#compareCandidates)
@@ -101,9 +105,23 @@ export class PcbInteractionIndex {
      * @returns {object}
      */
     static #context(pcb) {
+        const components = Array.isArray(pcb.components) ? pcb.components : []
+        const componentsById = new Map()
+        for (const component of components) {
+            const componentIndex = Number(component?.componentIndex)
+            if (
+                Number.isInteger(componentIndex) &&
+                !componentsById.has(componentIndex)
+            ) {
+                // Explicit identities take precedence, retaining the first row.
+                componentsById.set(componentIndex, component)
+            }
+        }
+
         return {
-            components: Array.isArray(pcb.components) ? pcb.components : [],
-            layerNameFor: PcbInteractionIndex.#layerNameResolver(pcb)
+            components,
+            componentsById,
+            layerNameFor: PcbInteractionSourceMetadata.layerNameResolver(pcb)
         }
     }
 
@@ -129,13 +147,7 @@ export class PcbInteractionIndex {
      */
     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 : [])
-        ]
+        const zones = PcbInteractionSourceMetadata.zoneSources(pcb)
 
         return zones
             .map((zone, index) => {
@@ -326,10 +338,11 @@ export class PcbInteractionIndex {
      * @returns {object | null}
      */
     static #zoneGeometry(zone) {
-        if (Array.isArray(zone?.points) && zone.points.length >= 3) {
+        const kind = PcbInteractionSourceMetadata.zoneGeometryKind(zone)
+        if (kind === 'points') {
             return PcbInteractionGeometry.polygon(zone.points)
         }
-        if (Array.isArray(zone?.segments) && zone.segments.length >= 3) {
+        if (kind === 'segments') {
             return PcbInteractionGeometry.polygon(
                 zone.segments.map((segment) => ({
                     x: segment.x1,
@@ -337,12 +350,7 @@ export class PcbInteractionIndex {
                 }))
             )
         }
-        if (
-            Number.isFinite(Number(zone?.x1)) &&
-            Number.isFinite(Number(zone?.y1)) &&
-            Number.isFinite(Number(zone?.x2)) &&
-            Number.isFinite(Number(zone?.y2))
-        ) {
+        if (kind === 'bounds') {
             return PcbInteractionGeometry.bounds({
                 minX: Math.min(Number(zone.x1), Number(zone.x2)),
                 minY: Math.min(Number(zone.y1), Number(zone.y2)),
@@ -372,21 +380,38 @@ export class PcbInteractionIndex {
     }
 
     /**
-     * Returns whether an item is visible under hit-test filters.
-     * @param {object} item Interaction item.
+     * Normalizes visibility filters once for the current hit test.
      * @param {object} options Hit-test options.
+     * @returns {object}
+     */
+    static #visibilityContext(options) {
+        return {
+            side: PcbInteractionIndex.#normalizeSide(options?.side),
+            hiddenObjects: new Set(
+                (Array.isArray(options?.hiddenObjects)
+                    ? options.hiddenObjects
+                    : []
+                ).map(String)
+            ),
+            hiddenLayers: new Set(
+                (Array.isArray(options?.hiddenLayers)
+                    ? options.hiddenLayers
+                    : []
+                ).map(String)
+            )
+        }
+    }
+
+    /**
+     * Returns whether an item is visible under normalized hit-test filters.
+     * @param {object} item Interaction item.
+     * @param {object} visibility Normalized visibility filters.
      * @returns {boolean}
      */
-    static #isVisibleCandidate(item, options) {
-        const side = PcbInteractionIndex.#normalizeSide(options?.side)
+    static #isVisibleCandidate(item, visibility) {
+        const { side, hiddenObjects, hiddenLayers } = visibility
         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)
@@ -394,12 +419,6 @@ export class PcbInteractionIndex {
             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))
@@ -416,39 +435,6 @@ export class PcbInteractionIndex {
         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.
@@ -484,18 +470,13 @@ export class PcbInteractionIndex {
         const componentIndex = Number(primitive?.componentIndex)
         if (!Number.isInteger(componentIndex)) return null
 
-        const explicitMatch =
-            context.components.find(
-                (component) =>
-                    Number(component?.componentIndex) === componentIndex
-            ) || null
+        const explicitMatch = context.componentsById.get(componentIndex)
         if (explicitMatch) return explicitMatch
 
-        return (
-            context.components.find((component, index) => {
-                return index === componentIndex
-            }) || null
-        )
+        if (componentIndex < 0 || componentIndex >= context.components.length) {
+            return null
+        }
+        return context.components[componentIndex] || null
     }
 
     /**

package/src/ui/PcbInteractionLayerModel.mjs

@@ -2,7 +2,7 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import { PcbInteractionIndex } from './PcbInteractionIndex.mjs'
+import { PcbInteractionSourceMetadata } from './PcbInteractionSourceMetadata.mjs'
 
 const VIRTUAL_LAYER_DEFINITIONS = [
     { key: 'tracks', label: 'Tracks' },
@@ -25,8 +25,7 @@ export class PcbInteractionLayerModel {
     static resolve(documentModel) {
         const pcb = documentModel?.pcb || {}
         const physicalLayers = PcbInteractionLayerModel.#physicalLayers(pcb)
-        const items = PcbInteractionIndex.build(documentModel)
-        const layersByObject = PcbInteractionLayerModel.#layersByObject(items)
+        const layersByObject = PcbInteractionSourceMetadata.layersByObject(pcb)
 
         return {
             physicalLayers,
@@ -71,33 +70,4 @@ export class PcbInteractionLayerModel {
 
         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
-    }
 }