altium-toolkit 1.1.3 → 1.1.22

package/src/core/altium/AltiumPcbLibExporter.mjs

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { OleCompoundDocumentWriter } from '../ole/OleCompoundDocumentWriter.mjs'
+import { AltiumLibraryRecordBuilder } from './AltiumLibraryRecordBuilder.mjs'
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized bundles into a compact OLE-backed footprint library.
+ */
+export class AltiumPcbLibExporter {
+    /**
+     * Exports one or more component bundles as `.PcbLib` bytes.
+     * @param {object[] | object} bundles Component bundles.
+     * @returns {Uint8Array}
+     */
+    static export(bundles) {
+        const normalizedBundles =
+            AltiumPcbLibExporter.#normalizeBundles(bundles)
+        const streams = new Map()
+        const modelRows = AltiumPcbLibExporter.#collectModels(normalizedBundles)
+
+        streams.set(
+            'Library/Data',
+            AltiumLibraryRecordBuilder.buildPcbLibraryData(normalizedBundles)
+        )
+        streams.set(
+            'Library/ComponentParamsTOC/Data',
+            AltiumLibraryRecordBuilder.buildComponentParamsToc(
+                normalizedBundles
+            )
+        )
+        streams.set(
+            'SectionKeys',
+            AltiumLibraryRecordBuilder.buildSectionKeys(normalizedBundles)
+        )
+
+        for (const bundle of normalizedBundles) {
+            const storageName = AltiumLibraryRecordBuilder.sanitizeStorageName(
+                bundle.footprint.name
+            )
+            streams.set(
+                storageName + '/Header',
+                AltiumLibraryRecordBuilder.createCountHeader(0)
+            )
+            streams.set(
+                storageName + '/Parameters',
+                AltiumLibraryRecordBuilder.buildFootprintParameters(bundle)
+            )
+            streams.set(
+                storageName + '/Data',
+                AltiumLibraryRecordBuilder.buildFootprintData(bundle)
+            )
+            streams.set(
+                storageName + '/SourceRecord',
+                new TextEncoder().encode(
+                    AltiumLibraryRecordBuilder.buildPcbFootprintRecord(bundle)
+                )
+            )
+        }
+
+        if (modelRows.length) {
+            streams.set(
+                'Models/Data',
+                AltiumLibraryRecordBuilder.buildModelsData(modelRows)
+            )
+            modelRows.forEach((row, index) => {
+                streams.set('Models/' + index, row.model.bytes)
+            })
+        }
+
+        return OleCompoundDocumentWriter.write({ streams })
+    }
+
+    /**
+     * Collects model rows with deterministic generated ids.
+     * @param {object[]} bundles Normalized bundles.
+     * @returns {{ model: object, id: string, checksum: number }[]}
+     */
+    static #collectModels(bundles) {
+        return bundles.flatMap((bundle, bundleIndex) =>
+            bundle.models.map((model, modelIndex) => ({
+                model,
+                id: 'model-' + bundleIndex + '-' + modelIndex,
+                checksum: AltiumLibraryRecordBuilder.checksumBytes(model.bytes)
+            }))
+        )
+    }
+
+    /**
+     * Normalizes one or more bundles.
+     * @param {object[] | object} bundles Bundle input.
+     * @returns {object[]}
+     */
+    static #normalizeBundles(bundles) {
+        return (Array.isArray(bundles) ? bundles : [bundles]).map((bundle) =>
+            SourceComponentBundleNormalizer.normalize(bundle)
+        )
+    }
+}

package/src/core/altium/AltiumSchLibExporter.mjs

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { OleCompoundDocumentWriter } from '../ole/OleCompoundDocumentWriter.mjs'
+import { AltiumLibraryRecordBuilder } from './AltiumLibraryRecordBuilder.mjs'
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized bundles into a compact OLE-backed schematic library.
+ */
+export class AltiumSchLibExporter {
+    /**
+     * Exports one or more component bundles as `.SchLib` bytes.
+     * @param {object[] | object} bundles Component bundles.
+     * @returns {Uint8Array}
+     */
+    static export(bundles) {
+        const normalizedBundles =
+            AltiumSchLibExporter.#normalizeBundles(bundles)
+        const streams = new Map()
+        const libraryRecord = normalizedBundles
+            .map((bundle) =>
+                AltiumLibraryRecordBuilder.buildSchematicComponentRecord(bundle)
+            )
+            .join('\n')
+
+        streams.set('Library/Data', new TextEncoder().encode(libraryRecord))
+        for (const bundle of normalizedBundles) {
+            streams.set(
+                'Components/' +
+                    AltiumLibraryRecordBuilder.sanitizeStorageName(
+                        bundle.symbol.name
+                    ) +
+                    '/Data',
+                new TextEncoder().encode(
+                    AltiumLibraryRecordBuilder.buildSchematicComponentRecord(
+                        bundle
+                    )
+                )
+            )
+        }
+
+        return OleCompoundDocumentWriter.write({ streams })
+    }
+
+    /**
+     * Normalizes one or more bundles.
+     * @param {object[] | object} bundles Bundle input.
+     * @returns {object[]}
+     */
+    static #normalizeBundles(bundles) {
+        return (Array.isArray(bundles) ? bundles : [bundles]).map((bundle) =>
+            SourceComponentBundleNormalizer.normalize(bundle)
+        )
+    }
+}

package/src/core/altium/AsciiRecordParser.mjs

@@ -146,17 +146,11 @@ export class AsciiRecordParser {
             const rawKey = AsciiRecordParser.#trimAscii(
                 segment.slice(0, separatorIndex)
             )
-            const value = PrintableTextDecoder.decodeBytes(
-                AsciiRecordParser.#binaryStringToBytes(
-                    AsciiRecordParser.#trimAscii(
-                        segment.slice(separatorIndex + 1)
-                    )
-                ),
-                {
-                    encoding: rawKey.startsWith('%UTF8%') ? 'utf-8' : undefined
-                }
-            )
             const isUtf8Field = rawKey.startsWith('%UTF8%')
+            const value = AsciiRecordParser.#decodeFieldValue(
+                AsciiRecordParser.#trimAscii(segment.slice(separatorIndex + 1)),
+                isUtf8Field ? 'utf-8' : ''
+            )
             const key = rawKey.replace(/^%UTF8%/, '')
             if (!key) continue
 
@@ -228,13 +222,51 @@ export class AsciiRecordParser {
         return normalizedKeyIndex
     }
 
+    /**
+     * Decodes one pipe-delimited field value from the byte-preserving run
+     * string. Plain ASCII is already decoded by construction and can avoid
+     * byte-array allocation plus TextDecoder fallback probing.
+     * @param {string} value Byte-preserving field value.
+     * @param {string} preferredEncoding Optional preferred decoder encoding.
+     * @returns {string}
+     */
+    static #decodeFieldValue(value, preferredEncoding) {
+        if (!AsciiRecordParser.#hasExtendedByte(value)) {
+            return value
+        }
+
+        return PrintableTextDecoder.decodeBytes(
+            AsciiRecordParser.#binaryStringToBytes(value),
+            { encoding: preferredEncoding || undefined }
+        )
+    }
+
     /**
      * Converts one binary string into bytes without altering byte values.
      * @param {string} value
      * @returns {Uint8Array}
      */
     static #binaryStringToBytes(value) {
-        return Uint8Array.from(value, (character) => character.charCodeAt(0))
+        const bytes = new Uint8Array(value.length)
+
+        for (let index = 0; index < value.length; index += 1) {
+            bytes[index] = value.charCodeAt(index) & 0xff
+        }
+
+        return bytes
+    }
+
+    /**
+     * Returns true when the byte-preserving string contains non-ASCII bytes.
+     * @param {string} value Field value.
+     * @returns {boolean}
+     */
+    static #hasExtendedByte(value) {
+        for (let index = 0; index < value.length; index += 1) {
+            if (value.charCodeAt(index) > 0x7f) return true
+        }
+
+        return false
     }
 
     /**

package/src/core/altium/PcbComponentKindPolicy.mjs

@@ -12,49 +12,49 @@ const KIND_BY_VALUE = {
         displayName: 'Standard',
         includeInBom: true,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     },
     1: {
         name: 'mechanical',
         displayName: 'Mechanical',
         includeInBom: true,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     },
     2: {
         name: 'graphical',
         displayName: 'Graphical',
         includeInBom: false,
         includeInNetlist: false,
-        includeInPnp: false
+        includeInPlacement: false
     },
     3: {
         name: 'net-tie-bom',
         displayName: 'Net Tie BOM',
         includeInBom: true,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     },
     4: {
         name: 'net-tie-no-bom',
         displayName: 'Net Tie No BOM',
         includeInBom: false,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     },
     5: {
         name: 'standard-no-bom',
         displayName: 'Standard No BOM',
         includeInBom: false,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     },
     6: {
         name: 'jumper',
         displayName: 'Jumper',
         includeInBom: true,
         includeInNetlist: true,
-        includeInPnp: true
+        includeInPlacement: true
     }
 }
 
@@ -65,7 +65,7 @@ export class PcbComponentKindPolicy {
     /**
      * Parses native versioned component-kind fields.
      * @param {Record<string, string | string[]>} fields Native component row.
-     * @returns {{ value: number, name: string, displayName: string, includeInBom: boolean, includeInNetlist: boolean, includeInPnp: boolean } | undefined}
+     * @returns {{ value: number, name: string, displayName: string, includeInBom: boolean, includeInNetlist: boolean, includeInPlacement: boolean } | undefined}
      */
     static parse(fields) {
         if (!PcbComponentKindPolicy.#hasKindField(fields)) return undefined
@@ -76,7 +76,7 @@ export class PcbComponentKindPolicy {
             displayName: 'Unknown',
             includeInBom: true,
             includeInNetlist: true,
-            includeInPnp: true
+            includeInPlacement: true
         }
 
         return {

package/src/core/altium/PcbEmbeddedModelExtractor.mjs

@@ -20,14 +20,16 @@ export class PcbEmbeddedModelExtractor {
      * @returns {{ models: { id: string, checksum: number, name: string, format: string, payloadText: string, sourceStream: string, transform: { rotationDeg: { x: number, y: number, z: number }, dzMil: number } }[], componentBodies: { sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[] }}
      */
     static extractFromStreams(streams) {
+        const modelStreamPrefix =
+            PcbEmbeddedModelExtractor.#resolveModelStreamPrefix(streams)
         const modelMetadataRecords =
             PcbEmbeddedModelExtractor.#parseModelMetadataStream(
-                streams.get('Models/Data')
+                streams.get(modelStreamPrefix + '/Data')
             )
         const modelMetadataRows = modelMetadataRecords.map((fields, index) => ({
             fields,
             index,
-            sourceStream: 'Models/' + index,
+            sourceStream: modelStreamPrefix + '/' + index,
             id: PcbEmbeddedModelExtractor.#getField(fields, 'ID'),
             name: PcbEmbeddedModelExtractor.#getField(fields, 'NAME'),
             checksum: PcbEmbeddedModelExtractor.#normalizeChecksum(
@@ -70,7 +72,24 @@ export class PcbEmbeddedModelExtractor {
     }
 
     /**
-     * Parses the length-prefixed `Models/Data` metadata stream.
+     * Resolves the embedded-model stream folder used by the compound document.
+     * @param {Map<string, Uint8Array>} streams
+     * @returns {string}
+     */
+    static #resolveModelStreamPrefix(streams) {
+        if (streams.has('Models/Data')) {
+            return 'Models'
+        }
+
+        if (streams.has('Library/Models/Data')) {
+            return 'Library/Models'
+        }
+
+        return 'Models'
+    }
+
+    /**
+     * Parses the length-prefixed model metadata stream.
      * @param {Uint8Array | undefined} bytes
      * @returns {Record<string, string | string[]>[]}
      */

package/src/core/altium/PcbOutlineRecovery.mjs

@@ -24,6 +24,8 @@ export class PcbOutlineRecovery {
 
     static #MAX_DIRECT_RENDER_ARC_SWEEP_DEGREES = 120
 
+    static #MAX_MECHANICAL_FRAME_TO_AUTHORED_AREA_RATIO = 16
+
     /**
      * Selects a recoverable board outline from mechanical track layers.
      * @param {{ fallbackOutline: { minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }, components: { x: number, y: number }[], tracks: { x1: number, y1: number, x2: number, y2: number, width: number, layerId?: number }[] }} options
@@ -76,6 +78,20 @@ export class PcbOutlineRecovery {
             }
         }
 
+        if (
+            PcbOutlineRecovery.#shouldKeepAuthoredOutline(
+                fallbackOutline,
+                boundaryLayer.bounds,
+                componentBounds
+            )
+        ) {
+            return {
+                source: 'fallback',
+                layerId: null,
+                outline: fallbackOutline
+            }
+        }
+
         const recoveredOutline =
             PcbOutlineRecovery.#traceTrackOutline(
                 boundaryLayer.tracks,
@@ -166,6 +182,84 @@ export class PcbOutlineRecovery {
         return candidates[0] || null
     }
 
+    /**
+     * Returns true when the mechanical candidate is likely a drawing frame
+     * around an otherwise plausible authored board route.
+     * @param {{ minX: number, minY: number, widthMil: number, heightMil: number, segments?: Array<Record<string, number | string>> }} authoredOutline Authored board-route outline.
+     * @param {{ widthMil: number, heightMil: number }} mechanicalBounds Mechanical track-layer bounds.
+     * @param {{ centerX: number, centerY: number }} componentBounds Component placement envelope.
+     * @returns {boolean}
+     */
+    static #shouldKeepAuthoredOutline(
+        authoredOutline,
+        mechanicalBounds,
+        componentBounds
+    ) {
+        if (
+            !PcbOutlineRecovery.#isClosedOutlinePath(
+                authoredOutline?.segments || []
+            )
+        ) {
+            return false
+        }
+
+        const authoredArea =
+            Number(authoredOutline?.widthMil || 0) *
+            Number(authoredOutline?.heightMil || 0)
+        const mechanicalArea =
+            Number(mechanicalBounds?.widthMil || 0) *
+            Number(mechanicalBounds?.heightMil || 0)
+
+        if (!authoredArea || !mechanicalArea) {
+            return false
+        }
+
+        if (
+            mechanicalArea / authoredArea <=
+            PcbOutlineRecovery.#MAX_MECHANICAL_FRAME_TO_AUTHORED_AREA_RATIO
+        ) {
+            return false
+        }
+
+        return PcbOutlineRecovery.#outlineEnvelopeContainsPoint(
+            authoredOutline,
+            componentBounds?.centerX,
+            componentBounds?.centerY
+        )
+    }
+
+    /**
+     * Returns true when one point falls within an outline's bounding envelope.
+     * @param {{ minX?: number, minY?: number, widthMil?: number, heightMil?: number }} outline Outline bounds.
+     * @param {number} x Point X coordinate.
+     * @param {number} y Point Y coordinate.
+     * @returns {boolean}
+     */
+    static #outlineEnvelopeContainsPoint(outline, x, y) {
+        const minX = Number(outline?.minX)
+        const minY = Number(outline?.minY)
+        const widthMil = Number(outline?.widthMil)
+        const heightMil = Number(outline?.heightMil)
+
+        if (
+            !Number.isFinite(minX) ||
+            !Number.isFinite(minY) ||
+            !Number.isFinite(widthMil) ||
+            !Number.isFinite(heightMil) ||
+            !Number.isFinite(x) ||
+            !Number.isFinite(y)
+        ) {
+            return false
+        }
+
+        return (
+            x >= minX &&
+            x <= minX + widthMil &&
+            y >= minY &&
+            y <= minY + heightMil
+        )
+    }
+
     /**
      * Builds one track-bounds envelope.
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} tracks

package/src/core/altium/SchematicDirectiveParser.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { ParserUtils } from './ParserUtils.mjs'
+import { SchematicNoErcSymbolResolver } from './SchematicNoErcSymbolResolver.mjs'
 
 /**
  * Helpers for normalized schematic directive primitives.
@@ -144,6 +145,7 @@ export class SchematicDirectiveParser {
         const x = ParserUtils.parseNumericField(record.fields, 'Location.X')
         const y = ParserUtils.parseNumericField(record.fields, 'Location.Y')
         if (x === null || y === null) return null
+        const rawSymbol = ParserUtils.getField(record.fields, 'Symbol')
         const symbol = ParserUtils.parseNumericField(record.fields, 'Symbol')
 
         return {
@@ -160,7 +162,9 @@ export class SchematicDirectiveParser {
                 ParserUtils.parseNumericField(record.fields, 'Orientation') ||
                 0,
             symbol,
-            symbolName: SchematicDirectiveParser.#noErcSymbolName(symbol)
+            symbolName: SchematicNoErcSymbolResolver.resolveSymbolName(
+                rawSymbol || symbol
+            )
         }
     }
 
@@ -332,22 +336,6 @@ export class SchematicDirectiveParser {
         return 'record-' + String(record.recordIndex ?? 0)
     }
 
-    /**
-     * Converts common No ERC symbol ids into public labels.
-     * @param {number | null} symbol Symbol id.
-     * @returns {string}
-     */
-    static #noErcSymbolName(symbol) {
-        return (
-            {
-                0: 'generic',
-                1: 'box',
-                2: 'cross',
-                3: 'triangle'
-            }[Number(symbol)] || 'unknown'
-        )
-    }
-
     /**
      * Parses one boolean-ish directive parameter value.
      * @param {unknown} value Raw parameter value.

package/src/core/altium/SchematicNoErcSymbolResolver.mjs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Resolves Altium No ERC marker symbol identifiers into stable names.
+ */
+export class SchematicNoErcSymbolResolver {
+    /**
+     * Converts common No ERC symbol ids and names into public labels.
+     * @param {number | string | null | undefined} symbol Symbol id or source name.
+     * @returns {string}
+     */
+    static resolveSymbolName(symbol) {
+        const text = String(symbol ?? '')
+            .trim()
+            .toLowerCase()
+
+        if (text) {
+            if (/check\s*box/.test(text)) return 'checkbox'
+            if (/cross/.test(text)) return 'cross'
+            if (/triangle/.test(text)) return 'triangle'
+            if (/box/.test(text)) return 'box'
+            if (/generic/.test(text)) return 'generic'
+        }
+
+        return (
+            {
+                0: 'generic',
+                1: 'box',
+                2: 'cross',
+                3: 'triangle'
+            }[Number(symbol)] || 'unknown'
+        )
+    }
+}