altium-toolkit 0.1.16 → 0.1.18

package/README.md

@@ -12,8 +12,9 @@ outputs from the recovered model.
 
 The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
 is used for browser-based Altium document parsing and deterministic render
-output. Its parser behavior, normalized model shape, and renderer output can be
-reused by other browser or Node-based tools.
+output. It is also used in [PCB Styler](https://pcb-styler.app/). Its parser
+behavior, normalized model shape, and renderer output can be reused by other
+browser or Node-based tools.
 
 ## Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "0.1.16",
+    "version": "0.1.18",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/core/altium/AsciiRecordParser.mjs

@@ -16,6 +16,7 @@ export class AsciiRecordParser {
     static parse(arrayBuffer) {
         const runs = PrintableTextDecoder.extractRunBytes(arrayBuffer)
         const records = []
+        let pendingPrefix = ''
 
         for (const runBytes of runs) {
             const run = AsciiRecordParser.#bytesToBinaryString(runBytes)
@@ -26,10 +27,30 @@ export class AsciiRecordParser {
             for (const chunk of chunks) {
                 const candidate = chunk.trim()
                 if (!AsciiRecordParser.#isRecordCandidate(candidate)) continue
-                records.push(AsciiRecordParser.#parseRecord(candidate))
+
+                const headerPrefix =
+                    AsciiRecordParser.#extractHeaderFieldPrefix(candidate)
+                if (headerPrefix) {
+                    pendingPrefix += headerPrefix
+                    continue
+                }
+
+                if (!AsciiRecordParser.#hasRecordMarker(candidate)) {
+                    pendingPrefix += candidate
+                    continue
+                }
+
+                records.push(
+                    AsciiRecordParser.#parseRecord(pendingPrefix + candidate)
+                )
+                pendingPrefix = ''
             }
         }
 
+        if (pendingPrefix) {
+            records.push(AsciiRecordParser.#parseRecord(pendingPrefix))
+        }
+
         return records
     }
 
@@ -44,6 +65,40 @@ export class AsciiRecordParser {
         return candidate.split('|').length >= 4
     }
 
+    /**
+     * Returns true when a printable fragment contains its marker field.
+     * @param {string} candidate
+     * @returns {boolean}
+     */
+    static #hasRecordMarker(candidate) {
+        return /(?:^|\|)(?:HEADER|RECORD|UNICODE|SELECTION|KIND)=/.test(
+            candidate
+        )
+    }
+
+    /**
+     * Extracts schematic sheet fields that trail a schematic header before the
+     * first record.
+     * @param {string} candidate
+     * @returns {string}
+     */
+    static #extractHeaderFieldPrefix(candidate) {
+        if (!candidate.startsWith('|HEADER=')) {
+            return ''
+        }
+
+        const segments = candidate.split('|').filter(Boolean)
+        if (segments.length <= 1) {
+            return ''
+        }
+        const headerValue = segments[0].slice('HEADER='.length)
+        if (!/^Schematic Document$/i.test(headerValue)) {
+            return ''
+        }
+
+        return '|' + segments.slice(1).join('|')
+    }
+
     /**
      * Parses one pipe-delimited record into a field object.
      * @param {string} raw
@@ -89,7 +144,61 @@ export class AsciiRecordParser {
             AsciiRecordParser.#appendFieldValue(fields, key, value)
         }
 
-        return { raw, fields }
+        return {
+            raw,
+            fields: AsciiRecordParser.#createCaseInsensitiveFields(fields)
+        }
+    }
+
+    /**
+     * Wraps parsed fields so consumers can read native records regardless of
+     * whether the printable stream used upper, lower, or mixed-case keys.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {Record<string, string | string[]>}
+     */
+    static #createCaseInsensitiveFields(fields) {
+        const normalizedKeyIndex =
+            AsciiRecordParser.#buildCaseInsensitiveFieldIndex(fields)
+
+        return new Proxy(fields, {
+            get(target, property, receiver) {
+                if (typeof property !== 'string' || property in target) {
+                    return Reflect.get(target, property, receiver)
+                }
+
+                const normalizedKey = normalizedKeyIndex.get(
+                    property.toLowerCase()
+                )
+                return normalizedKey
+                    ? Reflect.get(target, normalizedKey, receiver)
+                    : undefined
+            },
+            has(target, property) {
+                if (typeof property !== 'string' || property in target) {
+                    return Reflect.has(target, property)
+                }
+
+                return normalizedKeyIndex.has(property.toLowerCase())
+            }
+        })
+    }
+
+    /**
+     * Builds a lookup from lower-case field names to their source key.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {Map<string, string>}
+     */
+    static #buildCaseInsensitiveFieldIndex(fields) {
+        const normalizedKeyIndex = new Map()
+
+        for (const key of Object.keys(fields)) {
+            const normalizedKey = key.toLowerCase()
+            if (!normalizedKeyIndex.has(normalizedKey)) {
+                normalizedKeyIndex.set(normalizedKey, key)
+            }
+        }
+
+        return normalizedKeyIndex
     }
 
     /**

package/src/core/altium/PcbComponentAnnotationNormalizer.mjs

@@ -112,12 +112,21 @@ export class PcbComponentAnnotationNormalizer {
      * @returns {number | null}
      */
     static #textComponentIndex(text) {
-        const componentIndex = Number(text?.componentIndex)
-        if (Number.isInteger(componentIndex)) {
-            return componentIndex
+        if (
+            text?.componentIndex !== null &&
+            text?.componentIndex !== undefined
+        ) {
+            const componentIndex = Number(text.componentIndex)
+            if (Number.isInteger(componentIndex)) {
+                return componentIndex
+            }
+        }
+
+        if (text?.ownerIndex === null || text?.ownerIndex === undefined) {
+            return null
         }
 
-        const ownerIndex = Number(text?.ownerIndex)
+        const ownerIndex = Number(text.ownerIndex)
         return Number.isInteger(ownerIndex) ? ownerIndex : null
     }
 

package/src/core/altium/PcbLibStreamExtractor.mjs

@@ -32,7 +32,7 @@ export class PcbLibStreamExtractor {
             type: 'via',
             collection: 'vias',
             minimumSubrecordCount: 1,
-            minimumPayloadByteLength: 321,
+            minimumPayloadByteLength: 209,
             parser: 'parseViaStream'
         },
         4: {

package/src/core/altium/PcbModelParser.mjs

@@ -367,7 +367,7 @@ export class PcbModelParser {
             summary: {
                 title: stripExtension(fileName),
                 componentCount: componentRecords.length,
-                layerCount: layers.length,
+                layerCount: layers.length || primitiveLayers.length,
                 outlineSegmentCount: boardOutline.segments.length,
                 bomRowCount: bom.length,
                 netCount: nets.length,

package/src/core/altium/PcbRawRecordRegistry.mjs

@@ -45,7 +45,7 @@ export class PcbRawRecordRegistry {
                 type: 'via',
                 typeId: 3,
                 fixedRecordByteLength: 326,
-                minimumPayloadByteLength: 321,
+                minimumPayloadByteLength: 209,
                 lengthPrefixedView: 'record',
                 parser: 'PcbViaPrimitiveParser',
                 strategy: 'slicer'

package/src/core/altium/PcbViaPrimitiveParser.mjs

@@ -14,7 +14,7 @@ export class PcbViaPrimitiveParser {
 
     static #VIA_RECORD_BYTE_LENGTH = 326
 
-    static #VIA_PAYLOAD_MIN_BYTE_LENGTH = 321
+    static #VIA_PAYLOAD_MIN_BYTE_LENGTH = 209
 
     /**
      * Decodes one via stream.

package/src/core/altium/SchematicPinParser.mjs

@@ -422,8 +422,7 @@ export class SchematicPinParser {
         }
 
         const segments = []
-        const lineStyle =
-            ParserUtils.parseNumericField(fields, 'LineStyle') || 0
+        const lineStyle = SchematicPinParser.#resolveSchematicLineStyle(fields)
 
         for (let index = 1; index < points.length; index += 1) {
             const previous = points[index - 1]
@@ -477,8 +476,7 @@ export class SchematicPinParser {
         }
 
         const segments = []
-        const lineStyle =
-            ParserUtils.parseNumericField(fields, 'LineStyle') || 0
+        const lineStyle = SchematicPinParser.#resolveSchematicLineStyle(fields)
 
         for (let index = 1; index < points.length; index += 1) {
             const previous = points[index - 1]
@@ -511,6 +509,24 @@ export class SchematicPinParser {
         return segments
     }
 
+    /**
+     * Resolves Altium's legacy and extended schematic line style fields.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {number}
+     */
+    static #resolveSchematicLineStyle(fields) {
+        const extendedStyle = ParserUtils.parseNumericField(
+            fields,
+            'LineStyleExt'
+        )
+
+        if (extendedStyle !== null) {
+            return extendedStyle
+        }
+
+        return ParserUtils.parseNumericField(fields, 'LineStyle') || 0
+    }
+
     /**
      * Deduces the visible pins for one schematic symbol owner.
      * @param {{ x: number, y: number, length: number, conglomerate?: number, name: string, nameSegments?: { text: string, overline: boolean }[], designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', electrical?: number, symbolOuter?: number, ownerIndex: string }[]} pins

package/src/core/altium/SchematicTextParser.mjs

@@ -60,7 +60,7 @@ export class SchematicTextParser {
      * Normalizes one schematic text record into a drawable text node.
      * @param {Record<string, string | string[]>} fields
      * @param {Record<string, string>} metadata
-     * @param {{ width: number, marginWidth: number }} sheet
+     * @param {{ width: number, marginWidth: number, titleBlockOn?: boolean }} sheet
      * @param {Record<string, { size: number, family: string, bold: boolean, rotation: number }>} fonts
      * @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, 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}
      */
@@ -431,14 +431,13 @@ export class SchematicTextParser {
      * @param {string} name
      * @param {string} rawText
      * @param {string} text
-     * @param {{ width: number, marginWidth: number }} sheet
+     * @param {{ width: number, marginWidth: number, titleBlockOn?: boolean }} sheet
      * @returns {boolean}
      */
     static #shouldSkipSchematicText(fields, name, rawText, text, sheet) {
         const normalizedName = String(name || '')
             .trim()
             .toLowerCase()
-        const normalizedRawText = String(rawText || '').trim()
         const normalizedText = String(text || '').trim()
         const nonDrawableNames = new Set([
             'kind',
@@ -448,16 +447,25 @@ export class SchematicTextParser {
             'model',
             'part number',
             'pkg type',
-            'description'
+            'description',
+            'vendor',
+            'manufacturer',
+            'supplier',
+            'ic',
+            'pinuniqueid',
+            'differentialpair'
         ])
 
         if (nonDrawableNames.has(normalizedName)) return true
+        if (/uniqueid$/i.test(normalizedName)) return true
         if (!normalizedText || normalizedText === '*') return true
         if (/^=/.test(normalizedText)) return true
-        if (SchematicTextParser.isTitleBlockFooterRecord(fields, sheet.width)) {
+        if (
+            sheet.titleBlockOn &&
+            SchematicTextParser.isTitleBlockFooterRecord(fields, sheet.width)
+        ) {
             return true
         }
-        if (/^=/.test(normalizedRawText)) return true
 
         return /@designator|initial voltage/i.test(normalizedText)
     }

package/src/styles/altium-renderers.css

@@ -247,11 +247,14 @@
     fill: var(--pcb-copper-solid-fill);
 }
 
-.pcb-footprint-fill,
-.pcb-footprint-region {
+.pcb-footprint-fill {
     fill: var(--pcb-footprint-fill);
 }
 
+.pcb-footprint-region {
+    fill: var(--pcb-footprint-track-color);
+}
+
 .pcb-footprint-track,
 .pcb-footprint-arc {
     stroke: var(--pcb-footprint-track-color);
@@ -269,7 +272,7 @@
 
 .pcb-text {
     font-size: 29px;
-    fill: var(--pcb-component-text);
+    fill: var(--pcb-footprint-track-color);
     font-weight: 700;
     font-family: Arial, sans-serif;
     pointer-events: none;

package/src/ui/PcbSvgRenderer.mjs

@@ -40,8 +40,11 @@ export class PcbSvgRenderer {
         const vias = pcb.vias || []
         const pads = pcb.pads || []
         const components = pcb.components.slice(0, 260)
+        const stackLayers = Array.isArray(pcb.layers) ? pcb.layers : []
+        const primitiveLayers = pcb.primitiveLayers || []
+        const displayLayers = stackLayers.length ? stackLayers : primitiveLayers
         const texts = PcbTextPrimitiveRenderer.select(
-            pcb.primitiveLayers || [],
+            primitiveLayers,
             pcb.texts || [],
             'top'
         )
@@ -54,7 +57,7 @@ export class PcbSvgRenderer {
         )
         const footprintPrimitives = PcbEdgeFacingGlyphNormalizer.normalize(
             PcbFootprintPrimitiveSelector.select(
-                pcb.primitiveLayers || [],
+                primitiveLayers,
                 fills,
                 tracks,
                 arcs,
@@ -95,7 +98,7 @@ export class PcbSvgRenderer {
             vias,
             pads
         )
-        const layerMarkup = pcb.layers
+        const layerMarkup = displayLayers
             .slice(0, 10)
             .map(
                 (layer) =>
@@ -307,7 +310,7 @@ export class PcbSvgRenderer {
             '</h3><p>' +
             components.length +
             ' placements, ' +
-            pcb.layers.length +
+            displayLayers.length +
             ' layers</p></header>' +
             '<div class="pcb-layout">' +
             '<aside class="pcb-legend"><h4>Board stack</h4><p>Top-facing composite view</p><ul>' +

package/src/ui/SchematicContentLayout.mjs

@@ -246,27 +246,44 @@ export class SchematicContentLayout {
         }
 
         const virtualInnerWidth = virtualSourceSheet.width - margin * 2
-        const scale = (width - margin * 2) / virtualInnerWidth
+        const targetScale = (width - margin * 2) / virtualInnerWidth
 
-        if (!Number.isFinite(scale) || scale <= 1) {
+        if (!Number.isFinite(targetScale) || targetScale <= 1) {
             return ''
         }
 
         const pivotX = margin
         const pivotY = height - margin
+        const topLimit = margin + contentPadding * 0.2
+        const bottomLimit = height - margin - footerReserve
+        const rightLimit = width - margin
+        const scale = Math.min(
+            targetScale,
+            ...SchematicContentLayout.#resolvePivotScaleLimits(
+                bounds,
+                pivotX,
+                pivotY,
+                margin,
+                topLimit,
+                rightLimit,
+                bottomLimit
+            )
+        )
+
+        if (!Number.isFinite(scale) || scale <= 1) {
+            return ''
+        }
+
         const projectedMinX = pivotX + (bounds.minX - pivotX) * scale
         const projectedMaxX = pivotX + (bounds.maxX - pivotX) * scale
         const projectedMinY = pivotY + (bounds.minY - pivotY) * scale
         const projectedMaxY = pivotY + (bounds.maxY - pivotY) * scale
-        const topLimit = margin + contentPadding
-        const bottomLimit = height - margin - footerReserve
-        const rightLimit = width - margin
 
         if (
-            projectedMinX < margin ||
-            projectedMaxX > rightLimit ||
-            projectedMinY < topLimit ||
-            projectedMaxY > bottomLimit
+            projectedMinX < margin - 0.01 ||
+            projectedMaxX > rightLimit + 0.01 ||
+            projectedMinY < topLimit - 0.01 ||
+            projectedMaxY > bottomLimit + 0.01
         ) {
             return ''
         }
@@ -286,6 +303,74 @@ export class SchematicContentLayout {
         )
     }
 
+    /**
+     * Resolves per-edge maximum scale factors for a bottom-left pivot.
+     * @param {{ minX: number, minY: number, maxX: number, maxY: number }} bounds
+     * @param {number} pivotX
+     * @param {number} pivotY
+     * @param {number} leftLimit
+     * @param {number} topLimit
+     * @param {number} rightLimit
+     * @param {number} bottomLimit
+     * @returns {number[]}
+     */
+    static #resolvePivotScaleLimits(
+        bounds,
+        pivotX,
+        pivotY,
+        leftLimit,
+        topLimit,
+        rightLimit,
+        bottomLimit
+    ) {
+        return [
+            SchematicContentLayout.#resolvePivotScaleLimit(
+                pivotX,
+                bounds.minX,
+                leftLimit,
+                'min'
+            ),
+            SchematicContentLayout.#resolvePivotScaleLimit(
+                pivotX,
+                bounds.maxX,
+                rightLimit,
+                'max'
+            ),
+            SchematicContentLayout.#resolvePivotScaleLimit(
+                pivotY,
+                bounds.minY,
+                topLimit,
+                'min'
+            ),
+            SchematicContentLayout.#resolvePivotScaleLimit(
+                pivotY,
+                bounds.maxY,
+                bottomLimit,
+                'max'
+            )
+        ]
+    }
+
+    /**
+     * Resolves one axis scale cap from an edge limit.
+     * @param {number} pivot
+     * @param {number} coordinate
+     * @param {number} limit
+     * @param {'min' | 'max'} mode
+     * @returns {number}
+     */
+    static #resolvePivotScaleLimit(pivot, coordinate, limit, mode) {
+        if (mode === 'min') {
+            return coordinate < pivot
+                ? (pivot - limit) / (pivot - coordinate)
+                : Infinity
+        }
+
+        return coordinate > pivot
+            ? (limit - pivot) / (coordinate - pivot)
+            : Infinity
+    }
+
     /**
      * Resolves the maximum sheet-wide scale implied by source and normalized
      * page sizes.
@@ -538,6 +623,10 @@ export class SchematicContentLayout {
         }
 
         for (const component of schematic?.components || []) {
+            if (!SchematicContentLayout.#isDrawableComponentAnchor(component)) {
+                continue
+            }
+
             coordinates.push([
                 component.x,
                 projectSchematicY(sheetHeight, component.y)
@@ -604,6 +693,25 @@ export class SchematicContentLayout {
         }
     }
 
+    /**
+     * Returns true when one component anchor can produce visible fallback
+     * markup and should therefore influence layout bounds.
+     * @param {{ x?: number, y?: number, designator?: string }} component
+     * @returns {boolean}
+     */
+    static #isDrawableComponentAnchor(component) {
+        if (!component) return false
+
+        const hasCoordinates =
+            Number.isFinite(component.x) &&
+            Number.isFinite(component.y) &&
+            (component.x !== 0 || component.y !== 0)
+        const hasDesignator =
+            Boolean(component.designator) && component.designator !== 'U?'
+
+        return hasCoordinates && hasDesignator
+    }
+
     /**
      * Projects authored rectangles or regions into rendered SVG bounds.
      * @param {{ x: number, y: number, width: number, height: number }[] | undefined} boxes

package/src/ui/SchematicShapeRenderer.mjs

@@ -231,18 +231,27 @@ export class SchematicShapeRenderer {
      * @returns {string}
      */
     static #buildSchematicStrokeStyleAttributes(lineWidth, lineStyle) {
-        if (Number(lineStyle || 0) !== 1) {
+        const resolvedLineStyle = Number(lineStyle || 0)
+        if (
+            resolvedLineStyle !== 1 &&
+            resolvedLineStyle !== 2 &&
+            resolvedLineStyle !== 3
+        )
             return ''
-        }
 
         const dashLength = Math.max(Number(lineWidth || 1) * 8, 8)
         const gapLength = Math.max(Number(lineWidth || 1) * 5, 5)
+        const dotLength = Math.max(Number(lineWidth || 1) * 1.5, 1.5)
+        const dashPattern =
+            resolvedLineStyle === 1
+                ? [dashLength, gapLength]
+                : resolvedLineStyle === 2
+                  ? [dotLength, gapLength]
+                  : [dashLength, gapLength, dotLength, gapLength]
 
         return (
             ' stroke-dasharray="' +
-            formatNumber(dashLength) +
-            ' ' +
-            formatNumber(gapLength) +
+            dashPattern.map((part) => formatNumber(part)).join(' ') +
             '" stroke-linecap="round"'
         )
     }

package/src/ui/SchematicSvgRenderer.mjs

@@ -511,16 +511,22 @@ export class SchematicSvgRenderer {
      * @returns {string}
      */
     static #buildSchematicLineStyleAttributes(line) {
-        if (Number(line.lineStyle || 0) !== 1) {
-            return ''
-        }
+        const lineStyle = Number(line.lineStyle || 0)
+        if (lineStyle !== 1 && lineStyle !== 2 && lineStyle !== 3) return ''
+
         const dashLength = Math.max(Number(line.width || 1) * 8, 8)
         const gapLength = Math.max(Number(line.width || 1) * 5, 5)
+        const dotLength = Math.max(Number(line.width || 1) * 1.5, 1.5)
+        const dashPattern =
+            lineStyle === 1
+                ? [dashLength, gapLength]
+                : lineStyle === 2
+                  ? [dotLength, gapLength]
+                  : [dashLength, gapLength, dotLength, gapLength]
+
         return (
             ' stroke-dasharray="' +
-            formatNumber(dashLength) +
-            ' ' +
-            formatNumber(gapLength) +
+            dashPattern.map((part) => formatNumber(part)).join(' ') +
             '" stroke-linecap="round"'
         )
     }