altium-toolkit 1.1.22 → 1.1.24

package/src/core/altium/SchematicRecordStreamParser.mjs

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AsciiRecordParser } from './AsciiRecordParser.mjs'
+
+/**
+ * Parses schematic stream records from native framed streams or printable runs.
+ */
+export class SchematicRecordStreamParser {
+    /**
+     * Parses one schematic stream into record objects.
+     * @param {ArrayBuffer} arrayBuffer Stream bytes.
+     * @returns {{ raw: string, fields: Record<string, string | string[]> }[]}
+     */
+    static parse(arrayBuffer) {
+        return SchematicRecordStreamParser.parseWithOpaqueRecords(arrayBuffer)
+            .records
+    }
+
+    /**
+     * Parses one schematic stream and preserves unmodelled native frames.
+     * @param {ArrayBuffer} arrayBuffer Stream bytes.
+     * @param {{ source?: string, sourceStorage?: string, sourceStream?: string }} [options]
+     * @returns {{ records: { raw: string, fields: Record<string, string | string[]> }[], opaqueRecords: object[] }}
+     */
+    static parseWithOpaqueRecords(arrayBuffer, options = {}) {
+        const framedRecords = SchematicRecordStreamParser.#parseFramedRecords(
+            arrayBuffer,
+            options
+        )
+
+        if (framedRecords) {
+            return framedRecords
+        }
+
+        return {
+            records: AsciiRecordParser.parse(arrayBuffer),
+            opaqueRecords: []
+        }
+    }
+
+    /**
+     * Parses length-prefixed native records when the full stream validates as
+     * framed schematic data.
+     * @param {ArrayBuffer} arrayBuffer Stream bytes.
+     * @param {{ source?: string, sourceStorage?: string, sourceStream?: string }} options Parser metadata.
+     * @returns {{ records: { raw: string, fields: Record<string, string | string[]> }[], opaqueRecords: object[] } | null}
+     */
+    static #parseFramedRecords(arrayBuffer, options) {
+        const bytes = new Uint8Array(arrayBuffer)
+        const records = []
+        const opaqueRecords = []
+        let offset = 0
+        let recordIndex = 0
+
+        while (offset < bytes.byteLength) {
+            if (offset + 4 > bytes.byteLength) {
+                return null
+            }
+
+            const payloadLength = bytes[offset] | (bytes[offset + 1] << 8)
+            const separatorByte = bytes[offset + 2]
+            const recordType = bytes[offset + 3]
+            const payloadStart = offset + 4
+            const payloadEnd = payloadStart + payloadLength
+
+            if (
+                payloadLength <= 0 ||
+                separatorByte !== 0 ||
+                payloadEnd > bytes.byteLength
+            ) {
+                return null
+            }
+
+            if (recordType === 0) {
+                if (bytes[payloadEnd - 1] !== 0) {
+                    return null
+                }
+
+                const raw = SchematicRecordStreamParser.#bytesToBinaryString(
+                    bytes.subarray(payloadStart, payloadEnd - 1)
+                )
+
+                if (raw.trim()) {
+                    records.push(AsciiRecordParser.parseRecord(raw))
+                }
+            } else {
+                opaqueRecords.push(
+                    SchematicRecordStreamParser.#opaqueRecord(
+                        bytes.subarray(payloadStart, payloadEnd),
+                        recordType,
+                        recordIndex,
+                        options
+                    )
+                )
+            }
+
+            offset = payloadEnd
+            recordIndex += 1
+        }
+
+        return records.length || opaqueRecords.length
+            ? { records, opaqueRecords }
+            : null
+    }
+
+    /**
+     * Builds one opaque framed-record metadata row.
+     * @param {Uint8Array} bytes Raw payload bytes.
+     * @param {number} frameType Native frame type byte.
+     * @param {number} recordIndex Zero-based frame index.
+     * @param {{ source?: string, sourceStorage?: string, sourceStream?: string }} options Parser metadata.
+     * @returns {object}
+     */
+    static #opaqueRecord(bytes, frameType, recordIndex, options) {
+        return SchematicRecordStreamParser.#stripUndefined({
+            source: options.source || 'schdoc',
+            sourceStorage: options.sourceStorage,
+            sourceStream: options.sourceStream,
+            frameType,
+            recordIndex,
+            byteLength: bytes.byteLength,
+            rawBase64: SchematicRecordStreamParser.#bytesToBase64(bytes)
+        })
+    }
+
+    /**
+     * Converts bytes into a byte-preserving string.
+     * @param {Uint8Array} bytes Source bytes.
+     * @returns {string}
+     */
+    static #bytesToBinaryString(bytes) {
+        let value = ''
+
+        for (const byte of bytes) {
+            value += String.fromCharCode(byte)
+        }
+
+        return value
+    }
+
+    /**
+     * Encodes bytes as base64 without depending on Node globals.
+     * @param {Uint8Array} bytes Source bytes.
+     * @returns {string}
+     */
+    static #bytesToBase64(bytes) {
+        const alphabet =
+            'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+        let output = ''
+
+        for (let index = 0; index < bytes.byteLength; index += 3) {
+            const first = bytes[index]
+            const second = bytes[index + 1]
+            const third = bytes[index + 2]
+            const hasSecond = index + 1 < bytes.byteLength
+            const hasThird = index + 2 < bytes.byteLength
+            const value =
+                (first << 16) |
+                ((hasSecond ? second : 0) << 8) |
+                (hasThird ? third : 0)
+
+            output += alphabet[(value >> 18) & 0x3f]
+            output += alphabet[(value >> 12) & 0x3f]
+            output += hasSecond ? alphabet[(value >> 6) & 0x3f] : '='
+            output += hasThird ? alphabet[value & 0x3f] : '='
+        }
+
+        return output
+    }
+
+    /**
+     * Removes undefined values from an object.
+     * @param {object} row Row to strip.
+     * @returns {object}
+     */
+    static #stripUndefined(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(([, value]) => value !== undefined)
+        )
+    }
+}

package/src/core/altium/SchematicRecordTypeRegistry.mjs

@@ -47,13 +47,18 @@ export class SchematicRecordTypeRegistry {
         [47, ['map-definer', 'implementation', true]],
         [48, ['implementation-parameters', 'implementation', true]],
         [209, ['note', 'annotation', true]],
+        [210, ['probe-marker', 'code-symbol', true]],
         [211, ['compile-mask', 'directive', true]],
         [215, ['harness-connector', 'harness', true]],
         [216, ['harness-entry', 'harness', true]],
         [217, ['harness-type', 'harness', true]],
         [218, ['signal-harness', 'harness', true]],
+        [220, ['code-symbol', 'code-symbol', true]],
+        [221, ['code-symbol-entry', 'code-symbol', true]],
+        [222, ['code-symbol-title', 'code-symbol', true]],
+        [223, ['code-symbol-source', 'code-symbol', true]],
         [225, ['blanket', 'directive', true]],
-        [226, ['hyperlink', 'annotation', false]]
+        [226, ['hyperlink', 'annotation', true]]
     ])
 
     /**

package/src/core/altium/SchematicSheetParser.mjs

@@ -13,7 +13,7 @@ export class SchematicSheetParser {
     /**
      * Parses sheet symbols and their child entries from schematic records.
      * @param {{ fields: Record<string, string | string[]>, recordIndex: number }[]} records
-     * @returns {{ sheetSymbols: { x: number, y: number, width: number, height: number, color: string, fill: string, isSolid: boolean, transparent: boolean, ownerIndex?: string, uniqueId: string, renderOrder: number, sourceRecordIndex: number, indexInSheet: number | null }[], sheetEntries: { ownerIndex: string, name: string, side: 'left' | 'right' | 'top' | 'bottom', direction: 'unspecified' | 'output' | 'input' | 'bidirectional', style: number, x: number, y: number, color: string, fill: string, textColor: string, harnessType: string, renderOrder: number }[] }}
+     * @returns {{ sheetSymbols: { x: number, y: number, width: number, height: number, name?: string, fileName?: string, color: string, fill: string, isSolid: boolean, transparent: boolean, ownerIndex?: string, uniqueId: string, renderOrder: number, sourceRecordIndex: number, indexInSheet: number | null }[], sheetEntries: { ownerIndex: string, name: string, side: 'left' | 'right' | 'top' | 'bottom', direction: 'unspecified' | 'output' | 'input' | 'bidirectional', style: number, x: number, y: number, color: string, fill: string, textColor: string, harnessType: string, renderOrder: number }[] }}
      */
     static parse(records) {
         const sheetSymbols = records
@@ -38,7 +38,7 @@ export class SchematicSheetParser {
     /**
      * Normalizes one `RECORD=15` sheet symbol.
      * @param {{ fields: Record<string, string | string[]>, recordIndex: number }} record
-     * @returns {{ x: number, y: number, width: number, height: number, color: string, fill: string, isSolid: boolean, transparent: boolean, ownerIndex?: string, uniqueId: string, renderOrder: number, sourceRecordIndex: number, indexInSheet: number | null } | null}
+     * @returns {{ x: number, y: number, width: number, height: number, name?: string, fileName?: string, color: string, fill: string, isSolid: boolean, transparent: boolean, ownerIndex?: string, uniqueId: string, renderOrder: number, sourceRecordIndex: number, indexInSheet: number | null } | null}
      */
     static #parseSheetSymbolRecord(record) {
         if (getField(record.fields, 'RECORD') !== '15') {
@@ -61,6 +61,12 @@ export class SchematicSheetParser {
             y,
             width,
             height,
+            ...(getField(record.fields, 'Name')
+                ? { name: getField(record.fields, 'Name') }
+                : {}),
+            ...(getField(record.fields, 'FileName')
+                ? { fileName: getField(record.fields, 'FileName') }
+                : {}),
             color: toColor(record.fields.Color, '#a44a1b'),
             fill: toColor(record.fields.AreaColor, '#ffe16f'),
             isSolid: parseBoolean(record.fields.IsSolid),

package/src/core/altium/SchematicStreamExtractor.mjs

@@ -2,8 +2,9 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import { AsciiRecordParser } from './AsciiRecordParser.mjs'
 import { EmbeddedFileInventoryBuilder } from './EmbeddedFileInventoryBuilder.mjs'
+import { NativeStreamInventoryBuilder } from './NativeStreamInventoryBuilder.mjs'
+import { SchematicRecordStreamParser } from './SchematicRecordStreamParser.mjs'
 import { OleCompoundDocument } from '../ole/OleCompoundDocument.mjs'
 import { OleConstants } from '../ole/OleConstants.mjs'
 
@@ -58,10 +59,10 @@ export class SchematicStreamExtractor {
             return null
         }
 
-        let fileHeaderRecords
+        let fileHeaderParse
 
         try {
-            fileHeaderRecords = SchematicStreamExtractor.#parseStreamRecords(
+            fileHeaderParse = SchematicStreamExtractor.#parseStreamRecords(
                 compoundDocument,
                 'FileHeader'
             )
@@ -73,32 +74,64 @@ export class SchematicStreamExtractor {
         const auxiliaryStreamNames = streamNames.filter((streamName) =>
             SchematicStreamExtractor.#isAuxiliaryPrintableStream(streamName)
         )
-        const auxiliaryRecords = auxiliaryStreamNames.flatMap((streamName) =>
+        const auxiliaryParses = auxiliaryStreamNames.map((streamName) =>
             SchematicStreamExtractor.#parseStreamRecords(
                 compoundDocument,
                 streamName
             )
         )
-        const records = [...fileHeaderRecords, ...auxiliaryRecords]
-
-        if (!records.length) {
+        const records = [
+            ...fileHeaderParse.records,
+            ...auxiliaryParses.flatMap((entry) => entry.records)
+        ]
+        const opaqueRecords = [
+            ...fileHeaderParse.opaqueRecords,
+            ...auxiliaryParses.flatMap((entry) => entry.opaqueRecords)
+        ]
+
+        if (!records.length && !opaqueRecords.length) {
             return null
         }
 
+        const embeddedFiles = EmbeddedFileInventoryBuilder.buildFromStreams(
+            new Map(
+                streamNames.map((name) => [
+                    name,
+                    compoundDocument.getStream(name)
+                ])
+            ),
+            {
+                skipStreamNames: ['FileHeader', ...auxiliaryStreamNames]
+            }
+        )
+        const consumedStreamNames = [
+            'FileHeader',
+            ...auxiliaryStreamNames,
+            ...embeddedFiles.files.map((file) => file.sourceStream),
+            ...embeddedFiles.diagnostics.map(
+                (diagnostic) => diagnostic.sourceStream
+            )
+        ]
+        const nativeStreams = NativeStreamInventoryBuilder.buildFromStreams(
+            new Map(
+                streamNames.map((name) => [
+                    name,
+                    compoundDocument.getStream(name)
+                ])
+            ),
+            {
+                source: 'schdoc',
+                consumedStreamNames,
+                knownStreamNames: ['FileHeader', ...auxiliaryStreamNames]
+            }
+        )
+
         return {
             records,
             streamNames,
-            embeddedFiles: EmbeddedFileInventoryBuilder.buildFromStreams(
-                new Map(
-                    streamNames.map((name) => [
-                        name,
-                        compoundDocument.getStream(name)
-                    ])
-                ),
-                {
-                    skipStreamNames: ['FileHeader', ...auxiliaryStreamNames]
-                }
-            )
+            opaqueRecords,
+            nativeStreams,
+            embeddedFiles
         }
     }
 
@@ -106,17 +139,23 @@ export class SchematicStreamExtractor {
      * Parses printable records from one compound-document stream.
      * @param {OleCompoundDocument} compoundDocument
      * @param {string} streamName
-     * @returns {Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>}
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, opaqueRecords: object[] }}
      */
     static #parseStreamRecords(compoundDocument, streamName) {
-        return AsciiRecordParser.parse(
+        const parsed = SchematicRecordStreamParser.parseWithOpaqueRecords(
             SchematicStreamExtractor.#toArrayBuffer(
                 compoundDocument.getStream(streamName)
-            )
-        ).map((record) => ({
-            ...record,
-            sourceStream: streamName
-        }))
+            ),
+            { sourceStream: streamName }
+        )
+
+        return {
+            records: parsed.records.map((record) => ({
+                ...record,
+                sourceStream: streamName
+            })),
+            opaqueRecords: parsed.opaqueRecords
+        }
     }
 
     /**

package/src/core/altium/SchematicTextOrientationResolver.mjs

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+/**
+ * Resolves native schematic text orientation flags.
+ */
+export class SchematicTextOrientationResolver {
+    /**
+     * Resolves component designator/parameter orientation bit 1 to right
+     * anchoring.
+     * @param {Record<string, string | string[]>} fields Text record fields.
+     * @param {string} recordType Native text record type.
+     * @returns {'end' | null}
+     */
+    static resolveHorizontalAnchor(fields, recordType) {
+        if (
+            !SchematicTextOrientationResolver.#isComponentTextRecord(recordType)
+        ) {
+            return null
+        }
+
+        const orientation = ParserUtils.parseNumericField(fields, 'Orientation')
+        if (!Number.isInteger(orientation)) return null
+
+        return (orientation & 2) === 2 ? 'end' : null
+    }
+
+    /**
+     * Resolves component text orientation bit 1 to top source anchoring.
+     * @param {Record<string, string | string[]>} fields Text record fields.
+     * @param {string} recordType Native text record type.
+     * @returns {'top' | null}
+     */
+    static resolveVerticalAnchor(fields, recordType) {
+        return SchematicTextOrientationResolver.resolveHorizontalAnchor(
+            fields,
+            recordType
+        )
+            ? 'top'
+            : null
+    }
+
+    /**
+     * Returns true when a text record's orientation encodes a quarter-turn.
+     * Component designators and parameters use bit 0; older free labels use
+     * the literal orientation-1 value.
+     * @param {string} recordType Native text record type.
+     * @param {number | null} orientation Native orientation value.
+     * @returns {boolean}
+     */
+    static shouldRotateFromOrientation(recordType, orientation) {
+        if (!Number.isInteger(orientation)) {
+            return false
+        }
+
+        if (
+            SchematicTextOrientationResolver.#isComponentTextRecord(recordType)
+        ) {
+            return (orientation & 1) === 1
+        }
+
+        return orientation === 1
+    }
+
+    /**
+     * Returns true for component designator and parameter text records.
+     * @param {string} recordType Native text record type.
+     * @returns {boolean}
+     */
+    static #isComponentTextRecord(recordType) {
+        return recordType === '34' || recordType === '41'
+    }
+}

package/src/core/altium/SchematicTextParser.mjs

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { ParserUtils } from './ParserUtils.mjs'
+import { SchematicTextRunParser } from './SchematicTextRunParser.mjs'
+import { SchematicTextOrientationResolver } from './SchematicTextOrientationResolver.mjs'
 
 /**
  * Helpers for normalized schematic text extraction.
@@ -134,7 +136,7 @@ export class SchematicTextParser {
      * @param {{ width: number, marginWidth: number, titleBlockOn?: boolean }} sheet
      * @param {Record<string, { size: number, family: string, bold: boolean, italic?: boolean, rotation: number }>} fonts
      * @param {Map<string, Record<string, string>>} [ownerMetadata]
-     * @returns {{ x: number, y: number, text: string, color: string, hidden: boolean, name: string, ownerIndex?: string, recordType: string, style: number, fontSize: number, fontFamily: string, fontWeight: number, fontStyle?: string, rotation: number, sourceOrientation?: number, isMirrored?: boolean, anchor: 'start' | 'middle' | 'end', powerPortDirection?: 'up' | 'down' | 'left' | 'right', cornerX?: number, cornerY?: number, fill?: string, borderColor?: string, isSolid?: boolean, showBorder?: boolean, textMargin?: number, noteLines?: string[] } | null}
+     * @returns {{ x: number, y: number, text: string, color: string, hidden: boolean, name: string, ownerIndex?: string, recordType: string, style: number, fontSize: number, fontFamily: string, fontWeight: number, fontStyle?: string, rotation: number, sourceOrientation?: number, isMirrored?: boolean, anchor: 'start' | 'middle' | 'end', verticalAnchor?: 'top', powerPortDirection?: 'up' | 'down' | 'left' | 'right', cornerX?: number, cornerY?: number, fill?: string, borderColor?: string, isSolid?: boolean, showBorder?: boolean, textMargin?: number, noteLines?: string[] } | null}
      */
     static normalizeSchematicTextRecord(
         fields,
@@ -158,8 +160,9 @@ export class SchematicTextParser {
                 ownerMetadata
             )
         )
+        const textRuns = SchematicTextRunParser.parseOptionalOverlineRuns(text)
 
-        if (hidden || x === null || y === null || !text) {
+        if (hidden || x === null || y === null || !textRuns.text) {
             return null
         }
 
@@ -168,7 +171,7 @@ export class SchematicTextParser {
                 fields,
                 name,
                 rawText,
-                text,
+                textRuns.text,
                 sheet
             )
         ) {
@@ -191,7 +194,8 @@ export class SchematicTextParser {
         const textRecord = {
             x,
             y,
-            text,
+            text: textRuns.text,
+            textSegments: textRuns.segments,
             color: SchematicTextParser.#resolveSchematicTextColor(
                 fields,
                 recordType
@@ -211,6 +215,11 @@ export class SchematicTextParser {
             sourceOrientation:
                 sourceOrientation === null ? undefined : sourceOrientation,
             isMirrored: isMirrored || undefined,
+            verticalAnchor:
+                SchematicTextOrientationResolver.resolveVerticalAnchor(
+                    fields,
+                    recordType
+                ) || undefined,
             powerPortDirection:
                 SchematicTextParser.#resolvePowerPortDirection(
                     fields,
@@ -597,8 +606,14 @@ export class SchematicTextParser {
     static #inferTextAnchor(fields, recordType, name, text, font, rotation) {
         const explicitAnchor =
             SchematicTextParser.#resolveSchematicTextJustificationAnchor(fields)
+        const orientationAnchor =
+            SchematicTextOrientationResolver.resolveHorizontalAnchor(
+                fields,
+                recordType
+            )
 
         if (recordType === '17') return 'middle'
+        if (orientationAnchor) return orientationAnchor
         if (explicitAnchor) return explicitAnchor
         if (
             SchematicTextParser.#shouldCenterSchematicNoteByDefault(
@@ -748,12 +763,9 @@ export class SchematicTextParser {
      */
     static #resolveTextRotation(fields, font, recordType) {
         if (recordType === '17') return 0
-        if (recordType === '25') {
-            const orientation = ParserUtils.parseNumericField(
-                fields,
-                'Orientation'
-            )
+        const orientation = ParserUtils.parseNumericField(fields, 'Orientation')
 
+        if (recordType === '25') {
             if (orientation === 1 || orientation === 3) {
                 return 90
             }
@@ -765,7 +777,12 @@ export class SchematicTextParser {
         )
         if (explicitRotation !== null) return explicitRotation
         if (font.rotation) return font.rotation
-        if (ParserUtils.parseNumericField(fields, 'Orientation') === 1) {
+        if (
+            SchematicTextOrientationResolver.shouldRotateFromOrientation(
+                recordType,
+                orientation
+            )
+        ) {
             return 90
         }
         return 0
@@ -870,8 +887,7 @@ export class SchematicTextParser {
                 fields.Color || fields.TextColor,
                 '#7b7753'
             ),
-            lineWidth:
-                ParserUtils.parseNumericField(fields, 'LineWidth') ?? undefined,
+            lineWidth: ParserUtils.parseSchematicLineWidth(fields),
             isSolid: ParserUtils.parseBoolean(fields.IsSolid),
             showBorder: ParserUtils.parseBoolean(fields.ShowBorder),
             textMargin:

package/src/core/altium/SchematicTextRunParser.mjs

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Parses schematic text runs that use backslash suffix markers for overlines.
+ */
+export class SchematicTextRunParser {
+    /**
+     * Parses overline suffix markers into display text and contiguous runs.
+     * @param {string} value Source text.
+     * @returns {{ text: string, hasOverline: boolean, segments: { text: string, overline: boolean }[] }}
+     */
+    static parseOverlineRuns(value) {
+        const characters = []
+
+        for (const character of String(value || '').trim()) {
+            if (character === '\\') {
+                const previousCharacter = characters.at(-1)
+                if (previousCharacter) {
+                    previousCharacter.overline = true
+                }
+                continue
+            }
+
+            characters.push({
+                text: character,
+                overline: false
+            })
+        }
+
+        const segments = SchematicTextRunParser.#segments(characters)
+
+        return {
+            text: characters.map((character) => character.text).join(''),
+            hasOverline: segments.some((segment) => segment.overline),
+            segments
+        }
+    }
+
+    /**
+     * Returns only overline segments when a value contains overlined runs.
+     * @param {string} value Source text.
+     * @returns {{ text: string, segments?: { text: string, overline: boolean }[] }}
+     */
+    static parseOptionalOverlineRuns(value) {
+        const parsed = SchematicTextRunParser.parseOverlineRuns(value)
+
+        return {
+            text: parsed.text,
+            segments: parsed.hasOverline ? parsed.segments : undefined
+        }
+    }
+
+    /**
+     * Merges character flags into contiguous text segments.
+     * @param {{ text: string, overline: boolean }[]} characters Character rows.
+     * @returns {{ text: string, overline: boolean }[]}
+     */
+    static #segments(characters) {
+        const segments = []
+
+        for (const character of characters) {
+            const previousSegment = segments.at(-1)
+            if (
+                previousSegment &&
+                previousSegment.overline === character.overline
+            ) {
+                previousSegment.text += character.text
+                continue
+            }
+
+            segments.push({
+                text: character.text,
+                overline: character.overline
+            })
+        }
+
+        return segments
+    }
+}