altium-toolkit 1.1.2 → 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/PcbEmbeddedFontExtractor.mjs

@@ -2,13 +2,16 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import { unzlibSync } from 'fflate'
+import { Unzlib } from 'fflate'
 import { PcbFontMetricsParser } from './PcbFontMetricsParser.mjs'
 
 /**
  * Extracts zlib-compressed embedded font payloads from PCB compound streams.
  */
 export class PcbEmbeddedFontExtractor {
+    static #BASE64_ALPHABET =
+        'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
     static #CANDIDATE_STREAM_NAMES = [
         'EmbeddedFonts6/Data',
         'EmbeddedFonts/Data',
@@ -114,16 +117,19 @@ export class PcbEmbeddedFontExtractor {
             return null
         }
 
-        const compressedEnd = PcbEmbeddedFontExtractor.#findCompressedEnd(
+        const payload = PcbEmbeddedFontExtractor.#inflateZlibPayloadAt(
             bytes,
             zlibOffset
         )
-        if (compressedEnd <= zlibOffset) {
+        if (!payload) {
             return null
         }
 
-        const compressedBytes = bytes.subarray(zlibOffset, compressedEnd)
-        const payloadBytes = unzlibSync(compressedBytes)
+        const compressedBytes = bytes.subarray(
+            zlibOffset,
+            payload.compressedEnd
+        )
+        const payloadBytes = payload.bytes
         const metadata = PcbEmbeddedFontExtractor.#normalizeFontMetadata(
             familyField.text,
             alternateField.text,
@@ -151,7 +157,7 @@ export class PcbEmbeddedFontExtractor {
                     PcbEmbeddedFontExtractor.#bytesToBase64(payloadBytes),
                 metrics
             },
-            nextOffset: compressedEnd
+            nextOffset: payload.compressedEnd
         }
     }
 
@@ -224,48 +230,146 @@ export class PcbEmbeddedFontExtractor {
     }
 
     /**
-     * Finds the smallest trailing offset that fully contains a zlib payload.
+     * Inflates one zlib payload and returns its exact stream boundary.
      * @param {Uint8Array} bytes
      * @param {number} zlibOffset
+     * @returns {{ bytes: Uint8Array, compressedEnd: number } | null}
+     */
+    static #inflateZlibPayloadAt(bytes, zlibOffset) {
+        const input = bytes.subarray(zlibOffset)
+        const chunks = []
+        let inflater
+
+        try {
+            inflater = new Unzlib((chunk) => {
+                chunks.push(chunk)
+            })
+            inflater.push(input, false)
+        } catch {
+            return null
+        }
+
+        if (!Number(inflater?.s?.f || 0)) {
+            return null
+        }
+
+        const payloadBytes = PcbEmbeddedFontExtractor.#concatBytes(chunks)
+        const compressedByteCount =
+            PcbEmbeddedFontExtractor.#resolveCompressedByteCount(
+                input,
+                inflater,
+                payloadBytes
+            )
+
+        if (compressedByteCount <= 2) {
+            return null
+        }
+
+        return {
+            bytes: payloadBytes,
+            compressedEnd: zlibOffset + compressedByteCount
+        }
+    }
+
+    /**
+     * Resolves the zlib stream length from fflate's remaining input buffer.
+     * @param {Uint8Array} input
+     * @param {Unzlib} inflater
+     * @param {Uint8Array} payloadBytes
      * @returns {number}
      */
-    static #findCompressedEnd(bytes, zlibOffset) {
-        let low = zlibOffset + 2
-        let high = bytes.byteLength
+    static #resolveCompressedByteCount(input, inflater, payloadBytes) {
+        const remainingByteCount = Number(inflater?.p?.byteLength || 0)
+        if (remainingByteCount < 4) {
+            return -1
+        }
+
+        const baseByteCount = input.byteLength - remainingByteCount + 4
+        const checksum = PcbEmbeddedFontExtractor.#adler32(payloadBytes)
 
-        while (low < high) {
-            const midpoint = Math.floor((low + high) / 2)
+        // fflate can leave the final consumed deflate byte in `p` when the
+        // stream ends mid-byte, so validate both adjacent boundary candidates.
+        for (const compressedByteCount of [baseByteCount, baseByteCount + 1]) {
             if (
-                PcbEmbeddedFontExtractor.#canInflate(
-                    bytes.subarray(zlibOffset, midpoint)
+                PcbEmbeddedFontExtractor.#hasZlibChecksumAt(
+                    input,
+                    compressedByteCount,
+                    checksum
                 )
             ) {
-                high = midpoint
-            } else {
-                low = midpoint + 1
+                return compressedByteCount
             }
         }
 
-        return PcbEmbeddedFontExtractor.#canInflate(
-            bytes.subarray(zlibOffset, low)
-        )
-            ? low
-            : -1
+        return -1
     }
 
     /**
-     * Returns true when one byte slice can be inflated as a complete zlib
-     * stream.
-     * @param {Uint8Array} bytes
+     * Returns true when a candidate zlib boundary ends with the checksum.
+     * @param {Uint8Array} input
+     * @param {number} compressedByteCount
+     * @param {number} checksum
      * @returns {boolean}
      */
-    static #canInflate(bytes) {
-        try {
-            unzlibSync(bytes)
-            return true
-        } catch {
+    static #hasZlibChecksumAt(input, compressedByteCount, checksum) {
+        if (compressedByteCount < 6 || compressedByteCount > input.byteLength) {
             return false
         }
+
+        const checksumOffset = compressedByteCount - 4
+        const actualChecksum = new DataView(
+            input.buffer,
+            input.byteOffset + checksumOffset,
+            4
+        ).getUint32(0, false)
+
+        return actualChecksum === checksum
+    }
+
+    /**
+     * Computes the Adler-32 checksum used by zlib trailers.
+     * @param {Uint8Array} bytes
+     * @returns {number}
+     */
+    static #adler32(bytes) {
+        const modulo = 65521
+        let low = 1
+        let high = 0
+
+        for (let offset = 0; offset < bytes.byteLength; offset += 5552) {
+            const end = Math.min(offset + 5552, bytes.byteLength)
+            for (let index = offset; index < end; index += 1) {
+                low += bytes[index]
+                high += low
+            }
+            low %= modulo
+            high %= modulo
+        }
+
+        return ((high << 16) | low) >>> 0
+    }
+
+    /**
+     * Concatenates inflated output chunks.
+     * @param {Uint8Array[]} chunks
+     * @returns {Uint8Array}
+     */
+    static #concatBytes(chunks) {
+        if (chunks.length === 1) {
+            return chunks[0]
+        }
+
+        const bytes = new Uint8Array(
+            chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0)
+        )
+        let offset = 0
+
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset)
+            offset += chunk.byteLength
+        }
+
+        return bytes
     }
 
     /**
@@ -451,22 +555,61 @@ export class PcbEmbeddedFontExtractor {
      * @returns {string}
      */
     static #bytesToBase64(bytes) {
-        if (typeof btoa === 'function') {
-            let binary = ''
-            const chunkSize = 0x8000
-            for (
-                let offset = 0;
-                offset < bytes.byteLength;
-                offset += chunkSize
-            ) {
-                binary += String.fromCharCode(
-                    ...bytes.subarray(offset, offset + chunkSize)
-                )
+        if (typeof Buffer === 'function' && typeof Buffer.from === 'function') {
+            return Buffer.from(bytes).toString('base64')
+        }
+
+        return PcbEmbeddedFontExtractor.#bytesToBase64Portable(bytes)
+    }
+
+    /**
+     * Encodes bytes as base64 without relying on Node APIs.
+     * @param {Uint8Array} bytes
+     * @returns {string}
+     */
+    static #bytesToBase64Portable(bytes) {
+        const alphabet = PcbEmbeddedFontExtractor.#BASE64_ALPHABET
+        const groupBuffer = new Array(4096)
+        const outputChunks = []
+        let groupIndex = 0
+        let byteIndex = 0
+
+        for (; byteIndex + 2 < bytes.byteLength; byteIndex += 3) {
+            const value =
+                (bytes[byteIndex] << 16) |
+                (bytes[byteIndex + 1] << 8) |
+                bytes[byteIndex + 2]
+            groupBuffer[groupIndex] =
+                alphabet[(value >> 18) & 63] +
+                alphabet[(value >> 12) & 63] +
+                alphabet[(value >> 6) & 63] +
+                alphabet[value & 63]
+            groupIndex += 1
+
+            if (groupIndex === groupBuffer.length) {
+                outputChunks.push(groupBuffer.join(''))
+                groupIndex = 0
             }
-            return btoa(binary)
         }
 
-        return Buffer.from(bytes).toString('base64')
+        if (byteIndex < bytes.byteLength) {
+            const hasSecondByte = byteIndex + 1 < bytes.byteLength
+            const value =
+                (bytes[byteIndex] << 16) |
+                ((hasSecondByte ? bytes[byteIndex + 1] : 0) << 8)
+            groupBuffer[groupIndex] =
+                alphabet[(value >> 18) & 63] +
+                alphabet[(value >> 12) & 63] +
+                (hasSecondByte ? alphabet[(value >> 6) & 63] : '=') +
+                '='
+            groupIndex += 1
+        }
+
+        if (groupIndex > 0) {
+            outputChunks.push(groupBuffer.slice(0, groupIndex).join(''))
+        }
+
+        return outputChunks.join('')
     }
 
     /**

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[]>[]}
      */