altium-toolkit 0.1.0

package/src/core/ole/OleCompoundDocument.mjs

@@ -0,0 +1,439 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { BinaryReader } from '../BinaryReader.mjs'
+import { OleConstants } from './OleConstants.mjs'
+import { OleDirectoryEntry } from './OleDirectoryEntry.mjs'
+
+/**
+ * Reads OLE Compound Document streams.
+ */
+export class OleCompoundDocument {
+    #directoryEntries
+
+    #fatEntries
+
+    #header
+
+    #miniFatEntries
+
+    #miniStreamBytes
+
+    #reader
+
+    #streamPaths
+
+    /**
+     * @param {ArrayBuffer} arrayBuffer
+     */
+    constructor(arrayBuffer) {
+        this.#reader = new BinaryReader(arrayBuffer)
+        this.#header = this.#parseHeader()
+        this.#fatEntries = this.#parseFatEntries()
+        this.#directoryEntries = this.#parseDirectoryEntries()
+        this.#miniFatEntries = this.#parseMiniFatEntries()
+        this.#miniStreamBytes = this.#parseMiniStreamBytes()
+        this.#streamPaths = this.#collectStreamPaths()
+    }
+
+    /**
+     * Creates one compound document reader from raw bytes.
+     * @param {ArrayBuffer} arrayBuffer
+     * @returns {OleCompoundDocument}
+     */
+    static fromArrayBuffer(arrayBuffer) {
+        return new OleCompoundDocument(arrayBuffer)
+    }
+
+    /**
+     * Returns the sector size in bytes.
+     * @returns {number}
+     */
+    get sectorByteLength() {
+        return this.#header.sectorByteLength
+    }
+
+    /**
+     * Returns the mini-sector size in bytes.
+     * @returns {number}
+     */
+    get miniSectorByteLength() {
+        return this.#header.miniSectorByteLength
+    }
+
+    /**
+     * Lists all stream paths.
+     * @returns {string[]}
+     */
+    listStreams() {
+        return [...this.#streamPaths.keys()].sort((left, right) =>
+            left.localeCompare(right)
+        )
+    }
+
+    /**
+     * Resolves one stream by path or unique leaf name.
+     * @param {string} name
+     * @returns {Uint8Array}
+     */
+    getStream(name) {
+        const directMatch = this.#streamPaths.get(name)
+        if (directMatch) {
+            return this.#readEntryStream(directMatch)
+        }
+
+        const leafMatches = [...this.#streamPaths.entries()].filter(
+            ([path]) => path.split('/').at(-1) === name
+        )
+
+        if (!leafMatches.length) {
+            throw new Error('OLE stream not found: ' + name)
+        }
+
+        if (leafMatches.length > 1) {
+            throw new Error('OLE stream name is ambiguous: ' + name)
+        }
+
+        return this.#readEntryStream(leafMatches[0][1])
+    }
+
+    /**
+     * Parses and validates the OLE header.
+     * @returns {{ sectorByteLength: number, miniSectorByteLength: number, numberOfFatSectors: number, firstDirectorySector: number, miniStreamCutoff: number, firstMiniFatSector: number, numberOfMiniFatSectors: number, firstDifatSector: number, numberOfDifatSectors: number, difatEntries: number[] }}
+     */
+    #parseHeader() {
+        const signature = [
+            ...this.#reader.readBytes(0, OleConstants.HEADER_SIGNATURE.length)
+        ]
+
+        if (
+            signature.some(
+                (value, index) => value !== OleConstants.HEADER_SIGNATURE[index]
+            )
+        ) {
+            throw new Error('Invalid OLE header signature.')
+        }
+
+        const sectorByteLength = 2 ** this.#reader.readUint16(30)
+        const miniSectorByteLength = 2 ** this.#reader.readUint16(32)
+        const difatEntries = []
+
+        for (let index = 0; index < 109; index += 1) {
+            difatEntries.push(this.#reader.readInt32(76 + index * 4))
+        }
+
+        return {
+            sectorByteLength,
+            miniSectorByteLength,
+            numberOfFatSectors: this.#reader.readUint32(44),
+            firstDirectorySector: this.#reader.readInt32(48),
+            miniStreamCutoff: this.#reader.readUint32(56),
+            firstMiniFatSector: this.#reader.readInt32(60),
+            numberOfMiniFatSectors: this.#reader.readUint32(64),
+            firstDifatSector: this.#reader.readInt32(68),
+            numberOfDifatSectors: this.#reader.readUint32(72),
+            difatEntries
+        }
+    }
+
+    /**
+     * Parses all FAT entries.
+     * @returns {number[]}
+     */
+    #parseFatEntries() {
+        const fatSectorIds = this.#collectFatSectorIds()
+        const entries = []
+        const intsPerSector = this.#header.sectorByteLength / 4
+
+        for (const sectorId of fatSectorIds) {
+            const sectorBytes = this.#readSectorBytes(sectorId)
+            const reader = new BinaryReader(sectorBytes.buffer)
+
+            for (let index = 0; index < intsPerSector; index += 1) {
+                entries.push(reader.readInt32(index * 4))
+            }
+        }
+
+        return entries
+    }
+
+    /**
+     * Collects all FAT sector identifiers from the header and optional DIFAT
+     * sectors.
+     * @returns {number[]}
+     */
+    #collectFatSectorIds() {
+        const fatSectorIds = this.#header.difatEntries.filter(
+            (sectorId) => sectorId >= 0
+        )
+
+        if (
+            this.#header.firstDifatSector < 0 ||
+            this.#header.numberOfDifatSectors === 0
+        ) {
+            return fatSectorIds.slice(0, this.#header.numberOfFatSectors)
+        }
+
+        const intsPerSector = this.#header.sectorByteLength / 4
+        let currentSectorId = this.#header.firstDifatSector
+
+        for (
+            let difatIndex = 0;
+            difatIndex < this.#header.numberOfDifatSectors &&
+            currentSectorId >= 0;
+            difatIndex += 1
+        ) {
+            const sectorReader = new BinaryReader(
+                this.#readSectorBytes(currentSectorId).buffer
+            )
+
+            for (let index = 0; index < intsPerSector - 1; index += 1) {
+                const fatSectorId = sectorReader.readInt32(index * 4)
+                if (fatSectorId >= 0) {
+                    fatSectorIds.push(fatSectorId)
+                }
+            }
+
+            currentSectorId = sectorReader.readInt32((intsPerSector - 1) * 4)
+        }
+
+        return fatSectorIds.slice(0, this.#header.numberOfFatSectors)
+    }
+
+    /**
+     * Parses all directory entries reachable from the directory stream chain.
+     * @returns {OleDirectoryEntry[]}
+     */
+    #parseDirectoryEntries() {
+        const directoryChain = this.#readRegularChain(
+            this.#header.firstDirectorySector
+        )
+        const entryCount =
+            directoryChain.length / OleConstants.DIRECTORY_ENTRY_BYTE_LENGTH
+        const entries = []
+
+        for (let index = 0; index < entryCount; index += 1) {
+            const offset = index * OleConstants.DIRECTORY_ENTRY_BYTE_LENGTH
+            entries.push(
+                OleDirectoryEntry.fromBytes(
+                    directoryChain.slice(
+                        offset,
+                        offset + OleConstants.DIRECTORY_ENTRY_BYTE_LENGTH
+                    ),
+                    index
+                )
+            )
+        }
+
+        return entries
+    }
+
+    /**
+     * Parses all mini FAT entries.
+     * @returns {number[]}
+     */
+    #parseMiniFatEntries() {
+        if (
+            this.#header.firstMiniFatSector < 0 ||
+            this.#header.numberOfMiniFatSectors === 0
+        ) {
+            return []
+        }
+
+        const chain = this.#readRegularChain(this.#header.firstMiniFatSector)
+        const reader = new BinaryReader(chain.buffer)
+        const entryCount = chain.length / 4
+        const entries = []
+
+        for (let index = 0; index < entryCount; index += 1) {
+            entries.push(reader.readInt32(index * 4))
+        }
+
+        return entries
+    }
+
+    /**
+     * Reads the root mini-stream bytes.
+     * @returns {Uint8Array}
+     */
+    #parseMiniStreamBytes() {
+        const rootEntry = this.#directoryEntries.find((entry) =>
+            entry.isRootStorage()
+        )
+        if (!rootEntry || rootEntry.startSector < 0 || !rootEntry.streamSize) {
+            return new Uint8Array(0)
+        }
+
+        return this.#readRegularChain(rootEntry.startSector).slice(
+            0,
+            rootEntry.streamSize
+        )
+    }
+
+    /**
+     * Builds a path map for all reachable stream entries.
+     * @returns {Map<string, OleDirectoryEntry>}
+     */
+    #collectStreamPaths() {
+        const rootEntry = this.#directoryEntries.find((entry) =>
+            entry.isRootStorage()
+        )
+        const paths = new Map()
+
+        if (!rootEntry || rootEntry.childId < 0) {
+            return paths
+        }
+
+        this.#walkDirectoryTree(rootEntry.childId, '', paths)
+
+        return paths
+    }
+
+    /**
+     * Traverses one directory sibling tree.
+     * @param {number} entryId
+     * @param {string} basePath
+     * @param {Map<string, OleDirectoryEntry>} paths
+     */
+    #walkDirectoryTree(entryId, basePath, paths) {
+        if (entryId < 0) {
+            return
+        }
+
+        const entry = this.#directoryEntries[entryId]
+        if (!entry) {
+            return
+        }
+
+        this.#walkDirectoryTree(entry.leftSiblingId, basePath, paths)
+
+        const path = basePath ? basePath + '/' + entry.name : entry.name
+
+        if (entry.isStream()) {
+            paths.set(path, entry)
+        }
+
+        if (entry.isStorage() && !entry.isRootStorage() && entry.childId >= 0) {
+            this.#walkDirectoryTree(entry.childId, path, paths)
+        }
+
+        this.#walkDirectoryTree(entry.rightSiblingId, basePath, paths)
+    }
+
+    /**
+     * Reads one stream entry using the standard or mini FAT.
+     * @param {OleDirectoryEntry} entry
+     * @returns {Uint8Array}
+     */
+    #readEntryStream(entry) {
+        if (entry.streamSize < this.#header.miniStreamCutoff) {
+            return this.#readMiniStream(entry)
+        }
+
+        return this.#readRegularChain(entry.startSector).slice(
+            0,
+            entry.streamSize
+        )
+    }
+
+    /**
+     * Reads one standard-sector chain.
+     * @param {number} startSectorId
+     * @returns {Uint8Array}
+     */
+    #readRegularChain(startSectorId) {
+        return this.#concatenateSectors(
+            this.#readSectorChain(startSectorId, this.#fatEntries),
+            this.#header.sectorByteLength,
+            (sectorId) => this.#readSectorBytes(sectorId)
+        )
+    }
+
+    /**
+     * Reads one mini-sector-backed stream.
+     * @param {OleDirectoryEntry} entry
+     * @returns {Uint8Array}
+     */
+    #readMiniStream(entry) {
+        const sectorIds = this.#readSectorChain(
+            entry.startSector,
+            this.#miniFatEntries
+        )
+        const bytes = this.#concatenateSectors(
+            sectorIds,
+            this.#header.miniSectorByteLength,
+            (miniSectorId) =>
+                this.#miniStreamBytes.slice(
+                    miniSectorId * this.#header.miniSectorByteLength,
+                    (miniSectorId + 1) * this.#header.miniSectorByteLength
+                )
+        )
+
+        return bytes.slice(0, entry.streamSize)
+    }
+
+    /**
+     * Reads one chain of sector identifiers.
+     * @param {number} startSectorId
+     * @param {number[]} entries
+     * @returns {number[]}
+     */
+    #readSectorChain(startSectorId, entries) {
+        const sectorIds = []
+        const visited = new Set()
+        let currentSectorId = startSectorId
+
+        while (currentSectorId >= 0) {
+            if (visited.has(currentSectorId)) {
+                throw new Error(
+                    'OLE sector chain loop detected at sector ' +
+                        currentSectorId +
+                        '.'
+                )
+            }
+
+            visited.add(currentSectorId)
+            sectorIds.push(currentSectorId)
+
+            const nextSectorId = entries[currentSectorId]
+            if (nextSectorId === OleConstants.END_OF_CHAIN) {
+                break
+            }
+
+            currentSectorId = nextSectorId
+        }
+
+        return sectorIds
+    }
+
+    /**
+     * Concatenates sector bytes from one chain.
+     * @param {number[]} sectorIds
+     * @param {number} sectorByteLength
+     * @param {(sectorId: number) => Uint8Array} byteResolver
+     * @returns {Uint8Array}
+     */
+    #concatenateSectors(sectorIds, sectorByteLength, byteResolver) {
+        const bytes = new Uint8Array(sectorIds.length * sectorByteLength)
+
+        for (let index = 0; index < sectorIds.length; index += 1) {
+            bytes.set(byteResolver(sectorIds[index]), index * sectorByteLength)
+        }
+
+        return bytes
+    }
+
+    /**
+     * Reads one regular sector.
+     * @param {number} sectorId
+     * @returns {Uint8Array}
+     */
+    #readSectorBytes(sectorId) {
+        const offset =
+            OleConstants.HEADER_BYTE_LENGTH +
+            sectorId * this.#header.sectorByteLength
+
+        return this.#reader.readBytes(offset, this.#header.sectorByteLength)
+    }
+}

package/src/core/ole/OleConstants.mjs

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Shared OLE Compound Document constants.
+ */
+export class OleConstants {
+    /**
+     * @returns {number}
+     */
+    static get HEADER_BYTE_LENGTH() {
+        return 512
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get DIRECTORY_ENTRY_BYTE_LENGTH() {
+        return 128
+    }
+
+    /**
+     * @returns {number[]}
+     */
+    static get HEADER_SIGNATURE() {
+        return [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get FREE_SECTOR() {
+        return -1
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get END_OF_CHAIN() {
+        return -2
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get FAT_SECTOR() {
+        return -3
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get DIFAT_SECTOR() {
+        return -4
+    }
+
+    /**
+     * @returns {number}
+     */
+    static get NO_STREAM() {
+        return -1
+    }
+}

package/src/core/ole/OleDirectoryEntry.mjs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { BinaryReader } from '../BinaryReader.mjs'
+import { OleConstants } from './OleConstants.mjs'
+
+/**
+ * Represents one decoded OLE directory entry.
+ */
+export class OleDirectoryEntry {
+    /**
+     * @param {{ id: number, name: string, type: number, leftSiblingId: number, rightSiblingId: number, childId: number, startSector: number, streamSize: number }} options
+     */
+    constructor(options) {
+        this.id = options.id
+        this.name = options.name
+        this.type = options.type
+        this.leftSiblingId = options.leftSiblingId
+        this.rightSiblingId = options.rightSiblingId
+        this.childId = options.childId
+        this.startSector = options.startSector
+        this.streamSize = options.streamSize
+    }
+
+    /**
+     * Decodes one raw directory-entry buffer.
+     * @param {Uint8Array} bytes
+     * @param {number} id
+     * @returns {OleDirectoryEntry}
+     */
+    static fromBytes(bytes, id) {
+        const reader = new BinaryReader(
+            bytes.buffer.slice(
+                bytes.byteOffset,
+                bytes.byteOffset + bytes.byteLength
+            )
+        )
+        const nameByteLength = Math.max(
+            Math.min(reader.readUint16(64), 64) - 2,
+            0
+        )
+        const name = new TextDecoder('utf-16le')
+            .decode(reader.readBytes(0, nameByteLength))
+            .replace(/\u0000+$/g, '')
+
+        return new OleDirectoryEntry({
+            id,
+            name,
+            type: reader.readUint8(66),
+            leftSiblingId: reader.readInt32(68),
+            rightSiblingId: reader.readInt32(72),
+            childId: reader.readInt32(76),
+            startSector: reader.readInt32(116),
+            streamSize: reader.readUint64(120)
+        })
+    }
+
+    /**
+     * Returns true when this entry stores stream bytes.
+     * @returns {boolean}
+     */
+    isStream() {
+        return this.type === 2
+    }
+
+    /**
+     * Returns true when this entry is the root storage.
+     * @returns {boolean}
+     */
+    isRootStorage() {
+        return this.type === 5
+    }
+
+    /**
+     * Returns true when this entry is a non-root storage.
+     * @returns {boolean}
+     */
+    isStorage() {
+        return this.type === 1 || this.type === 5
+    }
+
+    /**
+     * Returns true when the entry has no useful payload.
+     * @returns {boolean}
+     */
+    isEmpty() {
+        return (
+            !this.name &&
+            this.type === 0 &&
+            this.startSector === OleConstants.NO_STREAM &&
+            this.streamSize === 0
+        )
+    }
+}

package/src/index.mjs

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export * from './parser.mjs'
+export * from './renderers.mjs'
+export * from './scene3d.mjs'

package/src/parser.mjs

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export { BinaryReader } from './core/BinaryReader.mjs'
+export { OleCompoundDocument } from './core/ole/OleCompoundDocument.mjs'
+export { OleConstants } from './core/ole/OleConstants.mjs'
+export { OleDirectoryEntry } from './core/ole/OleDirectoryEntry.mjs'
+export { AltiumParser } from './core/altium/AltiumParser.mjs'
+export { AltiumLayoutParser } from './core/altium/AltiumLayoutParser.mjs'
+export { AsciiRecordParser } from './core/altium/AsciiRecordParser.mjs'
+export { ParserUtils } from './core/altium/ParserUtils.mjs'
+export { PcbBinaryPrimitiveParser } from './core/altium/PcbBinaryPrimitiveParser.mjs'
+export { PcbEmbeddedModelExtractor } from './core/altium/PcbEmbeddedModelExtractor.mjs'
+export { PcbModelParser } from './core/altium/PcbModelParser.mjs'
+export { PcbOutlineRasterizer } from './core/altium/PcbOutlineRasterizer.mjs'
+export { PcbOutlineRecovery } from './core/altium/PcbOutlineRecovery.mjs'
+export { PcbStreamExtractor } from './core/altium/PcbStreamExtractor.mjs'
+export { PrintableTextDecoder } from './core/altium/PrintableTextDecoder.mjs'
+export { SchematicMultipartOwnerMatcher } from './core/altium/SchematicMultipartOwnerMatcher.mjs'
+export { SchematicStandaloneCalloutNormalizer } from './core/altium/SchematicStandaloneCalloutNormalizer.mjs'

package/src/renderers.mjs

@@ -0,0 +1,15 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export { BomTableRenderer } from './ui/BomTableRenderer.mjs'
+export { PcbArcUtils } from './ui/PcbArcUtils.mjs'
+export { PcbEdgeFacingGlyphNormalizer } from './ui/PcbEdgeFacingGlyphNormalizer.mjs'
+export { PcbFootprintPrimitiveSelector } from './ui/PcbFootprintPrimitiveSelector.mjs'
+export { PcbSvgRenderer } from './ui/PcbSvgRenderer.mjs'
+export { SchematicColorResolver } from './ui/SchematicColorResolver.mjs'
+export { SchematicContentLayout } from './ui/SchematicContentLayout.mjs'
+export { SchematicOwnerPinLabelLayout } from './ui/SchematicOwnerPinLabelLayout.mjs'
+export { SchematicSvgRenderer } from './ui/SchematicSvgRenderer.mjs'
+export { SchematicSvgUtils } from './ui/SchematicSvgUtils.mjs'
+export { SchematicTypography } from './ui/SchematicTypography.mjs'

package/src/scene3d.mjs

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export { PcbScene3dBuilder } from './ui/PcbScene3dBuilder.mjs'
+export { PcbScene3dModelRegistry } from './ui/PcbScene3dModelRegistry.mjs'
+export { PcbScene3dPackages } from './ui/PcbScene3dPackages.mjs'
+export { PcbScene3dScenePreparator } from './ui/PcbScene3dScenePreparator.mjs'
+export { PcbScene3dSummaryRenderer } from './ui/PcbScene3dSummaryRenderer.mjs'