altium-toolkit 1.0.2 → 1.0.8

package/src/ui/PcbInteractionLayerModel.mjs

@@ -0,0 +1,99 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbInteractionIndex } from './PcbInteractionIndex.mjs'
+
+const VIRTUAL_LAYER_DEFINITIONS = [
+    { key: 'tracks', label: 'Tracks' },
+    { key: 'vias', label: 'Vias' },
+    { key: 'pads', label: 'Pads' },
+    { key: 'holes', label: 'Holes' },
+    { key: 'zones', label: 'Zones' },
+    { key: 'footprint-text', label: 'Footprint text' }
+]
+
+/**
+ * Builds a PCB layer summary with physical layers and virtual controls.
+ */
+export class PcbInteractionLayerModel {
+    /**
+     * Resolves physical and virtual interaction layers.
+     * @param {object} documentModel Toolkit document model.
+     * @returns {{ physicalLayers: object[], virtualLayers: object[] }}
+     */
+    static resolve(documentModel) {
+        const pcb = documentModel?.pcb || {}
+        const physicalLayers = PcbInteractionLayerModel.#physicalLayers(pcb)
+        const items = PcbInteractionIndex.build(documentModel)
+        const layersByObject = PcbInteractionLayerModel.#layersByObject(items)
+
+        return {
+            physicalLayers,
+            virtualLayers: VIRTUAL_LAYER_DEFINITIONS.map((definition) => ({
+                ...definition,
+                physicalLayerKeys: Array.from(
+                    layersByObject.get(definition.key) || []
+                )
+            }))
+        }
+    }
+
+    /**
+     * Resolves physical layer rows from board and primitive layer metadata.
+     * @param {object} pcb PCB model.
+     * @returns {object[]}
+     */
+    static #physicalLayers(pcb) {
+        const seen = new Set()
+        const layers = []
+        const sources = [
+            ...(Array.isArray(pcb?.layers) ? pcb.layers : []),
+            ...(Array.isArray(pcb?.primitiveLayers) ? pcb.primitiveLayers : [])
+        ]
+
+        for (const layer of sources) {
+            const key = String(layer?.name || layer?.layer || '').trim()
+            if (!key || seen.has(key)) continue
+            seen.add(key)
+            layers.push({
+                key,
+                label: key,
+                layerId: Number.isFinite(Number(layer?.layerId))
+                    ? Number(layer.layerId)
+                    : null
+            })
+        }
+
+        return layers
+    }
+
+    /**
+     * Collects referenced physical layer keys by virtual object key.
+     * @param {object[]} items Interaction items.
+     * @returns {Map<string, Set<string>>}
+     */
+    static #layersByObject(items) {
+        const layersByObject = new Map()
+
+        for (const item of items) {
+            if (!layersByObject.has(item.objectKey)) {
+                layersByObject.set(item.objectKey, new Set())
+            }
+            const layerSet = layersByObject.get(item.objectKey)
+            for (const layerKey of item.layerKeys || []) {
+                layerSet.add(layerKey)
+            }
+            if (item.type === 'pad' || item.type === 'via') {
+                if (!layersByObject.has('holes')) {
+                    layersByObject.set('holes', new Set())
+                }
+                for (const layerKey of item.layerKeys || []) {
+                    layersByObject.get('holes').add(layerKey)
+                }
+            }
+        }
+
+        return layersByObject
+    }
+}

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -46,17 +46,82 @@ export class PcbScene3dBoardOutlineRefiner {
             return sceneDescription
         }
 
+        const refinedBoard = {
+            ...board,
+            minX: candidate.minX,
+            minY: candidate.minY,
+            widthMil: candidate.widthMil,
+            heightMil: candidate.heightMil,
+            centerX: candidate.minX + candidate.widthMil / 2,
+            centerY: candidate.minY + candidate.heightMil / 2,
+            segments: candidate.segments
+        }
+
         return {
             ...sceneDescription,
-            board: {
-                ...board,
-                minX: candidate.minX,
-                minY: candidate.minY,
-                widthMil: candidate.widthMil,
-                heightMil: candidate.heightMil,
-                centerX: candidate.minX + candidate.widthMil / 2,
-                centerY: candidate.minY + candidate.heightMil / 2,
-                segments: candidate.segments
+            board: refinedBoard,
+            components: PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                sceneDescription?.components,
+                board,
+                refinedBoard
+            ),
+            externalPlacements:
+                PcbScene3dBoardOutlineRefiner.#realignLocalPlacements(
+                    sceneDescription?.externalPlacements,
+                    board,
+                    refinedBoard
+                )
+        }
+    }
+
+    /**
+     * Realigns precomputed local placements to a refined board center.
+     * @param {object[] | undefined} placements Scene placements.
+     * @param {{ centerX?: number, centerY?: number }} previousBoard Previous board.
+     * @param {{ centerX?: number, centerY?: number }} refinedBoard Refined board.
+     * @returns {object[] | undefined}
+     */
+    static #realignLocalPlacements(placements, previousBoard, refinedBoard) {
+        if (!Array.isArray(placements)) {
+            return placements
+        }
+
+        const deltaX =
+            Number(previousBoard?.centerX || 0) -
+            Number(refinedBoard?.centerX || 0)
+        const deltaY =
+            Number(previousBoard?.centerY || 0) -
+            Number(refinedBoard?.centerY || 0)
+
+        if (!deltaX && !deltaY) {
+            return placements
+        }
+
+        return placements.map((placement) =>
+            PcbScene3dBoardOutlineRefiner.#realignLocalPlacement(
+                placement,
+                deltaX,
+                deltaY
+            )
+        )
+    }
+
+    /**
+     * Applies one local origin delta to a scene placement.
+     * @param {object} placement Scene placement.
+     * @param {number} deltaX Local X delta.
+     * @param {number} deltaY Local Y delta.
+     * @returns {object}
+     */
+    static #realignLocalPlacement(placement, deltaX, deltaY) {
+        const positionMil = placement?.positionMil || {}
+
+        return {
+            ...placement,
+            positionMil: {
+                ...positionMil,
+                x: Number(positionMil.x || 0) + deltaX,
+                y: Number(positionMil.y || 0) + deltaY
             }
         }
     }

package/src/ui/PcbScene3dBuilder.mjs

@@ -19,6 +19,9 @@ export class PcbScene3dBuilder {
     static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
     static #DENSE_OVERLAY_KNOCKOUT_COLOR = 0x2f6a2c
     static #PRECISE_BODY_MATCH_TOLERANCE_MIL = 5
+    static #UNMATCHED_BODY_OVERHANG_RATIO = 0.25
+    static #UNMATCHED_BODY_MIN_OVERHANG_MIL = 150
+    static #UNMATCHED_BODY_MAX_OVERHANG_MIL = 600
     static #TRUETYPE_TEXT_WIDTH_RATIO = 0.55
 
     /**
@@ -1159,16 +1162,41 @@ export class PcbScene3dBuilder {
     static #isBodyPositionNearBoard(componentBody, board) {
         const bodyX = Number(componentBody?.positionMil?.x || 0)
         const bodyY = Number(componentBody?.positionMil?.y || 0)
-        const minX = Number(board?.minX || 0) - 600
-        const minY = Number(board?.minY || 0) - 600
+        const xOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.widthMil
+        )
+        const yOverhang = PcbScene3dBuilder.#resolveUnmatchedBodyOverhang(
+            board?.heightMil
+        )
+        const minX = Number(board?.minX || 0) - xOverhang
+        const minY = Number(board?.minY || 0) - yOverhang
         const maxX =
-            Number(board?.minX || 0) + Number(board?.widthMil || 0) + 600
+            Number(board?.minX || 0) + Number(board?.widthMil || 0) + xOverhang
         const maxY =
-            Number(board?.minY || 0) + Number(board?.heightMil || 0) + 600
+            Number(board?.minY || 0) + Number(board?.heightMil || 0) + yOverhang
 
         return bodyX >= minX && bodyX <= maxX && bodyY >= minY && bodyY <= maxY
     }
 
+    /**
+     * Resolves a proportional unresolved-body margin for one board axis.
+     * @param {number | string | undefined} spanMil Board axis span.
+     * @returns {number}
+     */
+    static #resolveUnmatchedBodyOverhang(spanMil) {
+        const proportional =
+            Math.max(Number(spanMil || 0), 0) *
+            PcbScene3dBuilder.#UNMATCHED_BODY_OVERHANG_RATIO
+
+        return Math.min(
+            PcbScene3dBuilder.#UNMATCHED_BODY_MAX_OVERHANG_MIL,
+            Math.max(
+                proportional,
+                PcbScene3dBuilder.#UNMATCHED_BODY_MIN_OVERHANG_MIL
+            )
+        )
+    }
+
     /**
      * Normalizes one angle into the range [0, 360).
      * @param {number} angle

package/src/ui/PcbSvgRenderer.mjs

@@ -341,7 +341,7 @@ export class PcbSvgRenderer {
             '"><path d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" /></clipPath></defs>' +
-            '<path class="board-outline" d="' +
+            '<path class="board-outline pcb-layer pcb-layer--edge-cuts" data-layer-name="Edge.Cuts" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
             '<g class="pcb-copper-layers" clip-path="url(#' +
@@ -380,7 +380,7 @@ export class PcbSvgRenderer {
             '>' +
             textMarkup +
             '</g>' +
-            '<path class="board-outline board-outline--stroke" d="' +
+            '<path class="board-outline board-outline--stroke pcb-layer pcb-layer--edge-cuts" data-layer-name="Edge.Cuts" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
             '</svg></div></section>'

package/src/ui/PcbTextPrimitiveRenderer.mjs

@@ -132,7 +132,7 @@ export class PcbTextPrimitiveRenderer {
             metrics.lineHeight
         )
         const rectX = -layout.anchorX
-        const rectY = layout.anchorY - layout.height
+        const rectY = -layout.anchorY
         const cornerRadius = Math.min(
             padding,
             layout.width / 2,
@@ -360,7 +360,21 @@ export class PcbTextPrimitiveRenderer {
             return null
         }
 
-        context.font = PcbTextPrimitiveRenderer.#buildCanvasFont(text, fontSize)
+        const canvasFont = PcbTextPrimitiveRenderer.#buildCanvasFont(
+            text,
+            fontSize
+        )
+        if (
+            !PcbTextPrimitiveRenderer.#canMeasureCanvasFont(
+                text,
+                canvasFont,
+                fontSize
+            )
+        ) {
+            return null
+        }
+
+        context.font = canvasFont
 
         const measured = lines.map((line) => context.measureText(line || ' '))
         const ascent = PcbTextPrimitiveRenderer.#resolveMeasuredExtent(
@@ -388,6 +402,29 @@ export class PcbTextPrimitiveRenderer {
         }
     }
 
+    /**
+     * Checks whether canvas text metrics can be trusted for the requested
+     * imported font.
+     * @param {{ fontMetrics?: { averageAdvanceWidth?: number, unitsPerEm?: number } }} text Text record.
+     * @param {string} canvasFont Full canvas font shorthand.
+     * @param {number} fontSize Text font size.
+     * @returns {boolean}
+     */
+    static #canMeasureCanvasFont(text, canvasFont, fontSize) {
+        const fonts = globalThis.document?.fonts
+        if (typeof fonts?.check === 'function') {
+            return fonts.check(
+                PcbTextPrimitiveRenderer.#buildPrimaryCanvasFont(text, fontSize)
+            )
+        }
+
+        if (PcbTextPrimitiveRenderer.#fontMetricsAverageWidthRatio(text)) {
+            return false
+        }
+
+        return Boolean(canvasFont)
+    }
+
     /**
      * Resolves a measured text extent with a stable fallback.
      * @param {TextMetrics[]} measured Browser text metrics.
@@ -420,6 +457,25 @@ export class PcbTextPrimitiveRenderer {
         return `${style} ${weight} ${fontSize}px ${family}`
     }
 
+    /**
+     * Builds a single-family font shorthand for readiness checks.
+     * @param {{ fontFamily?: string, fontName?: string, isBold?: boolean, fontWeight?: number, isItalic?: boolean }} text Text record.
+     * @param {number} fontSize Text font size.
+     * @returns {string}
+     */
+    static #buildPrimaryCanvasFont(text, fontSize) {
+        const weight =
+            text?.isBold || Number(text?.fontWeight) >= 600 ? '700' : '400'
+        const style = text?.isItalic ? 'italic' : 'normal'
+        const family = PcbTextPrimitiveRenderer.#quoteFontFamily(
+            PcbTextPrimitiveRenderer.#cleanFontFamily(
+                text?.fontFamily || text?.fontName
+            )
+        )
+
+        return `${style} ${weight} ${fontSize}px ${family}`
+    }
+
     /**
      * Builds a browser font-family stack matching the 3D TrueType path.
      * @param {unknown} family Font family value.

package/src/ui/SchematicContentLayout.mjs

@@ -195,7 +195,7 @@ export class SchematicContentLayout {
             ' ' +
             formatNumber(targetMinY) +
             ') scale(' +
-            formatNumber(scale) +
+            SchematicContentLayout.#formatScale(scale) +
             ') translate(' +
             formatNumber(-bounds.minX) +
             ' ' +
@@ -252,20 +252,28 @@ export class SchematicContentLayout {
             return ''
         }
 
-        const pivotX = margin
-        const pivotY = height - margin
         const topLimit = margin + contentPadding * 0.2
         const bottomLimit = height - margin - footerReserve
         const rightLimit = width - margin
+        const usedWidth = bounds.maxX - bounds.minX
+        const usedHeight = bounds.maxY - bounds.minY
+
+        if (usedWidth <= 0 || usedHeight <= 0) {
+            return ''
+        }
+
         const scale = Math.min(
             targetScale,
-            ...SchematicContentLayout.#resolvePivotScaleLimits(
-                bounds,
-                pivotX,
-                pivotY,
+            SchematicContentLayout.#resolveContentScaleLimit(
+                bounds.minX,
+                bounds.maxX,
                 margin,
+                rightLimit
+            ),
+            SchematicContentLayout.#resolveContentScaleLimit(
+                bounds.minY,
+                bounds.maxY,
                 topLimit,
-                rightLimit,
                 bottomLimit
             )
         )
@@ -274,10 +282,18 @@ export class SchematicContentLayout {
             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 targetMinX =
+            SchematicContentLayout.#resolveCenteredContentTargetMinX(
+                bounds,
+                scale,
+                margin,
+                rightLimit
+            )
+        const projectedMinX = targetMinX
+        const projectedMaxX = targetMinX + usedWidth * scale
+        const targetMinY = bottomLimit - usedHeight * scale
+        const projectedMinY = targetMinY
+        const projectedMaxY = bottomLimit
 
         if (
             projectedMinX < margin - 0.01 ||
@@ -290,19 +306,73 @@ export class SchematicContentLayout {
 
         return (
             ' transform="translate(' +
-            formatNumber(pivotX) +
+            formatNumber(targetMinX) +
             ' ' +
-            formatNumber(pivotY) +
+            formatNumber(targetMinY) +
             ') scale(' +
-            formatNumber(scale) +
+            SchematicContentLayout.#formatScale(scale) +
             ') translate(' +
-            formatNumber(-pivotX) +
+            formatNumber(-bounds.minX) +
             ' ' +
-            formatNumber(-pivotY) +
+            formatNumber(-bounds.minY) +
             ')"'
         )
     }
 
+    /**
+     * Resolves one scale cap that keeps a horizontally centered content
+     * envelope inside the sheet frame.
+     * @param {number} minCoordinate
+     * @param {number} maxCoordinate
+     * @param {number} minLimit
+     * @param {number} maxLimit
+     * @returns {number}
+     */
+    static #resolveContentScaleLimit(
+        minCoordinate,
+        maxCoordinate,
+        minLimit,
+        maxLimit
+    ) {
+        const usedWidth = maxCoordinate - minCoordinate
+        const availableWidth = maxLimit - minLimit
+
+        return usedWidth > 0 && availableWidth > 0
+            ? availableWidth / usedWidth
+            : Infinity
+    }
+
+    /**
+     * Formats SVG transform scales with enough precision to avoid visible
+     * placement drift on large schematic sheets.
+     * @param {number} value
+     * @returns {string}
+     */
+    static #formatScale(value) {
+        return Number(value).toFixed(4).replace(/0+$/, '').replace(/\.$/, '')
+    }
+
+    /**
+     * Resolves the target SVG x-coordinate for a scaled content envelope.
+     * @param {{ minX: number, maxX: number }} bounds
+     * @param {number} scale
+     * @param {number} leftLimit
+     * @param {number} rightLimit
+     * @returns {number}
+     */
+    static #resolveCenteredContentTargetMinX(
+        bounds,
+        scale,
+        leftLimit,
+        rightLimit
+    ) {
+        const scaledWidth = (bounds.maxX - bounds.minX) * scale
+        const availableWidth = rightLimit - leftLimit
+        const remainingWidth = Math.max(availableWidth - scaledWidth, 0)
+
+        return leftLimit + remainingWidth / 2
+    }
+
     /**
      * Resolves per-edge maximum scale factors for a bottom-left pivot.
      * @param {{ minX: number, minY: number, maxX: number, maxY: number }} bounds
@@ -436,11 +506,43 @@ export class SchematicContentLayout {
         const heightSlackRatio =
             (matchingSheet.height - requiredHeight) / requiredHeight
 
-        return widthSlackRatio <= RELAXED_STANDARD_PAGE_MAX_SLACK_RATIO &&
-            heightSlackRatio <= RELAXED_STANDARD_PAGE_MAX_SLACK_RATIO &&
-            matchingSheet.width < width
-            ? matchingSheet
-            : null
+        if (
+            widthSlackRatio > RELAXED_STANDARD_PAGE_MAX_SLACK_RATIO ||
+            heightSlackRatio > RELAXED_STANDARD_PAGE_MAX_SLACK_RATIO ||
+            matchingSheet.width >= width
+        ) {
+            return null
+        }
+
+        return {
+            ...matchingSheet,
+            width: SchematicContentLayout.#resolveTightVirtualDimension(
+                requiredWidth,
+                matchingSheet.width,
+                margin
+            )
+        }
+    }
+
+    /**
+     * Drops near-zero standard-page rounding slack from the scale axis so
+     * custom sheets that almost fill a standard source size do not render with
+     * a visible artificial gutter.
+     * @param {number} requiredDimension
+     * @param {number} candidateDimension
+     * @param {number} margin
+     * @returns {number}
+     */
+    static #resolveTightVirtualDimension(
+        requiredDimension,
+        candidateDimension,
+        margin
+    ) {
+        const slack = candidateDimension - requiredDimension
+
+        return slack > 0 && slack <= margin
+            ? requiredDimension
+            : candidateDimension
     }
 
     /**

package/src/ui/SchematicJunctionRenderer.mjs

@@ -18,6 +18,7 @@ export class SchematicJunctionRenderer {
      * @param {{ x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down' }[]} [ports]
      * @param {{ x: number, y: number, style?: number, powerPortDirection?: 'up' | 'down' | 'left' | 'right' }[]} [powerPorts]
      * @param {number} sheetHeight
+     * @param {{ x: number, y: number }[]} [authoredJunctions]
      * @returns {string}
      */
     static buildMarkup(
@@ -25,13 +26,15 @@ export class SchematicJunctionRenderer {
         crosses,
         ports = [],
         powerPorts = [],
-        sheetHeight
+        sheetHeight,
+        authoredJunctions = []
     ) {
         return SchematicJunctionRenderer.#resolveJunctions(
             lines,
             crosses,
             ports,
-            powerPorts
+            powerPorts,
+            authoredJunctions
         )
             .map(
                 (junction) =>
@@ -57,9 +60,16 @@ export class SchematicJunctionRenderer {
      * @param {{ x: number, y: number }[]} crosses
      * @param {{ x: number, y: number, width: number, direction?: 'left' | 'right' | 'up' | 'down' }[]} ports
      * @param {{ x: number, y: number, style?: number, powerPortDirection?: 'up' | 'down' | 'left' | 'right' }[]} powerPorts
+     * @param {{ x: number, y: number }[]} authoredJunctions
      * @returns {{ x: number, y: number, color: string }[]}
      */
-    static #resolveJunctions(lines, crosses, ports, powerPorts) {
+    static #resolveJunctions(
+        lines,
+        crosses,
+        ports,
+        powerPorts,
+        authoredJunctions
+    ) {
         const wireLines = lines.filter((line) =>
             SchematicJunctionRenderer.#isElectricalWireLine(line)
         )
@@ -69,6 +79,11 @@ export class SchematicJunctionRenderer {
         const visiblePowerPorts = powerPorts.filter((powerPort) =>
             SchematicJunctionRenderer.#isDrawablePowerPort(powerPort)
         )
+        const authoredJunctionKeys = new Set(
+            authoredJunctions.map((junction) =>
+                SchematicJunctionRenderer.#pointKey(junction)
+            )
+        )
 
         return SchematicJunctionRenderer.#collectCandidatePoints(
             wireLines,
@@ -77,6 +92,9 @@ export class SchematicJunctionRenderer {
         )
             .filter(
                 (point) =>
+                    !authoredJunctionKeys.has(
+                        SchematicJunctionRenderer.#pointKey(point)
+                    ) &&
                     !SchematicJunctionRenderer.#hasNearbyCross(point, crosses)
             )
             .flatMap((point) => {