altium-toolkit 0.1.23 → 1.0.2

package/src/core/netlist-query/QueryNetlistBuilder.mjs

@@ -0,0 +1,180 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ComponentGrouping } from './ComponentGrouping.mjs'
+
+/**
+ * Builds compact query netlists from normalized toolkit document models.
+ */
+export class QueryNetlistBuilder {
+    /**
+     * Builds the query netlist for one document model.
+     * @param {object} documentModel Document model.
+     * @returns {{ nets: object, components: object }}
+     */
+    static build(documentModel) {
+        const components =
+            QueryNetlistBuilder.#buildComponentDetails(documentModel)
+        const nets = {}
+
+        for (const net of documentModel?.schematic?.nets || []) {
+            const netName = String(net?.name || '').trim()
+            if (!netName) continue
+
+            for (const pin of net.pins || []) {
+                const refdes = QueryNetlistBuilder.#resolvePinRefdes(
+                    pin,
+                    components
+                )
+                const pinNumber = QueryNetlistBuilder.#resolvePinNumber(pin)
+                if (!refdes || !pinNumber) continue
+
+                nets[netName] ||= {}
+                const existing = nets[netName][refdes]
+                nets[netName][refdes] = QueryNetlistBuilder.#appendPin(
+                    existing,
+                    pinNumber
+                )
+                components[refdes] ||= { pins: {} }
+                components[refdes].pins[pinNumber] =
+                    QueryNetlistBuilder.#pinEntry(pinNumber, pin?.name, netName)
+            }
+        }
+
+        return { nets, components }
+    }
+
+    /**
+     * Builds component metadata from schematic, PCB, and BOM records.
+     * @param {object} documentModel Document model.
+     * @returns {object}
+     */
+    static #buildComponentDetails(documentModel) {
+        const components = {}
+
+        for (const component of documentModel?.schematic?.components || []) {
+            const refdes = String(component?.designator || '').trim()
+            if (!refdes) continue
+            components[refdes] = {
+                ...components[refdes],
+                value: component.value || components[refdes]?.value,
+                description:
+                    component.description || components[refdes]?.description,
+                comment: component.comment || components[refdes]?.comment,
+                ownerIndex:
+                    component.ownerIndex || components[refdes]?.ownerIndex,
+                dns:
+                    component.dns ||
+                    component.excludeFromBom ||
+                    components[refdes]?.dns,
+                excludeFromBom:
+                    component.excludeFromBom ||
+                    components[refdes]?.excludeFromBom,
+                pins: components[refdes]?.pins || {}
+            }
+        }
+
+        for (const component of documentModel?.pcb?.components || []) {
+            const refdes = String(component?.designator || '').trim()
+            if (!refdes) continue
+            components[refdes] = {
+                ...components[refdes],
+                description:
+                    component.description ||
+                    component.pattern ||
+                    components[refdes]?.description,
+                value: component.value || components[refdes]?.value,
+                comment: component.comment || components[refdes]?.comment,
+                pins: components[refdes]?.pins || {}
+            }
+        }
+
+        for (const row of documentModel?.bom || []) {
+            for (const refdes of row.designators || []) {
+                const normalizedRefdes = String(refdes || '').trim()
+                if (!normalizedRefdes) continue
+                components[normalizedRefdes] = {
+                    ...components[normalizedRefdes],
+                    mpn: row.pattern || components[normalizedRefdes]?.mpn,
+                    description:
+                        row.source || components[normalizedRefdes]?.description,
+                    value: row.value || components[normalizedRefdes]?.value,
+                    pins: components[normalizedRefdes]?.pins || {}
+                }
+            }
+        }
+
+        return components
+    }
+
+    /**
+     * Resolves a pin's owning reference designator.
+     * @param {object} pin Net pin.
+     * @param {object} components Component details.
+     * @returns {string}
+     */
+    static #resolvePinRefdes(pin, components) {
+        const direct = String(
+            pin?.refdes ||
+                pin?.componentRefdes ||
+                pin?.componentDesignator ||
+                pin?.ownerDesignator ||
+                ''
+        ).trim()
+        if (direct) return direct
+
+        const ownerIndex = String(pin?.ownerIndex || '').trim()
+        if (!ownerIndex) return ''
+
+        return (
+            Object.entries(components).find(([, component]) => {
+                return String(component.ownerIndex || '') === ownerIndex
+            })?.[0] || ''
+        )
+    }
+
+    /**
+     * Resolves a pin number.
+     * @param {object} pin Net pin.
+     * @returns {string}
+     */
+    static #resolvePinNumber(pin) {
+        return String(
+            pin?.pinNumber || pin?.number || pin?.designator || ''
+        ).trim()
+    }
+
+    /**
+     * Appends a pin to a compact net connection value.
+     * @param {string | string[] | undefined} existing Existing pins.
+     * @param {string} pinNumber Pin number.
+     * @returns {string | string[]}
+     */
+    static #appendPin(existing, pinNumber) {
+        if (!existing) return pinNumber
+        const pins = Array.isArray(existing) ? existing : [existing]
+        if (!pins.includes(pinNumber)) {
+            pins.push(pinNumber)
+        }
+        return ComponentGrouping.compactArray(
+            pins.sort(ComponentGrouping.naturalSort)
+        )
+    }
+
+    /**
+     * Builds a compact pin entry.
+     * @param {string} pinNumber Pin number.
+     * @param {string | undefined} pinName Pin name.
+     * @param {string} netName Net name.
+     * @returns {string | { name: string, net: string }}
+     */
+    static #pinEntry(pinNumber, pinName, netName) {
+        const normalizedName = String(pinName || '').trim()
+        if (normalizedName && normalizedName !== pinNumber) {
+            return { name: normalizedName, net: netName }
+        }
+
+        return netName
+    }
+}

package/src/core/netlist-query/RegexPattern.mjs

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Regex helpers for netlist query tools.
+ */
+export class RegexPattern {
+    /**
+     * Parses a user regex pattern into a JavaScript RegExp.
+     * @param {string} pattern User-provided pattern.
+     * @param {string} [flags] RegExp flags.
+     * @returns {{ regex: RegExp } | { error: string }}
+     */
+    static parse(pattern, flags = 'i') {
+        const normalizedPattern = RegexPattern.#normalizeInlineFlags(pattern)
+        const normalizedFlags = RegexPattern.#normalizeFlags(
+            flags,
+            normalizedPattern.forceIgnoreCase
+        )
+
+        try {
+            return {
+                regex: new RegExp(normalizedPattern.pattern, normalizedFlags)
+            }
+        } catch (error) {
+            return {
+                error:
+                    'Invalid regex pattern ' +
+                    JSON.stringify(String(pattern || '')) +
+                    ': ' +
+                    (error instanceof Error ? error.message : String(error))
+            }
+        }
+    }
+
+    /**
+     * Returns true when a pattern matches every candidate value.
+     * @param {string} pattern User-provided pattern.
+     * @param {string[]} candidates Candidate values.
+     * @returns {boolean}
+     */
+    static rejectsBroadMatch(pattern, candidates) {
+        const parsed = RegexPattern.parse(pattern)
+        if (parsed.error || !Array.isArray(candidates) || !candidates.length) {
+            return false
+        }
+
+        return candidates.every((candidate) => {
+            parsed.regex.lastIndex = 0
+            return parsed.regex.test(String(candidate || ''))
+        })
+    }
+
+    /**
+     * Normalizes a leading `(?i)` flag into JavaScript RegExp flags.
+     * @param {string} pattern User-provided pattern.
+     * @returns {{ pattern: string, forceIgnoreCase: boolean }}
+     */
+    static #normalizeInlineFlags(pattern) {
+        const source = String(pattern || '')
+        if (source.startsWith('(?i)')) {
+            return {
+                pattern: source.slice(4),
+                forceIgnoreCase: true
+            }
+        }
+
+        return {
+            pattern: source,
+            forceIgnoreCase: false
+        }
+    }
+
+    /**
+     * Adds the ignore-case flag when requested.
+     * @param {string} flags RegExp flags.
+     * @param {boolean} forceIgnoreCase Whether to force `i`.
+     * @returns {string}
+     */
+    static #normalizeFlags(flags, forceIgnoreCase) {
+        const uniqueFlags = new Set(String(flags || '').split(''))
+        if (forceIgnoreCase) {
+            uniqueFlags.add('i')
+        }
+
+        return [...uniqueFlags].join('')
+    }
+}

package/src/netlist-query.mjs

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export { RegexPattern } from './core/netlist-query/RegexPattern.mjs'
+export {
+    ComponentGrouping,
+    MPN_MISSING_NOTE
+} from './core/netlist-query/ComponentGrouping.mjs'
+export { CircuitTraversal } from './core/netlist-query/CircuitTraversal.mjs'
+export { QueryNetlistBuilder } from './core/netlist-query/QueryNetlistBuilder.mjs'
+export { LoadedDesignNetlistService } from './core/netlist-query/LoadedDesignNetlistService.mjs'

package/src/parser.mjs

@@ -11,6 +11,8 @@ export { AltiumLayoutParser } from './core/altium/AltiumLayoutParser.mjs'
 export { AsciiRecordParser } from './core/altium/AsciiRecordParser.mjs'
 export { ParserUtils } from './core/altium/ParserUtils.mjs'
 export { NormalizedModelSchema } from './core/altium/NormalizedModelSchema.mjs'
+export { CircuitJsonModelSchema } from './core/circuit-json/CircuitJsonModelSchema.mjs'
+export { CircuitJsonModelAdapter } from './core/circuit-json/CircuitJsonModelAdapter.mjs'
 export { PcbBinaryPrimitiveParser } from './core/altium/PcbBinaryPrimitiveParser.mjs'
 export { PcbBoardRegionSemanticsParser } from './core/altium/PcbBoardRegionSemanticsParser.mjs'
 export { PcbComponentPrimitiveIndexer } from './core/altium/PcbComponentPrimitiveIndexer.mjs'

package/src/styles/altium-renderers.css

@@ -141,6 +141,7 @@
     --pcb-via-hole-fill: #0f746c;
     --pcb-footprint-fill: rgba(247, 230, 117, 0.14);
     --pcb-footprint-track-color: rgba(237, 172, 36, 1);
+    --pcb-text-knockout-fill: rgba(248, 246, 239, 0.96);
     --pcb-component-top-fill: rgba(244, 219, 198, 0.92);
     --pcb-component-bottom-fill: rgba(15, 116, 108, 0.84);
     --pcb-component-stroke: rgba(110, 64, 38, 0.28);
@@ -178,6 +179,8 @@
     fill: var(--pcb-board-fill);
     stroke: var(--pcb-board-stroke);
     stroke-width: 18;
+    stroke-linecap: round;
+    stroke-linejoin: round;
 }
 
 .board-outline--stroke {
@@ -252,7 +255,7 @@
 }
 
 .pcb-footprint-region {
-    fill: var(--pcb-footprint-track-color);
+    fill: var(--pcb-footprint-region-fill, var(--pcb-footprint-track-color));
 }
 
 .pcb-footprint-track,
@@ -278,6 +281,14 @@
     pointer-events: none;
 }
 
+.pcb-text__knockout-fill {
+    fill: var(--pcb-text-knockout-fill);
+}
+
+.pcb-text__knockout-glyphs {
+    fill: #000;
+}
+
 .bom-panel {
     display: grid;
     gap: 1rem;

package/src/ui/PcbNativeTextKnockoutDetector.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Detects native overlay artwork that already contains text knockout holes.
+ */
+export class PcbNativeTextKnockoutDetector {
+    static #DENSE_OVERLAY_MIN_REGION_AREA_RATIO = 0.2
+    static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
+
+    /**
+     * Returns true when side-resolved overlay primitives carry native text
+     * knockouts, so source inverted TrueType labels would duplicate artwork.
+     * @param {{ fills?: object[], regions?: object[], tracks?: object[], arcs?: object[] }} primitives Side-resolved overlay primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static hasNativeTextKnockouts(primitives, board) {
+        const fills = [
+            ...(Array.isArray(primitives?.fills) ? primitives.fills : []),
+            ...(Array.isArray(primitives?.regions) ? primitives.regions : [])
+        ]
+
+        return (
+            PcbNativeTextKnockoutDetector.#isDenseOverlayArtwork(
+                {
+                    fills,
+                    tracks: primitives?.tracks,
+                    arcs: primitives?.arcs
+                },
+                board
+            ) &&
+            fills.some(
+                (fill) => Array.isArray(fill?.holes) && fill.holes.length > 0
+            )
+        )
+    }
+
+    /**
+     * Detects dense overlay artwork from structural density.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[] }} side Side primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static #isDenseOverlayArtwork(side, board) {
+        const strokeCount =
+            (Array.isArray(side?.tracks) ? side.tracks.length : 0) +
+            (Array.isArray(side?.arcs) ? side.arcs.length : 0)
+
+        return (
+            strokeCount >=
+                PcbNativeTextKnockoutDetector.#DENSE_OVERLAY_MIN_TRACK_COUNT &&
+            PcbNativeTextKnockoutDetector.#maxFillAreaRatio(
+                side?.fills,
+                board
+            ) >=
+                PcbNativeTextKnockoutDetector
+                    .#DENSE_OVERLAY_MIN_REGION_AREA_RATIO
+        )
+    }
+
+    /**
+     * Resolves the largest fill-to-board bounding-box area ratio.
+     * @param {object[] | undefined} fills Fill primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {number}
+     */
+    static #maxFillAreaRatio(fills, board) {
+        const boardArea =
+            Math.max(Number(board?.widthMil || 0), 0) *
+            Math.max(Number(board?.heightMil || 0), 0)
+        if (!boardArea) {
+            return 0
+        }
+
+        return (Array.isArray(fills) ? fills : []).reduce((maxRatio, fill) => {
+            const bounds =
+                PcbNativeTextKnockoutDetector.#resolveFillBounds(fill)
+            if (!bounds) {
+                return maxRatio
+            }
+
+            const fillArea =
+                Math.max(bounds.maxX - bounds.minX, 0) *
+                Math.max(bounds.maxY - bounds.minY, 0)
+
+            return Math.max(maxRatio, fillArea / boardArea)
+        }, 0)
+    }
+
+    /**
+     * Resolves rough authored bounds for one rectangular or polygon fill.
+     * @param {{ x1?: number, y1?: number, x2?: number, y2?: number, points?: { x?: number, y?: number }[] }} fill Fill primitive.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static #resolveFillBounds(fill) {
+        const points = Array.isArray(fill?.points)
+            ? fill.points
+                  .map((point) => ({
+                      x: Number(point?.x),
+                      y: Number(point?.y)
+                  }))
+                  .filter(
+                      (point) =>
+                          Number.isFinite(point.x) && Number.isFinite(point.y)
+                  )
+            : [
+                  { x: Number(fill?.x1), y: Number(fill?.y1) },
+                  { x: Number(fill?.x2), y: Number(fill?.y2) }
+              ].filter(
+                  (point) =>
+                      Number.isFinite(point.x) && Number.isFinite(point.y)
+              )
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+
+        return {
+            minX: Math.min(...xs),
+            minY: Math.min(...ys),
+            maxX: Math.max(...xs),
+            maxY: Math.max(...ys)
+        }
+    }
+}