altium-toolkit 1.1.3 → 1.1.22

package/src/core/altium/SchematicPinParser.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { ParserUtils } from './ParserUtils.mjs'
+import { SchematicNoErcSymbolResolver } from './SchematicNoErcSymbolResolver.mjs'
 import { SchematicPinDesignatorInferer } from './SchematicPinDesignatorInferer.mjs'
 
 /**
@@ -66,11 +67,9 @@ export class SchematicPinParser {
                 ),
                 designator: ParserUtils.getField(record.fields, 'Designator'),
                 orientation,
-                electrical:
-                    ParserUtils.parseNumericField(
-                        record.fields,
-                        'Electrical'
-                    ) || undefined,
+                electrical: SchematicPinParser.#parseSchematicPinElectrical(
+                    record.fields
+                ),
                 symbolOuter:
                     ParserUtils.parseNumericField(
                         record.fields,
@@ -94,6 +93,30 @@ export class SchematicPinParser {
         )
     }
 
+    /**
+     * Parses Altium's pin electrical type, including its omitted-field default.
+     * Formal schematic pin records omit Electrical for input pins and serialize
+     * passive pins explicitly as Electrical=4.
+     * @param {Record<string, string | string[]>} fields Pin record fields.
+     * @returns {number | undefined}
+     */
+    static #parseSchematicPinElectrical(fields) {
+        const explicitElectrical = ParserUtils.parseNumericField(
+            fields,
+            'Electrical'
+        )
+
+        if (explicitElectrical !== null) {
+            return explicitElectrical
+        }
+
+        if (ParserUtils.parseNumericField(fields, 'FormalType') !== null) {
+            return 0
+        }
+
+        return undefined
+    }
+
     /**
      * Normalizes schematic port records into drawable port boxes.
      * @param {{ fields: Record<string, string | string[]> }[]} records
@@ -386,24 +409,36 @@ export class SchematicPinParser {
     /**
      * Normalizes no-connect crosses from schematic records.
      * @param {{ fields: Record<string, string | string[]> }[]} records
-     * @returns {{ x: number, y: number, size: number, color: string }[]}
+     * @returns {{ x: number, y: number, size: number, color: string, symbol: number | null, symbolName: string }[]}
      */
     static parseSchematicCrosses(records) {
         return records
-            .map((record) => ({
-                x:
-                    ParserUtils.parseNumericField(
-                        record.fields,
-                        'Location.X'
-                    ) || 0,
-                y:
-                    ParserUtils.parseNumericField(
-                        record.fields,
-                        'Location.Y'
-                    ) || 0,
-                size: 6,
-                color: ParserUtils.toColor(record.fields.Color, '#ff0000')
-            }))
+            .map((record) => {
+                const rawSymbol = ParserUtils.getField(record.fields, 'Symbol')
+                const symbol = ParserUtils.parseNumericField(
+                    record.fields,
+                    'Symbol'
+                )
+
+                return {
+                    x:
+                        ParserUtils.parseNumericField(
+                            record.fields,
+                            'Location.X'
+                        ) || 0,
+                    y:
+                        ParserUtils.parseNumericField(
+                            record.fields,
+                            'Location.Y'
+                        ) || 0,
+                    size: 6,
+                    color: ParserUtils.toColor(record.fields.Color, '#ff0000'),
+                    symbol,
+                    symbolName: SchematicNoErcSymbolResolver.resolveSymbolName(
+                        rawSymbol || symbol
+                    )
+                }
+            })
             .filter((cross) => cross.x || cross.y)
     }
 
@@ -816,6 +851,13 @@ export class SchematicPinParser {
             SchematicPinParser.#isTwoPinNumericEndpointGroup(normalizedPins)
         ) {
             labelMode = 'number-only'
+        } else if (
+            SchematicPinParser.#isCompactSinglePinMarkerGroup(
+                normalizedPins,
+                names
+            )
+        ) {
+            labelMode = 'hidden'
         } else if (allPassive && normalizedPins.length <= 2) {
             labelMode = SchematicPinParser.#isCanonicalPassiveTwoPinGroup(
                 normalizedPins
@@ -875,6 +917,31 @@ export class SchematicPinParser {
         }))
     }
 
+    /**
+     * Returns true when a single owner pin belongs to compact marker artwork
+     * rather than to a visibly numbered electrical contact.
+     * @param {{ designator: string, name: string, length: number, electrical?: number }[]} pins
+     * @param {string[]} names
+     * @returns {boolean}
+     */
+    static #isCompactSinglePinMarkerGroup(pins, names) {
+        if (pins.length !== 1 || names.length !== 0) {
+            return false
+        }
+
+        const pin = pins[0]
+        const designator = String(pin.designator || '').trim()
+        const length = Math.abs(Number(pin.length || 0))
+        const electrical = Number(pin.electrical)
+
+        return (
+            /^\d+$/.test(designator) &&
+            length > 0 &&
+            length <= 15 &&
+            (!Number.isFinite(electrical) || electrical === 4)
+        )
+    }
+
     /**
      * Returns true when a compact owner-drawn FET body uses semantic terminal
      * names internally but still exposes external numeric contact labels.

package/src/core/altium/SchematicPrimitiveParser.mjs

@@ -98,6 +98,18 @@ export class SchematicPrimitiveParser {
         )
     }
 
+    /**
+     * Returns true when one point-listed record carries only an axis-aligned
+     * rectangular point list without authored `Location` and `Corner` fields.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {boolean}
+     */
+    static isPointListedRectangleRecord(fields) {
+        return Boolean(
+            SchematicPrimitiveParser.#pointListedRectangleBounds(fields)
+        )
+    }
+
     /**
      * Normalizes record-7 polygon primitives into fill-capable polygons.
      * @param {{ fields: Record<string, string | string[]> }[]} records
@@ -352,16 +364,32 @@ export class SchematicPrimitiveParser {
     static parseSchematicRectangles(records) {
         return records
             .map((record, index) => {
-                const x1 = parseNumericField(record.fields, 'Location.X')
-                const y1 = parseNumericField(record.fields, 'Location.Y')
-                const x2 = parseNumericField(record.fields, 'Corner.X')
-                const y2 = parseNumericField(record.fields, 'Corner.Y')
+                const pointListedBounds =
+                    SchematicPrimitiveParser.#pointListedRectangleBounds(
+                        record.fields
+                    )
+                const x1 =
+                    parseNumericField(record.fields, 'Location.X') ??
+                    pointListedBounds?.minX ??
+                    null
+                const y1 =
+                    parseNumericField(record.fields, 'Location.Y') ??
+                    pointListedBounds?.minY ??
+                    null
+                const x2 =
+                    parseNumericField(record.fields, 'Corner.X') ??
+                    pointListedBounds?.maxX ??
+                    null
+                const y2 =
+                    parseNumericField(record.fields, 'Corner.Y') ??
+                    pointListedBounds?.maxY ??
+                    null
                 const isRectangleRecord =
                     SchematicPrimitiveParser.isRectangleRecord(record.fields)
                 const isListedRectangle =
                     SchematicPrimitiveParser.isListedRectangleRecord(
                         record.fields
-                    )
+                    ) || Boolean(pointListedBounds)
                 const usesFrameFallback =
                     SchematicPrimitiveParser.#shouldUseFrameFallback(
                         record.fields,
@@ -402,9 +430,15 @@ export class SchematicPrimitiveParser {
                         : parseBoolean(record.fields.Transparent),
                     lineWidth:
                         parseNumericField(record.fields, 'LineWidth') || 1,
-                    lineStyle: usesFrameFallback
-                        ? 1
-                        : parseNumericField(record.fields, 'LineStyle') || 0,
+                    lineStyle:
+                        usesFrameFallback ||
+                        SchematicPrimitiveParser.#shouldDefaultBlanketDash(
+                            record.fields,
+                            pointListedBounds
+                        )
+                            ? 1
+                            : parseNumericField(record.fields, 'LineStyle') ||
+                              0,
                     renderOrder: SchematicPrimitiveParser.#resolveRenderOrder(
                         record.fields,
                         index
@@ -989,6 +1023,80 @@ export class SchematicPrimitiveParser {
         )
     }
 
+    /**
+     * Returns true when a point-listed blanket should use Altium's dashed frame
+     * style even when the printable record omits `LineStyle`.
+     * @param {Record<string, string | string[]>} fields Record fields.
+     * @param {{ minX: number, minY: number, maxX: number, maxY: number } | null} pointListedBounds Point-listed bounds.
+     * @returns {boolean}
+     */
+    static #shouldDefaultBlanketDash(fields, pointListedBounds) {
+        return (
+            Boolean(pointListedBounds) &&
+            getField(fields, 'RECORD') === '225' &&
+            getField(fields, 'LineStyle') === ''
+        )
+    }
+
+    /**
+     * Resolves rectangle bounds from a point-listed axis-aligned frame.
+     * @param {Record<string, string | string[]>} fields Record fields.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static #pointListedRectangleBounds(fields) {
+        const points = SchematicPrimitiveParser.#normalizeClosedPointList(
+            SchematicPrimitiveParser.#collectPolygonPoints(fields)
+        )
+
+        if (points.length !== 4) {
+            return null
+        }
+
+        const xs = [...new Set(points.map((point) => point.x))]
+        const ys = [...new Set(points.map((point) => point.y))]
+
+        if (xs.length !== 2 || ys.length !== 2) {
+            return null
+        }
+
+        const minX = Math.min(...xs)
+        const maxX = Math.max(...xs)
+        const minY = Math.min(...ys)
+        const maxY = Math.max(...ys)
+        const corners = new Set([
+            minX + ':' + minY,
+            minX + ':' + maxY,
+            maxX + ':' + minY,
+            maxX + ':' + maxY
+        ])
+
+        if (!points.every((point) => corners.has(point.x + ':' + point.y))) {
+            return null
+        }
+
+        return { minX, minY, maxX, maxY }
+    }
+
+    /**
+     * Removes an optional repeated closing point from one source point list.
+     * @param {{ x: number, y: number }[]} points Source points.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #normalizeClosedPointList(points) {
+        if (points.length < 2) {
+            return points
+        }
+
+        const first = points[0]
+        const last = points.at(-1)
+
+        if (first.x === last.x && first.y === last.y) {
+            return points.slice(0, -1)
+        }
+
+        return points
+    }
+
     /**
      * Collects one record-7 polygon point list in source order.
      * @param {Record<string, string | string[]>} fields

package/src/core/altium/SchematicStreamExtractor.mjs

@@ -12,6 +12,8 @@ import { OleConstants } from '../ole/OleConstants.mjs'
  * containers.
  */
 export class SchematicStreamExtractor {
+    static #AUXILIARY_PRINTABLE_STREAMS = new Set(['Additional'])
+
     /**
      * Returns true when one buffer starts with the OLE compound-document
      * signature.
@@ -38,9 +40,10 @@ export class SchematicStreamExtractor {
     }
 
     /**
-     * Extracts schematic records from the logical `FileHeader` stream.
+     * Extracts schematic records from the logical `FileHeader` stream and
+     * Altium's auxiliary printable schematic streams.
      * @param {ArrayBuffer} arrayBuffer
-     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[] } | null}
+     * @returns {{ records: Array<{ raw: string, fields: Record<string, string | string[]>, sourceStream: string }>, streamNames: string[], embeddedFiles?: object } | null}
      */
     static extractFromArrayBuffer(arrayBuffer) {
         if (!SchematicStreamExtractor.isCompoundDocument(arrayBuffer)) {
@@ -55,20 +58,28 @@ export class SchematicStreamExtractor {
             return null
         }
 
-        let fileHeaderBytes
+        let fileHeaderRecords
 
         try {
-            fileHeaderBytes = compoundDocument.getStream('FileHeader')
+            fileHeaderRecords = SchematicStreamExtractor.#parseStreamRecords(
+                compoundDocument,
+                'FileHeader'
+            )
         } catch {
             return null
         }
 
-        const records = AsciiRecordParser.parse(
-            SchematicStreamExtractor.#toArrayBuffer(fileHeaderBytes)
-        ).map((record) => ({
-            ...record,
-            sourceStream: 'FileHeader'
-        }))
+        const streamNames = compoundDocument.listStreams()
+        const auxiliaryStreamNames = streamNames.filter((streamName) =>
+            SchematicStreamExtractor.#isAuxiliaryPrintableStream(streamName)
+        )
+        const auxiliaryRecords = auxiliaryStreamNames.flatMap((streamName) =>
+            SchematicStreamExtractor.#parseStreamRecords(
+                compoundDocument,
+                streamName
+            )
+        )
+        const records = [...fileHeaderRecords, ...auxiliaryRecords]
 
         if (!records.length) {
             return null
@@ -76,18 +87,54 @@ export class SchematicStreamExtractor {
 
         return {
             records,
-            streamNames: compoundDocument.listStreams(),
+            streamNames,
             embeddedFiles: EmbeddedFileInventoryBuilder.buildFromStreams(
                 new Map(
-                    compoundDocument
-                        .listStreams()
-                        .map((name) => [name, compoundDocument.getStream(name)])
+                    streamNames.map((name) => [
+                        name,
+                        compoundDocument.getStream(name)
+                    ])
                 ),
-                { skipStreamNames: ['FileHeader'] }
+                {
+                    skipStreamNames: ['FileHeader', ...auxiliaryStreamNames]
+                }
             )
         }
     }
 
+    /**
+     * 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 }>}
+     */
+    static #parseStreamRecords(compoundDocument, streamName) {
+        return AsciiRecordParser.parse(
+            SchematicStreamExtractor.#toArrayBuffer(
+                compoundDocument.getStream(streamName)
+            )
+        ).map((record) => ({
+            ...record,
+            sourceStream: streamName
+        }))
+    }
+
+    /**
+     * Returns true for known non-embedded schematic streams with printable
+     * primitive records.
+     * @param {string} streamName
+     * @returns {boolean}
+     */
+    static #isAuxiliaryPrintableStream(streamName) {
+        const leafName = String(streamName || '')
+            .split('/')
+            .at(-1)
+
+        return SchematicStreamExtractor.#AUXILIARY_PRINTABLE_STREAMS.has(
+            leafName
+        )
+    }
+
     /**
      * Returns an ArrayBuffer view over one byte slice.
      * @param {Uint8Array} bytes

package/src/core/altium/SourceBundleExporter.mjs

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SourceComponentBundleNormalizer } from './SourceComponentBundleNormalizer.mjs'
+
+/**
+ * Exports normalized source component bundles as deterministic file entries.
+ */
+export class SourceBundleExporter {
+    /**
+     * Exports one source bundle.
+     * @param {object} componentBundle Component bundle or raw response.
+     * @param {{ includeModels?: boolean }} [options] Export options.
+     * @returns {{ manifest: object, entries: { path: string, bytes: Uint8Array, contentType: string }[] }}
+     */
+    static export(componentBundle, options = {}) {
+        const bundle =
+            SourceComponentBundleNormalizer.normalize(componentBundle)
+        const includeModels = options.includeModels !== false
+        const manifest = SourceBundleExporter.#buildManifest(
+            bundle,
+            includeModels
+        )
+        const entries = [
+            SourceBundleExporter.#jsonEntry('manifest.json', manifest),
+            SourceBundleExporter.#jsonEntry(
+                'source/source.json',
+                bundle.sourceJson
+            )
+        ]
+
+        if (includeModels) {
+            entries.push(
+                ...bundle.models.map((model) => ({
+                    path:
+                        'models/' +
+                        SourceBundleExporter.#safeFileName(model.name),
+                    bytes: model.bytes,
+                    contentType: SourceBundleExporter.#modelContentType(model)
+                }))
+            )
+        }
+
+        return {
+            manifest,
+            entries: entries.sort((left, right) =>
+                left.path.localeCompare(right.path)
+            )
+        }
+    }
+
+    /**
+     * Builds a deterministic manifest.
+     * @param {object} bundle Normalized bundle.
+     * @param {boolean} includeModels Whether model assets are included.
+     * @returns {object}
+     */
+    static #buildManifest(bundle, includeModels) {
+        return {
+            schema: 'ecad-source-bundle-v1',
+            component: {
+                id: bundle.id,
+                name: bundle.name,
+                symbolName: bundle.symbol.name,
+                footprintName: bundle.footprint.name
+            },
+            assets: includeModels
+                ? bundle.models.map((model) => ({
+                      name: model.name,
+                      format: model.format,
+                      path:
+                          'models/' +
+                          SourceBundleExporter.#safeFileName(model.name),
+                      byteLength: model.bytes.byteLength
+                  }))
+                : []
+        }
+    }
+
+    /**
+     * Creates one JSON entry.
+     * @param {string} path Entry path.
+     * @param {object} value JSON value.
+     * @returns {{ path: string, bytes: Uint8Array, contentType: string }}
+     */
+    static #jsonEntry(path, value) {
+        return {
+            path,
+            bytes: new TextEncoder().encode(
+                SourceBundleExporter.#stableStringify(value) + '\n'
+            ),
+            contentType: 'application/json'
+        }
+    }
+
+    /**
+     * Returns a stable JSON string with sorted object keys.
+     * @param {any} value JSON-compatible value.
+     * @returns {string}
+     */
+    static #stableStringify(value) {
+        return JSON.stringify(SourceBundleExporter.#sortJson(value), null, 2)
+    }
+
+    /**
+     * Recursively sorts JSON object keys.
+     * @param {any} value JSON-compatible value.
+     * @returns {any}
+     */
+    static #sortJson(value) {
+        if (Array.isArray(value)) {
+            return value.map((entry) => SourceBundleExporter.#sortJson(entry))
+        }
+
+        if (
+            value &&
+            typeof value === 'object' &&
+            !(value instanceof Uint8Array)
+        ) {
+            return Object.fromEntries(
+                Object.keys(value)
+                    .sort()
+                    .map((key) => [
+                        key,
+                        SourceBundleExporter.#sortJson(value[key])
+                    ])
+            )
+        }
+
+        return value
+    }
+
+    /**
+     * Returns a safe bundle file name.
+     * @param {string} name Raw file name.
+     * @returns {string}
+     */
+    static #safeFileName(name) {
+        return String(name || 'model.step').replace(
+            /[\\/:\u0000-\u001f]/gu,
+            '_'
+        )
+    }
+
+    /**
+     * Resolves a model content type.
+     * @param {object} model Model descriptor.
+     * @returns {string}
+     */
+    static #modelContentType(model) {
+        if (model.format === 'obj') return 'model/obj'
+        if (model.format === 'mtl') return 'text/plain'
+        return 'model/step'
+    }
+}