altium-toolkit 1.1.2 → 1.1.3

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/PrintableTextDecoder.mjs

@@ -6,6 +6,9 @@
  * Extracts long printable runs from binary Altium documents.
  */
 export class PrintableTextDecoder {
+    static #decoderCache = new Map()
+    static #decoderConstructor = null
+
     static #WINDOWS_1252_PRINTABLE_CONTROL_BYTES = new Set([
         0x80, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8a, 0x8b, 0x8c,
         0x8e, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9a, 0x9b,
@@ -115,7 +118,7 @@ export class PrintableTextDecoder {
         if (preferredEncoding === 'utf-8') {
             return (
                 PrintableTextDecoder.#tryDecode(bytes, 'utf-8') ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
         if (
@@ -124,7 +127,7 @@ export class PrintableTextDecoder {
         ) {
             return (
                 PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-                new TextDecoder('utf-8').decode(bytes)
+                PrintableTextDecoder.#decode(bytes, 'utf-8')
             )
         }
 
@@ -144,7 +147,7 @@ export class PrintableTextDecoder {
         return (
             PrintableTextDecoder.#tryDecode(bytes, 'gb18030') ||
             PrintableTextDecoder.#tryDecodeWindows1252(bytes) ||
-            new TextDecoder('utf-8').decode(bytes)
+            PrintableTextDecoder.#decode(bytes, 'utf-8')
         )
     }
 
@@ -157,18 +160,25 @@ export class PrintableTextDecoder {
      * @param {number} minLength
      */
     static #pushRunBytes(runs, bytes, start, end, minLength) {
-        const length = end - start
-        if (length < minLength) return
-
-        const slice = bytes.slice(start, end)
-        const normalized = PrintableTextDecoder.#normalizeRun(
-            PrintableTextDecoder.decodeBytes(slice)
+        const bounds = PrintableTextDecoder.#trimAsciiByteRange(
+            bytes,
+            start,
+            end
         )
+        const length = bounds.end - bounds.start
+        if (length < minLength) return
 
-        if (normalized.length < minLength) return
-        if (!normalized.includes('|') || !normalized.includes('=')) return
+        if (
+            !PrintableTextDecoder.#containsRecordDelimiterBytes(
+                bytes,
+                bounds.start,
+                bounds.end
+            )
+        ) {
+            return
+        }
 
-        runs.push(slice)
+        runs.push(bytes.slice(start, end))
     }
 
     /**
@@ -218,6 +228,72 @@ export class PrintableTextDecoder {
         return false
     }
 
+    /**
+     * Trims ASCII whitespace from one byte range.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {{ start: number, end: number }}
+     */
+    static #trimAsciiByteRange(bytes, start, end) {
+        let trimmedStart = start
+        let trimmedEnd = end
+
+        while (
+            trimmedStart < trimmedEnd &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedStart])
+        ) {
+            trimmedStart += 1
+        }
+
+        while (
+            trimmedEnd > trimmedStart &&
+            PrintableTextDecoder.#isAsciiWhitespaceByte(bytes[trimmedEnd - 1])
+        ) {
+            trimmedEnd -= 1
+        }
+
+        return {
+            start: trimmedStart,
+            end: trimmedEnd
+        }
+    }
+
+    /**
+     * Returns true when one byte range contains Altium record delimiters.
+     * @param {Uint8Array} bytes
+     * @param {number} start
+     * @param {number} end
+     * @returns {boolean}
+     */
+    static #containsRecordDelimiterBytes(bytes, start, end) {
+        let hasPipe = false
+        let hasEquals = false
+
+        for (let index = start; index < end; index += 1) {
+            if (bytes[index] === 0x7c) {
+                hasPipe = true
+            } else if (bytes[index] === 0x3d) {
+                hasEquals = true
+            }
+
+            if (hasPipe && hasEquals) {
+                return true
+            }
+        }
+
+        return false
+    }
+
+    /**
+     * Returns true when a byte is ASCII whitespace normalized around runs.
+     * @param {number} byte
+     * @returns {boolean}
+     */
+    static #isAsciiWhitespaceByte(byte) {
+        return byte === 9 || byte === 10 || byte === 13 || byte === 32
+    }
+
     /**
      * Tries one strict decode and returns null when bytes are invalid for it.
      * @param {Uint8Array} bytes
@@ -226,12 +302,56 @@ export class PrintableTextDecoder {
      */
     static #tryDecode(bytes, encoding) {
         try {
-            return new TextDecoder(encoding, { fatal: true }).decode(bytes)
+            return PrintableTextDecoder.#decode(bytes, encoding, {
+                fatal: true
+            })
         } catch {
             return null
         }
     }
 
+    /**
+     * Decodes one byte slice with a cached runtime decoder.
+     * @param {Uint8Array} bytes
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} [options]
+     * @returns {string}
+     */
+    static #decode(bytes, encoding, options = {}) {
+        return PrintableTextDecoder.#getTextDecoder(encoding, options).decode(
+            bytes
+        )
+    }
+
+    /**
+     * Resolves a cached TextDecoder for one encoding and fatal mode.
+     * @param {string} encoding
+     * @param {{ fatal?: boolean }} options
+     * @returns {TextDecoder}
+     */
+    static #getTextDecoder(encoding, options) {
+        const Decoder = globalThis.TextDecoder
+        if (PrintableTextDecoder.#decoderConstructor !== Decoder) {
+            PrintableTextDecoder.#decoderCache = new Map()
+            PrintableTextDecoder.#decoderConstructor = Decoder
+        }
+
+        const normalizedEncoding = String(encoding || 'utf-8').toLowerCase()
+        const fatal = Boolean(options?.fatal)
+        const cacheKey = `${normalizedEncoding}:${fatal ? 'fatal' : 'replace'}`
+        const cached = PrintableTextDecoder.#decoderCache.get(cacheKey)
+        if (cached) {
+            return cached
+        }
+
+        const decoder = new Decoder(
+            normalizedEncoding,
+            fatal ? { fatal: true } : {}
+        )
+        PrintableTextDecoder.#decoderCache.set(cacheKey, decoder)
+        return decoder
+    }
+
     /**
      * Tries a Windows-1252 decode and normalizes runtimes that expose C1 bytes
      * as control characters instead of punctuation.

package/src/core/altium/SchematicComponentOwnerTextResolver.mjs

@@ -66,6 +66,19 @@ export class SchematicComponentOwnerTextResolver {
         )
     }
 
+    /**
+     * Resolves candidate owner indexes for one schematic component record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Indexed schematic records.
+     * @returns {string[]}
+     */
+    static resolveOwnerIndexes(componentRecord, records) {
+        return SchematicComponentOwnerTextResolver.#resolveOwnerIndexes(
+            componentRecord,
+            records
+        )
+    }
+
     /**
      * Resolves candidate owner indexes for one schematic component record.
      * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} componentRecord Component placement record.

package/src/core/altium/SchematicComponentTextResolver.mjs

@@ -56,7 +56,7 @@ export class SchematicComponentTextResolver {
      */
     static resolveValue(ownerTexts, texts, component) {
         const ownerValue =
-            SchematicComponentTextResolver.#findFirstRelatedTextRecord(
+            SchematicComponentTextResolver.#findFirstUsableRelatedTextRecord(
                 ownerTexts,
                 ['Comment', 'VALUE']
             )
@@ -128,6 +128,45 @@ export class SchematicComponentTextResolver {
         return { found: false, text: '' }
     }
 
+    /**
+     * Finds the first owner text that is resolved or explicitly empty, while
+     * allowing unresolved templates to fall through to later owner parameters.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @param {string[]} logicalNames Logical text names.
+     * @returns {{ found: boolean, text: string }}
+     */
+    static #findFirstUsableRelatedTextRecord(records, logicalNames) {
+        let unresolvedMatch = { found: false, text: '' }
+
+        for (const logicalName of logicalNames) {
+            const match = SchematicComponentTextResolver.#findRelatedTextRecord(
+                records,
+                logicalName
+            )
+
+            if (!match.found) {
+                continue
+            }
+
+            if (
+                SchematicComponentTextResolver.#isExplicitEmptyText(
+                    match.text
+                ) ||
+                SchematicComponentTextResolver.#isResolvedComponentText(
+                    match.text
+                )
+            ) {
+                return match
+            }
+
+            if (!unresolvedMatch.found) {
+                unresolvedMatch = match
+            }
+        }
+
+        return unresolvedMatch
+    }
+
     /**
      * Finds the closest nearby designator text for one component.
      * @param {{ x: number, y: number, text: string, name: string }[]} texts