altium-toolkit 1.1.0 → 1.1.2

package/package.json

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

package/src/core/altium/NaturalStringComparator.mjs

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Compares generated ECAD keys in natural ASCII order without locale collation.
+ */
+export class NaturalStringComparator {
+    /**
+     * Compares two strings with numeric runs ordered by numeric value.
+     * @param {string} left Left value.
+     * @param {string} right Right value.
+     * @returns {number}
+     */
+    static compare(left, right) {
+        const leftValue = String(left ?? '')
+        const rightValue = String(right ?? '')
+        let leftIndex = 0
+        let rightIndex = 0
+
+        while (leftIndex < leftValue.length && rightIndex < rightValue.length) {
+            const leftCode = leftValue.charCodeAt(leftIndex)
+            const rightCode = rightValue.charCodeAt(rightIndex)
+
+            if (leftCode > 0x7f || rightCode > 0x7f) {
+                return leftValue.localeCompare(rightValue, undefined, {
+                    numeric: true
+                })
+            }
+
+            if (
+                NaturalStringComparator.#isDigit(leftCode) &&
+                NaturalStringComparator.#isDigit(rightCode)
+            ) {
+                const digitComparison =
+                    NaturalStringComparator.#compareDigitRuns(
+                        leftValue,
+                        rightValue,
+                        leftIndex,
+                        rightIndex
+                    )
+                if (digitComparison.comparison !== 0) {
+                    return digitComparison.comparison
+                }
+                leftIndex = digitComparison.leftEnd
+                rightIndex = digitComparison.rightEnd
+                continue
+            }
+
+            const normalizedLeft =
+                NaturalStringComparator.#toLowerAsciiCode(leftCode)
+            const normalizedRight =
+                NaturalStringComparator.#toLowerAsciiCode(rightCode)
+            if (normalizedLeft !== normalizedRight) {
+                return normalizedLeft - normalizedRight
+            }
+            if (leftCode !== rightCode) {
+                return leftCode - rightCode
+            }
+
+            leftIndex += 1
+            rightIndex += 1
+        }
+
+        return leftValue.length - rightValue.length
+    }
+
+    /**
+     * Compares numeric runs starting at the provided offsets.
+     * @param {string} leftValue Left value.
+     * @param {string} rightValue Right value.
+     * @param {number} leftStart Left digit offset.
+     * @param {number} rightStart Right digit offset.
+     * @returns {{ comparison: number, leftEnd: number, rightEnd: number }}
+     */
+    static #compareDigitRuns(leftValue, rightValue, leftStart, rightStart) {
+        const leftEnd = NaturalStringComparator.#digitRunEnd(
+            leftValue,
+            leftStart
+        )
+        const rightEnd = NaturalStringComparator.#digitRunEnd(
+            rightValue,
+            rightStart
+        )
+        const leftSignificant = NaturalStringComparator.#skipLeadingZeros(
+            leftValue,
+            leftStart,
+            leftEnd
+        )
+        const rightSignificant = NaturalStringComparator.#skipLeadingZeros(
+            rightValue,
+            rightStart,
+            rightEnd
+        )
+        const leftLength = leftEnd - leftSignificant
+        const rightLength = rightEnd - rightSignificant
+
+        if (leftLength !== rightLength) {
+            return {
+                comparison: leftLength - rightLength,
+                leftEnd,
+                rightEnd
+            }
+        }
+
+        for (
+            let offset = 0;
+            offset < leftLength && offset < rightLength;
+            offset += 1
+        ) {
+            const comparison =
+                leftValue.charCodeAt(leftSignificant + offset) -
+                rightValue.charCodeAt(rightSignificant + offset)
+            if (comparison !== 0) {
+                return { comparison, leftEnd, rightEnd }
+            }
+        }
+
+        return {
+            comparison: leftEnd - leftStart - (rightEnd - rightStart),
+            leftEnd,
+            rightEnd
+        }
+    }
+
+    /**
+     * Returns the offset after one ASCII digit run.
+     * @param {string} value Source value.
+     * @param {number} start Start offset.
+     * @returns {number}
+     */
+    static #digitRunEnd(value, start) {
+        let end = start
+        while (
+            end < value.length &&
+            NaturalStringComparator.#isDigit(value.charCodeAt(end))
+        ) {
+            end += 1
+        }
+        return end
+    }
+
+    /**
+     * Skips leading zeroes while leaving one digit for all-zero runs.
+     * @param {string} value Source value.
+     * @param {number} start Start offset.
+     * @param {number} end End offset.
+     * @returns {number}
+     */
+    static #skipLeadingZeros(value, start, end) {
+        let index = start
+        while (index < end - 1 && value.charCodeAt(index) === 48) {
+            index += 1
+        }
+        return index
+    }
+
+    /**
+     * Returns true for ASCII digit code points.
+     * @param {number} code Character code.
+     * @returns {boolean}
+     */
+    static #isDigit(code) {
+        return code >= 48 && code <= 57
+    }
+
+    /**
+     * Converts uppercase ASCII code points to lowercase.
+     * @param {number} code Character code.
+     * @returns {number}
+     */
+    static #toLowerAsciiCode(code) {
+        return code >= 65 && code <= 90 ? code + 32 : code
+    }
+}

package/src/core/altium/ParserUtils.mjs

@@ -6,6 +6,9 @@
  * Shared parsing helpers for normalized Altium records.
  */
 export class ParserUtils {
+    /** @type {WeakMap<object, Map<string, { raw: unknown, rawUtf8: unknown, value: string }>>} */
+    static #fieldValueCache = new WeakMap()
+
     /**
      * Removes duplicate PCB placements by designator.
      * @param {{ designator: string }[]} components
@@ -141,16 +144,69 @@ export class ParserUtils {
      * @returns {string}
      */
     static #getPreferredFieldValue(fields, key, skipAsterisk) {
-        if (!fields) return ''
+        if (!fields || typeof fields !== 'object') return ''
 
         const utf8Key = 'UTF8:' + key
-        const utf8Value = ParserUtils.#pickFieldValue(
-            fields[utf8Key],
-            skipAsterisk
+        const rawUtf8 = fields[utf8Key]
+        const raw = fields[key]
+
+        if (!Array.isArray(rawUtf8) && !Array.isArray(raw)) {
+            const utf8Value = ParserUtils.#pickFieldValue(rawUtf8, skipAsterisk)
+            return utf8Value || ParserUtils.#pickFieldValue(raw, skipAsterisk)
+        }
+
+        const cacheKey = key + ':' + (skipAsterisk ? 'text' : 'field')
+        const cached = ParserUtils.#cachedFieldValue(
+            fields,
+            cacheKey,
+            raw,
+            rawUtf8
         )
-        if (utf8Value) return utf8Value
+        if (cached !== null) return cached
+
+        const utf8Value = ParserUtils.#pickFieldValue(rawUtf8, skipAsterisk)
+        const value =
+            utf8Value || ParserUtils.#pickFieldValue(raw, skipAsterisk)
+
+        ParserUtils.#cacheFieldValue(fields, cacheKey, raw, rawUtf8, value)
+        return value
+    }
 
-        return ParserUtils.#pickFieldValue(fields[key], skipAsterisk)
+    /**
+     * Returns a cached normalized value when the raw field references match.
+     * @param {object} fields Field object.
+     * @param {string} cacheKey Cache key.
+     * @param {unknown} raw Raw field payload.
+     * @param {unknown} rawUtf8 Raw UTF-8 field payload.
+     * @returns {string | null}
+     */
+    static #cachedFieldValue(fields, cacheKey, raw, rawUtf8) {
+        const fieldCache = ParserUtils.#fieldValueCache.get(fields)
+        const cached = fieldCache?.get(cacheKey)
+        if (!cached || cached.raw !== raw || cached.rawUtf8 !== rawUtf8) {
+            return null
+        }
+
+        return cached.value
+    }
+
+    /**
+     * Stores one normalized field value.
+     * @param {object} fields Field object.
+     * @param {string} cacheKey Cache key.
+     * @param {unknown} raw Raw field payload.
+     * @param {unknown} rawUtf8 Raw UTF-8 field payload.
+     * @param {string} value Normalized value.
+     * @returns {void}
+     */
+    static #cacheFieldValue(fields, cacheKey, raw, rawUtf8, value) {
+        let fieldCache = ParserUtils.#fieldValueCache.get(fields)
+        if (!fieldCache) {
+            fieldCache = new Map()
+            ParserUtils.#fieldValueCache.set(fields, fieldCache)
+        }
+
+        fieldCache.set(cacheKey, { raw, rawUtf8, value })
     }
 
     /**
@@ -160,14 +216,27 @@ export class ParserUtils {
      * @returns {string}
      */
     static #pickFieldValue(raw, skipAsterisk) {
-        const values = Array.isArray(raw) ? raw : [raw]
+        if (!Array.isArray(raw)) {
+            const value = ParserUtils.#normalizeFieldValue(raw)
+            return value && (!skipAsterisk || value !== '*') ? value : ''
+        }
 
-        return (
-            values
-                .map((value) => String(value || '').trim())
-                .findLast(
-                    (value) => value && (!skipAsterisk || value !== '*')
-                ) || ''
-        )
+        for (let index = raw.length - 1; index >= 0; index -= 1) {
+            const value = ParserUtils.#normalizeFieldValue(raw[index])
+            if (value && (!skipAsterisk || value !== '*')) {
+                return value
+            }
+        }
+
+        return ''
+    }
+
+    /**
+     * Normalizes one field payload value.
+     * @param {string | undefined} value
+     * @returns {string}
+     */
+    static #normalizeFieldValue(value) {
+        return String(value || '').trim()
     }
 }

package/src/core/altium/PcbComponentPrimitiveIndexer.mjs

@@ -14,47 +14,54 @@ export class PcbComponentPrimitiveIndexer {
      * @returns {{ componentIndex: number, designator: string, pads: object[], tracks: object[], arcs: object[], fills: object[], vias: object[], regions: object[], shapeBasedRegions: object[], texts: object[], componentBodies: object[] }[]}
      */
     static buildGroups(components, pcb, componentBodies) {
+        const primitiveGroups =
+            PcbComponentPrimitiveIndexer.#primitiveGroupsByComponent(
+                pcb,
+                componentBodies
+            )
+
         return (components || []).map((component) => {
             const componentIndex = Number(component.componentIndex)
 
             return {
                 componentIndex,
                 designator: component.designator,
-                pads: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.pads,
+                pads: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.pads,
                     componentIndex
                 ),
-                tracks: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.tracks,
+                tracks: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.tracks,
                     componentIndex
                 ),
-                arcs: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.arcs,
+                arcs: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.arcs,
                     componentIndex
                 ),
-                fills: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.fills,
+                fills: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.fills,
                     componentIndex
                 ),
-                vias: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.vias,
+                vias: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.vias,
                     componentIndex
                 ),
-                regions: PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                    pcb.regions,
+                regions: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.regions,
                     componentIndex
                 ),
                 shapeBasedRegions:
-                    PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                        pcb.shapeBasedRegions,
+                    PcbComponentPrimitiveIndexer.#groupForComponent(
+                        primitiveGroups.shapeBasedRegions,
                         componentIndex
                     ),
-                texts: (pcb.texts || []).filter(
-                    (text) => Number(text?.ownerIndex) === componentIndex
+                texts: PcbComponentPrimitiveIndexer.#groupForComponent(
+                    primitiveGroups.texts,
+                    componentIndex
                 ),
                 componentBodies:
-                    PcbComponentPrimitiveIndexer.#primitivesForComponent(
-                        componentBodies,
+                    PcbComponentPrimitiveIndexer.#groupForComponent(
+                        primitiveGroups.componentBodies,
                         componentIndex
                     )
             }
@@ -87,23 +94,87 @@ export class PcbComponentPrimitiveIndexer {
     }
 
     /**
-     * Returns primitives linked to a component by native Altium index.
-     * @param {{ componentIndex?: number | null }[] | undefined} primitives
-     * @param {number} componentIndex
-     * @returns {object[]}
+     * Builds primitive maps by native component ownership index.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[], vias?: object[], pads?: object[], regions?: object[], shapeBasedRegions?: object[], texts?: object[] }} pcb
+     * @param {{ componentIndex?: number | null }[]} componentBodies
+     * @returns {{ pads: Map<number, object[]>, tracks: Map<number, object[]>, arcs: Map<number, object[]>, fills: Map<number, object[]>, vias: Map<number, object[]>, regions: Map<number, object[]>, shapeBasedRegions: Map<number, object[]>, texts: Map<number, object[]>, componentBodies: Map<number, object[]> }}
+     */
+    static #primitiveGroupsByComponent(pcb, componentBodies) {
+        return {
+            pads: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.pads
+            ),
+            tracks: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.tracks
+            ),
+            arcs: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.arcs
+            ),
+            fills: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.fills
+            ),
+            vias: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.vias
+            ),
+            regions: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.regions
+            ),
+            shapeBasedRegions:
+                PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                    pcb?.shapeBasedRegions
+                ),
+            texts: PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                pcb?.texts,
+                'ownerIndex'
+            ),
+            componentBodies:
+                PcbComponentPrimitiveIndexer.#groupPrimitivesByIndex(
+                    componentBodies
+                )
+        }
+    }
+
+    /**
+     * Groups primitives by one numeric owner-index field.
+     * @param {object[] | undefined} primitives Source primitives.
+     * @param {string} key Owner-index field name.
+     * @returns {Map<number, object[]>}
      */
-    static #primitivesForComponent(primitives, componentIndex) {
-        return (primitives || []).filter((primitive) => {
-            const rawComponentIndex = primitive?.componentIndex
-            if (
-                rawComponentIndex === null ||
-                rawComponentIndex === undefined ||
-                rawComponentIndex === ''
-            ) {
-                return false
+    static #groupPrimitivesByIndex(primitives, key = 'componentIndex') {
+        const groupedPrimitives = new Map()
+
+        for (const primitive of primitives || []) {
+            const componentIndex = PcbComponentPrimitiveIndexer.#optionalIndex(
+                primitive?.[key]
+            )
+            if (componentIndex === null) continue
+            if (!groupedPrimitives.has(componentIndex)) {
+                groupedPrimitives.set(componentIndex, [])
             }
+            groupedPrimitives.get(componentIndex).push(primitive)
+        }
 
-            return Number(rawComponentIndex) === componentIndex
-        })
+        return groupedPrimitives
+    }
+
+    /**
+     * Returns primitives linked to one component index.
+     * @param {Map<number, object[]>} groupedPrimitives Grouped primitives.
+     * @param {number} componentIndex Component index.
+     * @returns {object[]}
+     */
+    static #groupForComponent(groupedPrimitives, componentIndex) {
+        return groupedPrimitives.get(componentIndex) || []
+    }
+
+    /**
+     * Parses one optional component owner index.
+     * @param {unknown} value Candidate index value.
+     * @returns {number | null}
+     */
+    static #optionalIndex(value) {
+        if (value === null || value === undefined || value === '') return null
+        const index = Number(value)
+        return Number.isFinite(index) ? index : null
     }
 }

package/src/core/altium/PcbLayerStackReadModelBuilder.mjs

@@ -14,6 +14,8 @@ const { parseNumericField } = ParserUtils
 export class PcbLayerStackReadModelBuilder {
     static SCHEMA_ID = 'altium-toolkit.pcb.layer-stack.a1'
 
+    static #fieldIndexes = new WeakMap()
+
     /**
      * Builds the layer-stack sidecar.
      * @param {{ fileName: string, boardRecords: { fields: Record<string, string | string[]>, sourceStream?: string }[], streamNames?: string[], layers: object[], primitiveLayers: object[], layerSubstacks: object[], boardRegions: object[] }} input Source model context.
@@ -799,17 +801,37 @@ export class PcbLayerStackReadModelBuilder {
      * @returns {string}
      */
     static #field(fields, key) {
-        if (Object.hasOwn(fields, key)) {
+        if (Object.hasOwn(fields, key) || key in fields) {
             return ParserUtils.getField(fields, key)
         }
-        const upperKey = key.toUpperCase()
-        const realKey = Object.keys(fields).find(
-            (fieldKey) => fieldKey.toUpperCase() === upperKey
+        const realKey = PcbLayerStackReadModelBuilder.#fieldIndex(fields).get(
+            key.toUpperCase()
         )
 
         return realKey ? ParserUtils.getField(fields, realKey) : ''
     }
 
+    /**
+     * Builds or returns a cached case-insensitive field-key index.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {Map<string, string>}
+     */
+    static #fieldIndex(fields) {
+        const cached = PcbLayerStackReadModelBuilder.#fieldIndexes.get(fields)
+        if (cached) return cached
+
+        const fieldIndex = new Map()
+        for (const fieldKey of Object.keys(fields)) {
+            const upperKey = fieldKey.toUpperCase()
+            if (!fieldIndex.has(upperKey)) {
+                fieldIndex.set(upperKey, fieldKey)
+            }
+        }
+
+        PcbLayerStackReadModelBuilder.#fieldIndexes.set(fields, fieldIndex)
+        return fieldIndex
+    }
+
     /**
      * Parses layer-id lists.
      * @param {string} value Raw list value.

package/src/core/altium/PcbLayerStackSourceMetadataParser.mjs

@@ -8,6 +8,8 @@ import { ParserUtils } from './ParserUtils.mjs'
  * Parses source-only layer-stack metadata that is not part of core geometry.
  */
 export class PcbLayerStackSourceMetadataParser {
+    static #fieldIndexes = new WeakMap()
+
     /**
      * Parses source-aware extras for one layer-stack row.
      * @param {Record<string, string | string[]>} fields Source fields.
@@ -401,17 +403,38 @@ export class PcbLayerStackSourceMetadataParser {
      * @returns {string}
      */
     static #field(fields, key) {
-        if (Object.hasOwn(fields, key)) {
+        if (Object.hasOwn(fields, key) || key in fields) {
             return ParserUtils.getField(fields, key)
         }
-        const upperKey = key.toUpperCase()
-        const realKey = Object.keys(fields).find(
-            (fieldKey) => fieldKey.toUpperCase() === upperKey
-        )
+        const realKey = PcbLayerStackSourceMetadataParser.#fieldIndex(
+            fields
+        ).get(key.toUpperCase())
 
         return realKey ? ParserUtils.getField(fields, realKey) : ''
     }
 
+    /**
+     * Builds or returns a cached case-insensitive field-key index.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {Map<string, string>}
+     */
+    static #fieldIndex(fields) {
+        const cached =
+            PcbLayerStackSourceMetadataParser.#fieldIndexes.get(fields)
+        if (cached) return cached
+
+        const fieldIndex = new Map()
+        for (const fieldKey of Object.keys(fields)) {
+            const upperKey = fieldKey.toUpperCase()
+            if (!fieldIndex.has(upperKey)) {
+                fieldIndex.set(upperKey, fieldKey)
+            }
+        }
+
+        PcbLayerStackSourceMetadataParser.#fieldIndexes.set(fields, fieldIndex)
+        return fieldIndex
+    }
+
     /**
      * Splits a native list field.
      * @param {string} value Raw list value.

package/src/core/altium/PcbOwnershipGraphBuilder.mjs

@@ -228,9 +228,7 @@ export class PcbOwnershipGraphBuilder {
         if (!groups[key]) {
             groups[key] = fallbackGroup
         }
-        if (!groups[key].primitiveKeys.includes(primitiveKey)) {
-            groups[key].primitiveKeys.push(primitiveKey)
-        }
+        groups[key].primitiveKeys.push(primitiveKey)
     }
 
     /**