altium-toolkit 1.1.40 → 1.1.41

package/package.json

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

package/src/core/altium/AltiumLayoutParser.mjs

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { ParserUtils } from './ParserUtils.mjs'
+import { PcbLayerIdCodec } from './PcbLayerIdCodec.mjs'
 import { SchematicTextParser } from './SchematicTextParser.mjs'
 
 const { getField, parseNumericField } = ParserUtils
@@ -114,14 +115,18 @@ export class AltiumLayoutParser {
             if (!match) continue
 
             const index = Number.parseInt(match[1], 10)
+            const layerId = parseNumericField(
+                fields,
+                'V9_STACK_LAYER' + index + '_LAYERID'
+            )
+            const legacyLayerId =
+                PcbLayerIdCodec.legacyLayerIdFromV7SaveId(layerId) ?? undefined
             layers.push(
                 AltiumLayoutParser.#stripUndefined({
                     index,
                     name: getField(fields, key),
-                    layerId: parseNumericField(
-                        fields,
-                        'V9_STACK_LAYER' + index + '_LAYERID'
-                    ),
+                    layerId,
+                    legacyLayerId,
                     kind: AltiumLayoutParser.#firstLayerStackTextField(
                         fields,
                         index,

package/src/core/altium/PcbLayerStackReadModelBuilder.mjs

@@ -180,6 +180,7 @@ export class PcbLayerStackReadModelBuilder {
                 PcbLayerStackReadModelBuilder.#stripUndefined({
                     index: layer.index,
                     layerId: layer.layerId,
+                    legacyLayerId: layer.legacyLayerId,
                     layerKey: Number.isFinite(layer.layerId)
                         ? 'L' + layer.layerId
                         : undefined,

package/src/styles/altium-renderers.css

@@ -142,6 +142,16 @@
     --pcb-via-hole-fill: #0f746c;
     --pcb-footprint-fill: rgba(247, 230, 117, 0.14);
     --pcb-footprint-track-color: rgba(237, 172, 36, 1);
+    --pcb-detail-paste-fill: rgba(146, 146, 146, 0.94);
+    --pcb-detail-paste-stroke: rgba(154, 154, 154, 0.96);
+    --pcb-detail-mask-fill: rgba(137, 34, 132, 0.4);
+    --pcb-detail-mask-stroke: rgba(137, 34, 132, 0.82);
+    --pcb-detail-mechanical-fill: rgba(148, 160, 166, 0.32);
+    --pcb-detail-mechanical-stroke: rgba(96, 110, 118, 0.86);
+    --pcb-detail-drill-fill: rgba(79, 87, 93, 0.46);
+    --pcb-detail-drill-stroke: rgba(42, 50, 56, 0.88);
+    --pcb-detail-fill: rgba(150, 160, 166, 0.38);
+    --pcb-detail-stroke: rgba(80, 92, 100, 0.82);
     --pcb-dimension-color: rgba(39, 88, 111, 0.78);
     --pcb-dimension-text: #22343b;
     --pcb-text-knockout-fill: rgba(248, 246, 239, 0.96);
@@ -200,7 +210,9 @@
 .pcb-track,
 .pcb-arc,
 .pcb-footprint-track,
-.pcb-footprint-arc {
+.pcb-footprint-arc,
+.pcb-detail-track,
+.pcb-detail-arc {
     fill: none;
     stroke-linecap: round;
     stroke-linejoin: round;
@@ -271,6 +283,60 @@
     stroke: var(--pcb-footprint-track-color);
 }
 
+.pcb-detail-fill,
+.pcb-detail-region {
+    fill: var(--pcb-detail-fill);
+}
+
+.pcb-detail-track,
+.pcb-detail-arc {
+    stroke: var(--pcb-detail-stroke);
+}
+
+.pcb-detail-fill--paste,
+.pcb-detail-region--paste {
+    fill: var(--pcb-detail-paste-fill);
+}
+
+.pcb-detail-track--paste,
+.pcb-detail-arc--paste {
+    stroke: var(--pcb-detail-paste-stroke);
+}
+
+.pcb-detail-fill--mask,
+.pcb-detail-region--mask,
+.pcb-detail-fill--solder-mask,
+.pcb-detail-region--solder-mask {
+    fill: var(--pcb-detail-mask-fill);
+}
+
+.pcb-detail-track--mask,
+.pcb-detail-arc--mask,
+.pcb-detail-track--solder-mask,
+.pcb-detail-arc--solder-mask {
+    stroke: var(--pcb-detail-mask-stroke);
+}
+
+.pcb-detail-fill--mechanical,
+.pcb-detail-region--mechanical {
+    fill: var(--pcb-detail-mechanical-fill);
+}
+
+.pcb-detail-track--mechanical,
+.pcb-detail-arc--mechanical {
+    stroke: var(--pcb-detail-mechanical-stroke);
+}
+
+.pcb-detail-fill--drill,
+.pcb-detail-region--drill {
+    fill: var(--pcb-detail-drill-fill);
+}
+
+.pcb-detail-track--drill,
+.pcb-detail-arc--drill {
+    stroke: var(--pcb-detail-drill-stroke);
+}
+
 .pcb-dimensions {
     pointer-events: none;
 }

package/src/ui/PcbInteractionLayerModel.mjs

@@ -56,13 +56,17 @@ export class PcbInteractionLayerModel {
             const key = String(layer?.name || layer?.layer || '').trim()
             if (!key || seen.has(key)) continue
             seen.add(key)
-            layers.push({
+            const row = {
                 key,
                 label: key,
                 layerId: Number.isFinite(Number(layer?.layerId))
                     ? Number(layer.layerId)
                     : null
-            })
+            }
+            if (Number.isFinite(Number(layer?.legacyLayerId))) {
+                row.legacyLayerId = Number(layer.legacyLayerId)
+            }
+            layers.push(row)
         }
 
         return layers

package/src/ui/PcbPadMaskApertureRenderer.mjs

@@ -0,0 +1,288 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+
+/**
+ * Renders pad-derived paste and solder-mask apertures as independent SVG layers.
+ */
+export class PcbPadMaskApertureRenderer {
+    static #PAD_SHAPE_RECTANGULAR = 2
+    static #SPECS = [
+        {
+            flag: 'hasTopPasteMaskOpening',
+            kind: 'paste',
+            primitiveKind: 'pad-paste',
+            side: 'top',
+            layerId: 35,
+            layerName: 'Top Paste',
+            expansionKey: 'effectivePasteMaskExpansion'
+        },
+        {
+            flag: 'hasBottomPasteMaskOpening',
+            kind: 'paste',
+            primitiveKind: 'pad-paste',
+            side: 'bottom',
+            layerId: 36,
+            layerName: 'Bottom Paste',
+            expansionKey: 'effectivePasteMaskExpansion'
+        },
+        {
+            flag: 'hasTopSolderMaskOpening',
+            kind: 'solder-mask',
+            primitiveKind: 'pad-solder-mask',
+            side: 'top',
+            layerId: 37,
+            layerName: 'Top Solder',
+            expansionKey: 'effectiveSolderMaskExpansion'
+        },
+        {
+            flag: 'hasBottomSolderMaskOpening',
+            kind: 'solder-mask',
+            primitiveKind: 'pad-solder-mask',
+            side: 'bottom',
+            layerId: 38,
+            layerName: 'Bottom Solder',
+            expansionKey: 'effectiveSolderMaskExpansion'
+        }
+    ]
+
+    /**
+     * Builds one SVG group containing all derived pad mask apertures.
+     * @param {object[]} pads Normalized pad records.
+     * @param {{ attributes?: (aperture: object) => string, padIndex?: (pad: object, index: number) => number }} [options]
+     * @returns {string}
+     */
+    static render(pads, options = {}) {
+        const apertures = []
+
+        for (const [fallbackIndex, pad] of (pads || []).entries()) {
+            const padIndex = PcbPadMaskApertureRenderer.#padIndex(
+                pad,
+                fallbackIndex,
+                options
+            )
+            for (const [specIndex, spec] of this.#SPECS.entries()) {
+                if (!pad?.[spec.flag]) continue
+                const aperture = this.#apertureForPad(
+                    pad,
+                    padIndex,
+                    specIndex,
+                    spec
+                )
+                if (!aperture) continue
+                apertures.push(
+                    this.#renderAperture(aperture, options.attributes)
+                )
+            }
+        }
+
+        if (!apertures.length) return ''
+
+        return '<g class="pcb-pad-mask-layers">' + apertures.join('') + '</g>'
+    }
+
+    /**
+     * Resolves one stable pad index.
+     * @param {object} pad Pad record.
+     * @param {number} fallbackIndex Array index.
+     * @param {{ padIndex?: (pad: object, index: number) => number }} options
+     * @returns {number}
+     */
+    static #padIndex(pad, fallbackIndex, options) {
+        const resolved = options.padIndex?.(pad, fallbackIndex)
+        return Number.isInteger(resolved) ? resolved : fallbackIndex
+    }
+
+    /**
+     * Builds one normalized aperture descriptor for a pad/spec pair.
+     * @param {object} pad Pad record.
+     * @param {number} padIndex Stable pad index.
+     * @param {number} specIndex Spec index.
+     * @param {object} spec Aperture layer spec.
+     * @returns {object | null}
+     */
+    static #apertureForPad(pad, padIndex, specIndex, spec) {
+        const size = this.#sizeForPad(pad, spec)
+        if (size.width <= 0 || size.height <= 0) return null
+
+        return {
+            pad,
+            padIndex,
+            index: padIndex * this.#SPECS.length + specIndex,
+            spec,
+            size,
+            primitive: {
+                ...pad,
+                layerId: spec.layerId,
+                layerCode: spec.layerId,
+                legacyLayerId: spec.layerId,
+                layerName: spec.layerName
+            }
+        }
+    }
+
+    /**
+     * Resolves aperture dimensions after the parsed mask expansion.
+     * @param {object} pad Pad record.
+     * @param {object} spec Aperture layer spec.
+     * @returns {{ width: number, height: number }}
+     */
+    static #sizeForPad(pad, spec) {
+        const side = spec.side === 'bottom' ? 'Bottom' : 'Top'
+        const width = Number(pad?.['size' + side + 'X'] || pad?.sizeMidX || 0)
+        const height = Number(pad?.['size' + side + 'Y'] || pad?.sizeMidY || 0)
+        const expansion = Number(pad?.[spec.expansionKey] || 0)
+
+        return {
+            width: Math.max(width + expansion * 2, 0),
+            height: Math.max(height + expansion * 2, 0)
+        }
+    }
+
+    /**
+     * Renders one aperture shape.
+     * @param {object} aperture Aperture descriptor.
+     * @param {(aperture: object) => string | undefined} attributes Attribute callback.
+     * @returns {string}
+     */
+    static #renderAperture(aperture, attributes) {
+        const className =
+            'pcb-detail-fill pcb-detail-fill--' +
+            (aperture.spec.kind === 'solder-mask' ? 'mask' : 'paste') +
+            ' pcb-pad-mask-aperture pcb-pad-mask-aperture--' +
+            aperture.spec.kind
+        const renderedAttributes = attributes?.(aperture) || ''
+
+        return PcbPadMaskApertureRenderer.#isRoundAperture(aperture)
+            ? PcbPadMaskApertureRenderer.#renderCircle(
+                  aperture,
+                  className,
+                  renderedAttributes
+              )
+            : PcbPadMaskApertureRenderer.#renderRect(
+                  aperture,
+                  className,
+                  renderedAttributes
+              )
+    }
+
+    /**
+     * Renders one circular aperture.
+     * @param {object} aperture Aperture descriptor.
+     * @param {string} className SVG class list.
+     * @param {string} attributes SVG attributes.
+     * @returns {string}
+     */
+    static #renderCircle(aperture, className, attributes) {
+        const { pad, size } = aperture
+        const radius = Math.max(size.width, size.height) / 2
+
+        return (
+            '<circle class="' +
+            className +
+            '" cx="' +
+            SchematicSvgUtils.formatNumber(Number(pad.x || 0)) +
+            '" cy="' +
+            SchematicSvgUtils.formatNumber(Number(pad.y || 0)) +
+            '" r="' +
+            SchematicSvgUtils.formatNumber(radius) +
+            '"' +
+            attributes +
+            ' />'
+        )
+    }
+
+    /**
+     * Renders one rectangular aperture.
+     * @param {object} aperture Aperture descriptor.
+     * @param {string} className SVG class list.
+     * @param {string} attributes SVG attributes.
+     * @returns {string}
+     */
+    static #renderRect(aperture, className, attributes) {
+        const { pad, size } = aperture
+        const x = Number(pad.x || 0) - size.width / 2
+        const y = Number(pad.y || 0) - size.height / 2
+
+        return (
+            '<rect class="' +
+            className +
+            '" x="' +
+            SchematicSvgUtils.formatNumber(x) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(y) +
+            '" width="' +
+            SchematicSvgUtils.formatNumber(size.width) +
+            '" height="' +
+            SchematicSvgUtils.formatNumber(size.height) +
+            '" rx="' +
+            SchematicSvgUtils.formatNumber(
+                PcbPadMaskApertureRenderer.#cornerRadius(aperture)
+            ) +
+            '" transform="rotate(' +
+            SchematicSvgUtils.formatNumber(Number(pad.rotation || 0)) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(Number(pad.x || 0)) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(Number(pad.y || 0)) +
+            ')"' +
+            attributes +
+            ' />'
+        )
+    }
+
+    /**
+     * Returns true when one aperture should be rendered as a circle.
+     * @param {object} aperture Aperture descriptor.
+     * @returns {boolean}
+     */
+    static #isRoundAperture(aperture) {
+        const shape = PcbPadMaskApertureRenderer.#shapeForAperture(aperture)
+        return (
+            shape !== PcbPadMaskApertureRenderer.#PAD_SHAPE_RECTANGULAR &&
+            Math.abs(aperture.size.width - aperture.size.height) < 0.001
+        )
+    }
+
+    /**
+     * Resolves the side-specific pad shape code.
+     * @param {object} aperture Aperture descriptor.
+     * @returns {number}
+     */
+    static #shapeForAperture(aperture) {
+        const side = aperture.spec.side === 'bottom' ? 'Bottom' : 'Top'
+        if (
+            side === 'Top' &&
+            aperture.pad?.hasRoundedRect &&
+            Number.isInteger(aperture.pad.roundedRectShapeTop)
+        ) {
+            return Number(aperture.pad.roundedRectShapeTop)
+        }
+        return Number(aperture.pad?.['shape' + side] || 0)
+    }
+
+    /**
+     * Resolves rectangle corner radius for rounded pad shapes.
+     * @param {object} aperture Aperture descriptor.
+     * @returns {number}
+     */
+    static #cornerRadius(aperture) {
+        if (
+            aperture.spec.side === 'top' &&
+            aperture.pad?.hasRoundedRect &&
+            Number.isFinite(aperture.pad.cornerRadiusTop)
+        ) {
+            return (
+                Math.min(aperture.size.width, aperture.size.height) *
+                (Number(aperture.pad.cornerRadiusTop) / 100)
+            )
+        }
+        if (PcbPadMaskApertureRenderer.#shapeForAperture(aperture) === 1) {
+            return Math.min(aperture.size.width, aperture.size.height) / 2
+        }
+
+        return 0
+    }
+}

package/src/ui/PcbSvgRenderer.mjs

@@ -8,7 +8,10 @@ import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs
 import { PcbEmbeddedFontFaceRenderer } from './PcbEmbeddedFontFaceRenderer.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbCopperPrimitiveSplitter } from './PcbCopperPrimitiveSplitter.mjs'
+import { PcbLayerIdCodec } from '../core/altium/PcbLayerIdCodec.mjs'
+import { PcbLayerGroups } from '../core/altium/PcbLayerGroups.mjs'
 import { PcbNativeTextKnockoutDetector } from './PcbNativeTextKnockoutDetector.mjs'
+import { PcbPadMaskApertureRenderer } from './PcbPadMaskApertureRenderer.mjs'
 import { PcbRegionPrimitiveRenderer } from './PcbRegionPrimitiveRenderer.mjs'
 import { PcbScene3dBoardOutlineRefiner } from './PcbScene3dBoardOutlineRefiner.mjs'
 import { PcbTextPrimitiveRenderer } from './PcbTextPrimitiveRenderer.mjs'
@@ -80,7 +83,7 @@ export class PcbSvgRenderer {
             arcs,
             renderedRegions
         )
-        const footprintPrimitives = PcbEdgeFacingGlyphNormalizer.normalize(
+        const selectedFootprintPrimitives =
             PcbFootprintPrimitiveSelector.select(
                 primitiveLayers,
                 fills,
@@ -88,9 +91,21 @@ export class PcbSvgRenderer {
                 arcs,
                 renderedRegions,
                 'top'
-            ),
+            )
+        const footprintPrimitives = PcbEdgeFacingGlyphNormalizer.normalize(
+            selectedFootprintPrimitives,
             outline
         )
+        const detailPrimitives = PcbSvgRenderer.#detailPrimitiveCollections(
+            {
+                fills,
+                tracks,
+                arcs,
+                regions: renderedRegions
+            },
+            PcbSvgRenderer.#primitiveIdentitySet(selectedFootprintPrimitives),
+            semanticContext
+        )
         const texts = PcbTextPrimitiveRenderer.select(
             primitiveLayers,
             pcb.texts || [],
@@ -115,22 +130,26 @@ export class PcbSvgRenderer {
             [
                 ...copperGroups.surface.fills,
                 ...copperGroups.subsurface.fills,
-                ...footprintPrimitives.fills
+                ...footprintPrimitives.fills,
+                ...detailPrimitives.fills
             ],
             [
                 ...copperGroups.surface.tracks,
                 ...copperGroups.subsurface.tracks,
-                ...footprintPrimitives.tracks
+                ...footprintPrimitives.tracks,
+                ...detailPrimitives.tracks
             ],
             [
                 ...copperGroups.surface.arcs,
                 ...copperGroups.subsurface.arcs,
-                ...footprintPrimitives.arcs
+                ...footprintPrimitives.arcs,
+                ...detailPrimitives.arcs
             ],
             [
                 ...copperGroups.surface.regions,
                 ...copperGroups.subsurface.regions,
-                ...footprintPrimitives.regions
+                ...footprintPrimitives.regions,
+                ...detailPrimitives.regions
             ],
             vias,
             pads,
@@ -263,10 +282,27 @@ export class PcbSvgRenderer {
                 )
                 .join('')
         const regionMarkup = (regionList, visibilityClass) =>
-            PcbRegionPrimitiveRenderer.buildMarkup(
-                regionList,
-                'pcb-region pcb-region--' + visibilityClass
-            )
+            regionList
+                .map((region, index) =>
+                    PcbSvgRenderer.#appendSvgAttributes(
+                        PcbRegionPrimitiveRenderer.buildMarkup(
+                            [region],
+                            'pcb-region pcb-region--' + visibilityClass
+                        ),
+                        PcbSvgRenderer.#semanticAttributes(
+                            'region',
+                            region,
+                            PcbSvgRenderer.#primitiveIndex(
+                                semanticContext,
+                                'regions',
+                                region,
+                                index
+                            ),
+                            semanticContext
+                        )
+                    )
+                )
+                .join('')
         const viaMarkup = vias
             .map((via, index) => {
                 const ringRadius = Math.max((via.diameter || 0) / 2, 1)
@@ -328,8 +364,26 @@ export class PcbSvgRenderer {
                 )
             )
             .join('')
+        const padMaskApertureMarkup = PcbPadMaskApertureRenderer.render(pads, {
+            padIndex: (pad, index) =>
+                PcbSvgRenderer.#primitiveIndex(
+                    semanticContext,
+                    'pads',
+                    pad,
+                    index
+                ),
+            attributes: (aperture) =>
+                PcbSvgRenderer.#padMaskApertureAttributes(
+                    aperture,
+                    semanticContext
+                )
+        })
+        const detailMarkup = PcbSvgRenderer.#renderDetailPrimitives(
+            detailPrimitives,
+            semanticContext
+        )
         const footprintFillMarkup = footprintPrimitives.fills
-            .map((fill) => {
+            .map((fill, index) => {
                 const x = Math.min(fill.x1, fill.x2)
                 const y = Math.min(fill.y1, fill.y2)
                 const width = Math.abs(fill.x2 - fill.x1)
@@ -347,13 +401,25 @@ export class PcbSvgRenderer {
                     SchematicSvgUtils.formatNumber(
                         Math.min(width, height) / 6
                     ) +
-                    '" />'
+                    '"' +
+                    PcbSvgRenderer.#semanticAttributes(
+                        'fill',
+                        fill,
+                        PcbSvgRenderer.#primitiveIndex(
+                            semanticContext,
+                            'fills',
+                            fill,
+                            index
+                        ),
+                        semanticContext
+                    ) +
+                    ' />'
                 )
             })
             .join('')
         const footprintTrackMarkup = footprintPrimitives.tracks
             .map(
-                (track) =>
+                (track, index) =>
                     '<line class="pcb-footprint-track" x1="' +
                     SchematicSvgUtils.formatNumber(track.x1) +
                     '" y1="' +
@@ -366,16 +432,60 @@ export class PcbSvgRenderer {
                     SchematicSvgUtils.formatNumber(
                         Math.max(track.width || 0, 1)
                     ) +
-                    '" />'
+                    '"' +
+                    PcbSvgRenderer.#semanticAttributes(
+                        'track',
+                        track,
+                        PcbSvgRenderer.#primitiveIndex(
+                            semanticContext,
+                            'tracks',
+                            track,
+                            index
+                        ),
+                        semanticContext
+                    ) +
+                    ' />'
             )
             .join('')
         const footprintArcMarkup = footprintPrimitives.arcs
-            .map((arc) => PcbArcUtils.buildMarkup(arc, 'pcb-footprint-arc'))
+            .map((arc, index) =>
+                PcbSvgRenderer.#appendSvgAttributes(
+                    PcbArcUtils.buildMarkup(arc, 'pcb-footprint-arc'),
+                    PcbSvgRenderer.#semanticAttributes(
+                        'arc',
+                        arc,
+                        PcbSvgRenderer.#primitiveIndex(
+                            semanticContext,
+                            'arcs',
+                            arc,
+                            index
+                        ),
+                        semanticContext
+                    )
+                )
+            )
+            .join('')
+        const footprintRegionMarkup = footprintPrimitives.regions
+            .map((region, index) =>
+                PcbSvgRenderer.#appendSvgAttributes(
+                    PcbRegionPrimitiveRenderer.buildMarkup(
+                        [region],
+                        'pcb-footprint-region'
+                    ),
+                    PcbSvgRenderer.#semanticAttributes(
+                        'region',
+                        region,
+                        PcbSvgRenderer.#primitiveIndex(
+                            semanticContext,
+                            'regions',
+                            region,
+                            index
+                        ),
+                        semanticContext
+                    )
+                )
+            )
             .join('')
-        const footprintRegionMarkup = PcbRegionPrimitiveRenderer.buildMarkup(
-            footprintPrimitives.regions,
-            'pcb-footprint-region'
-        )
         const textMarkup = PcbTextPrimitiveRenderer.render(texts, {
             semanticContext
         })
@@ -519,6 +629,7 @@ export class PcbSvgRenderer {
             SchematicSvgUtils.escapeHtml(path) +
             '"' +
             ' />' +
+            padMaskApertureMarkup +
             '<g class="pcb-copper-layers" clip-path="url(#' +
             clipPathId +
             ')">' +
@@ -545,6 +656,7 @@ export class PcbSvgRenderer {
             footprintArcMarkup +
             footprintRegionMarkup +
             '</g>' +
+            detailMarkup +
             '<g class="pcb-components">' +
             componentMarkup +
             '</g>' +
@@ -594,6 +706,316 @@ export class PcbSvgRenderer {
         )
     }
 
+    /**
+     * Selects non-copper layer primitives that need explicit SVG artwork.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[], regions?: object[] }} primitives Primitive collections.
+     * @param {Set<object>} excludedPrimitives Primitives already rendered elsewhere.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {{ fills: object[], tracks: object[], arcs: object[], regions: object[] }}
+     */
+    static #detailPrimitiveCollections(
+        primitives,
+        excludedPrimitives,
+        semanticContext
+    ) {
+        const includePrimitive = (primitive) =>
+            !excludedPrimitives.has(primitive) &&
+            PcbSvgRenderer.#isDetailPrimitive(primitive, semanticContext)
+
+        return {
+            fills: (primitives.fills || []).filter(includePrimitive),
+            tracks: (primitives.tracks || []).filter(includePrimitive),
+            arcs: (primitives.arcs || []).filter(includePrimitive),
+            regions: (primitives.regions || []).filter(includePrimitive)
+        }
+    }
+
+    /**
+     * Builds an identity set for primitives rendered by a specialized path.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[], regions?: object[] }} primitiveCollections Primitive collections.
+     * @returns {Set<object>}
+     */
+    static #primitiveIdentitySet(primitiveCollections) {
+        return new Set([
+            ...(primitiveCollections?.fills || []),
+            ...(primitiveCollections?.tracks || []),
+            ...(primitiveCollections?.arcs || []),
+            ...(primitiveCollections?.regions || [])
+        ])
+    }
+
+    /**
+     * Returns true when a primitive should render as generic layer detail.
+     * @param {object} primitive Primitive record.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {boolean}
+     */
+    static #isDetailPrimitive(primitive, semanticContext) {
+        const layer = PcbSvgRenderer.#knownLayerForPrimitive(
+            primitive,
+            semanticContext
+        )
+        const role = PcbSvgRenderer.#layerRoleForDetail(layer)
+
+        return Boolean(layer) && !['copper', 'multi-layer'].includes(role)
+    }
+
+    /**
+     * Renders non-copper fabrication and documentation primitives.
+     * @param {{ fills: object[], tracks: object[], arcs: object[], regions: object[] }} primitives Primitive collections.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #renderDetailPrimitives(primitives, semanticContext) {
+        const fillMarkup = primitives.fills
+            .map((fill, index) =>
+                PcbSvgRenderer.#renderDetailFill(
+                    fill,
+                    PcbSvgRenderer.#primitiveIndex(
+                        semanticContext,
+                        'fills',
+                        fill,
+                        index
+                    ),
+                    semanticContext
+                )
+            )
+            .join('')
+        const trackMarkup = primitives.tracks
+            .map((track, index) =>
+                PcbSvgRenderer.#renderDetailTrack(
+                    track,
+                    PcbSvgRenderer.#primitiveIndex(
+                        semanticContext,
+                        'tracks',
+                        track,
+                        index
+                    ),
+                    semanticContext
+                )
+            )
+            .join('')
+        const arcMarkup = primitives.arcs
+            .map((arc, index) =>
+                PcbSvgRenderer.#renderDetailArc(
+                    arc,
+                    PcbSvgRenderer.#primitiveIndex(
+                        semanticContext,
+                        'arcs',
+                        arc,
+                        index
+                    ),
+                    semanticContext
+                )
+            )
+            .join('')
+        const regionMarkup = primitives.regions
+            .map((region, index) =>
+                PcbSvgRenderer.#renderDetailRegion(
+                    region,
+                    PcbSvgRenderer.#primitiveIndex(
+                        semanticContext,
+                        'regions',
+                        region,
+                        index
+                    ),
+                    semanticContext
+                )
+            )
+            .join('')
+
+        return fillMarkup || trackMarkup || arcMarkup || regionMarkup
+            ? '<g class="pcb-detail-layers">' +
+                  fillMarkup +
+                  trackMarkup +
+                  arcMarkup +
+                  regionMarkup +
+                  '</g>'
+            : ''
+    }
+
+    /**
+     * Renders one non-copper fill primitive.
+     * @param {{ x1: number, y1: number, x2: number, y2: number }} fill Fill primitive.
+     * @param {number} index Stable primitive index.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #renderDetailFill(fill, index, semanticContext) {
+        const x = Math.min(fill.x1, fill.x2)
+        const y = Math.min(fill.y1, fill.y2)
+        const width = Math.abs(fill.x2 - fill.x1)
+        const height = Math.abs(fill.y2 - fill.y1)
+        const className = PcbSvgRenderer.#detailPrimitiveClass(
+            'fill',
+            fill,
+            semanticContext
+        )
+
+        return (
+            '<rect class="' +
+            className +
+            '" x="' +
+            SchematicSvgUtils.formatNumber(x) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(y) +
+            '" width="' +
+            SchematicSvgUtils.formatNumber(width) +
+            '" height="' +
+            SchematicSvgUtils.formatNumber(height) +
+            '" rx="' +
+            SchematicSvgUtils.formatNumber(Math.min(width, height) / 6) +
+            '"' +
+            PcbSvgRenderer.#semanticAttributes(
+                'fill',
+                fill,
+                index,
+                semanticContext
+            ) +
+            ' />'
+        )
+    }
+
+    /**
+     * Renders one non-copper track primitive.
+     * @param {{ x1: number, y1: number, x2: number, y2: number, width?: number }} track Track primitive.
+     * @param {number} index Stable primitive index.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #renderDetailTrack(track, index, semanticContext) {
+        const className = PcbSvgRenderer.#detailPrimitiveClass(
+            'track',
+            track,
+            semanticContext
+        )
+
+        return (
+            '<line class="' +
+            className +
+            '" x1="' +
+            SchematicSvgUtils.formatNumber(track.x1) +
+            '" y1="' +
+            SchematicSvgUtils.formatNumber(track.y1) +
+            '" x2="' +
+            SchematicSvgUtils.formatNumber(track.x2) +
+            '" y2="' +
+            SchematicSvgUtils.formatNumber(track.y2) +
+            '" stroke-width="' +
+            SchematicSvgUtils.formatNumber(Math.max(track.width || 0, 1)) +
+            '"' +
+            PcbSvgRenderer.#semanticAttributes(
+                'track',
+                track,
+                index,
+                semanticContext
+            ) +
+            ' />'
+        )
+    }
+
+    /**
+     * Renders one non-copper arc primitive.
+     * @param {object} arc Arc primitive.
+     * @param {number} index Stable primitive index.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #renderDetailArc(arc, index, semanticContext) {
+        return PcbSvgRenderer.#appendSvgAttributes(
+            PcbArcUtils.buildMarkup(
+                arc,
+                PcbSvgRenderer.#detailPrimitiveClass(
+                    'arc',
+                    arc,
+                    semanticContext
+                )
+            ),
+            PcbSvgRenderer.#semanticAttributes(
+                'arc',
+                arc,
+                index,
+                semanticContext
+            )
+        )
+    }
+
+    /**
+     * Renders one non-copper region primitive.
+     * @param {object} region Region primitive.
+     * @param {number} index Stable primitive index.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #renderDetailRegion(region, index, semanticContext) {
+        return PcbSvgRenderer.#appendSvgAttributes(
+            PcbRegionPrimitiveRenderer.buildMarkup(
+                [region],
+                PcbSvgRenderer.#detailPrimitiveClass(
+                    'region',
+                    region,
+                    semanticContext
+                )
+            ),
+            PcbSvgRenderer.#semanticAttributes(
+                'region',
+                region,
+                index,
+                semanticContext
+            )
+        )
+    }
+
+    /**
+     * Builds one detail primitive CSS class string.
+     * @param {string} primitiveKind Primitive kind.
+     * @param {object} primitive Primitive record.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #detailPrimitiveClass(primitiveKind, primitive, semanticContext) {
+        const layer = PcbSvgRenderer.#layerForPrimitive(
+            primitive,
+            semanticContext
+        )
+        const role = PcbSvgRenderer.#cssToken(
+            PcbSvgRenderer.#layerRoleForDetail(layer)
+        )
+
+        return (
+            'pcb-detail-' +
+            primitiveKind +
+            ' pcb-detail-' +
+            primitiveKind +
+            '--' +
+            role
+        )
+    }
+
+    /**
+     * Resolves a layer role suitable for generic detail styling.
+     * @param {object | null} layer Layer descriptor.
+     * @returns {string}
+     */
+    static #layerRoleForDetail(layer) {
+        return String(layer?.role || 'other')
+    }
+
+    /**
+     * Converts arbitrary text to a safe CSS class token.
+     * @param {unknown} value Raw token value.
+     * @returns {string}
+     */
+    static #cssToken(value) {
+        return (
+            String(value || 'other')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-+|-+$/gu, '') || 'other'
+        )
+    }
+
     /**
      * Normalizes renderer view options.
      * @param {{ viewKind?: string, layerView?: object } | undefined} options Render options.
@@ -721,17 +1143,31 @@ export class PcbSvgRenderer {
             primitive?.layerId,
             primitive?.layerCode
         ])
-        if (Number.isInteger(layerId) && Number.isInteger(layerView?.layerId)) {
-            return layerId === layerView.layerId
+        const layerIds = PcbSvgRenderer.#layerDescriptorIds(layerView)
+        if (Number.isInteger(layerId) && layerIds.length) {
+            return layerIds.includes(layerId)
         }
 
         const primitiveName =
             primitive?.layerName || primitive?.layer || primitive?.side || ''
         if (primitiveName && layerView?.displayName) {
-            return (
+            if (
                 PcbSvgRenderer.#normalizeSemanticLookup(primitiveName) ===
                 PcbSvgRenderer.#normalizeSemanticLookup(layerView.displayName)
-            )
+            ) {
+                return true
+            }
+
+            const primitiveLayerId =
+                PcbSvgRenderer.#legacyLayerIdForPrimitiveLayerName(
+                    primitiveName
+                )
+            if (
+                Number.isInteger(primitiveLayerId) &&
+                layerIds.includes(primitiveLayerId)
+            ) {
+                return true
+            }
         }
 
         return (
@@ -768,6 +1204,12 @@ export class PcbSvgRenderer {
             ) {
                 layersById.set(descriptor.layerId, descriptor)
             }
+            if (
+                Number.isInteger(descriptor.legacyLayerId) &&
+                !layersById.has(descriptor.legacyLayerId)
+            ) {
+                layersById.set(descriptor.legacyLayerId, descriptor)
+            }
             const normalizedName = PcbSvgRenderer.#normalizeSemanticLookup(
                 descriptor.displayName
             )
@@ -830,6 +1272,7 @@ export class PcbSvgRenderer {
                 fills: PcbSvgRenderer.#objectIndexMap(pcb?.fills || []),
                 tracks: PcbSvgRenderer.#objectIndexMap(pcb?.tracks || []),
                 arcs: PcbSvgRenderer.#objectIndexMap(pcb?.arcs || []),
+                regions: PcbSvgRenderer.#objectIndexMap(pcb?.regions || []),
                 vias: PcbSvgRenderer.#objectIndexMap(pcb?.vias || []),
                 pads: PcbSvgRenderer.#objectIndexMap(pcb?.pads || []),
                 texts: PcbSvgRenderer.#objectIndexMap(pcb?.texts || []),
@@ -884,6 +1327,12 @@ export class PcbSvgRenderer {
                     pcb?.arcs || [],
                     semanticContext
                 ),
+                ...PcbSvgRenderer.#semanticMetadataEntries(
+                    'region',
+                    'regions',
+                    pcb?.regions || [],
+                    semanticContext
+                ),
                 ...PcbSvgRenderer.#semanticMetadataEntries(
                     'via',
                     'vias',
@@ -1370,6 +1819,7 @@ export class PcbSvgRenderer {
             layer.id,
             layer.index
         ])
+        const legacyLayerId = PcbSvgRenderer.#legacyLayerId(layer, layerId)
         const displayName =
             layer.displayName || layer.name || layer.layerName || ''
         const layerKey = Number.isInteger(layerId)
@@ -1382,12 +1832,16 @@ export class PcbSvgRenderer {
 
         return PcbSvgRenderer.#stripEmptySemanticObject({
             layerId,
+            legacyLayerId,
             layerKey,
             displayName: displayName || layerKey,
             role:
                 layer.role ||
                 layer.layerRole ||
-                PcbSvgRenderer.#inferLayerRole(displayName)
+                PcbSvgRenderer.#inferLayerRole(
+                    displayName,
+                    legacyLayerId ?? layerId
+                )
         })
     }
 
@@ -1398,10 +1852,50 @@ export class PcbSvgRenderer {
      */
     static #includedLayerIds(semanticContext) {
         return (semanticContext?.layerDescriptors || [])
-            .map((layer) => layer.layerId)
+            .flatMap((layer) => PcbSvgRenderer.#layerDescriptorIds(layer))
             .filter((layerId) => Number.isInteger(layerId))
     }
 
+    /**
+     * Returns all numeric identifiers that can address one layer descriptor.
+     * @param {object | null} layer Layer descriptor.
+     * @returns {number[]}
+     */
+    static #layerDescriptorIds(layer) {
+        return [
+            PcbSvgRenderer.#firstFiniteNumber([layer?.layerId]),
+            PcbSvgRenderer.#firstFiniteNumber([layer?.legacyLayerId])
+        ].filter(
+            (layerId, index, layerIds) =>
+                Number.isInteger(layerId) && layerIds.indexOf(layerId) === index
+        )
+    }
+
+    /**
+     * Resolves a legacy primitive-layer alias for a layer descriptor.
+     * @param {object} layer Layer record.
+     * @param {number | undefined} layerId Primary layer id.
+     * @returns {number | undefined}
+     */
+    static #legacyLayerId(layer, layerId) {
+        const explicitLegacyLayerId = PcbSvgRenderer.#firstFiniteNumber([
+            layer.legacyLayerId,
+            layer.legacyId
+        ])
+        const legacyLayerId = Number.isInteger(explicitLegacyLayerId)
+            ? explicitLegacyLayerId
+            : PcbLayerIdCodec.legacyLayerIdFromV7SaveId(layerId)
+
+        if (
+            !Number.isInteger(legacyLayerId) ||
+            (Number.isInteger(layerId) && legacyLayerId === layerId)
+        ) {
+            return undefined
+        }
+
+        return legacyLayerId
+    }
+
     /**
      * Returns true when a PCB view contains only board outline metadata.
      * @param {object} pcb Normalized PCB model.
@@ -1426,9 +1920,15 @@ export class PcbSvgRenderer {
     /**
      * Infers one broad rendering role from a layer name.
      * @param {string} displayName Layer display name.
+     * @param {number | undefined} layerId Legacy layer id.
      * @returns {string}
      */
-    static #inferLayerRole(displayName) {
+    static #inferLayerRole(displayName, layerId) {
+        const groupedRole = PcbSvgRenderer.#inferLayerRoleFromId(layerId)
+        if (groupedRole) {
+            return groupedRole
+        }
+
         const normalized = String(displayName || '').toLowerCase()
         if (/overlay|silk/u.test(normalized)) return 'overlay'
         if (/paste/u.test(normalized)) return 'paste'
@@ -1437,10 +1937,42 @@ export class PcbSvgRenderer {
             return 'mechanical'
         }
         if (/drill/u.test(normalized)) return 'drill'
-        if (/layer|copper|plane/u.test(normalized)) return 'copper'
+        if (
+            /layer|copper|plane/u.test(normalized) ||
+            /\binternal[-_\s]*\d+\b/u.test(normalized) ||
+            /\binner[-_\s]*\d+\b/u.test(normalized)
+        ) {
+            return 'copper'
+        }
         return 'other'
     }
 
+    /**
+     * Infers one layer role from a legacy Altium layer id.
+     * @param {unknown} layerId Legacy layer id.
+     * @returns {string}
+     */
+    static #inferLayerRoleFromId(layerId) {
+        const legacyLayerId = Number(layerId)
+        if (!Number.isInteger(legacyLayerId)) {
+            return ''
+        }
+        if (
+            PcbLayerGroups.isCopper(legacyLayerId) ||
+            PcbLayerGroups.isInternalPlane(legacyLayerId)
+        ) {
+            return 'copper'
+        }
+        if (PcbLayerGroups.isOverlay(legacyLayerId)) return 'overlay'
+        if (PcbLayerGroups.isPaste(legacyLayerId)) return 'paste'
+        if (PcbLayerGroups.isSolderMask(legacyLayerId)) return 'mask'
+        if (PcbLayerGroups.isDrill(legacyLayerId)) return 'drill'
+        if (PcbLayerGroups.isKeepout(legacyLayerId)) return 'keepout'
+        if (PcbLayerGroups.isMechanical(legacyLayerId)) return 'mechanical'
+        if (PcbLayerGroups.isMultiLayer(legacyLayerId)) return 'multi-layer'
+        return ''
+    }
+
     /**
      * Resolves drill plating metadata for SVG and sidecar output.
      * @param {object} primitive Drill owner primitive.
@@ -1504,21 +2036,46 @@ export class PcbSvgRenderer {
      * @returns {{ layerId?: number, layerKey: string, displayName: string } | null}
      */
     static #layerForPrimitive(primitive, semanticContext) {
+        const knownLayer = PcbSvgRenderer.#knownLayerForPrimitive(
+            primitive,
+            semanticContext
+        )
+        if (knownLayer) {
+            return knownLayer
+        }
+
         const layerId = PcbSvgRenderer.#firstFiniteNumber([
             primitive?.layerId,
             primitive?.layerCode
         ])
         if (Number.isInteger(layerId)) {
-            return (
-                semanticContext.layersById.get(layerId) || {
-                    layerId,
-                    layerKey: 'L' + layerId,
-                    displayName:
-                        primitive?.layerName ||
-                        primitive?.layer ||
-                        'Layer ' + layerId
-                }
-            )
+            return {
+                layerId,
+                layerKey: 'L' + layerId,
+                displayName:
+                    primitive?.layerName ||
+                    primitive?.layer ||
+                    'Layer ' + layerId,
+                role: PcbSvgRenderer.#inferLayerRole('', layerId)
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Resolves a layer descriptor only when the layer is in recovered metadata.
+     * @param {object} primitive Primitive record.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {{ layerId?: number, layerKey: string, displayName: string } | null}
+     */
+    static #knownLayerForPrimitive(primitive, semanticContext) {
+        const layerId = PcbSvgRenderer.#firstFiniteNumber([
+            primitive?.layerId,
+            primitive?.layerCode
+        ])
+        if (Number.isInteger(layerId)) {
+            return semanticContext.layersById.get(layerId) || null
         }
 
         const layerName =
@@ -1527,7 +2084,63 @@ export class PcbSvgRenderer {
             PcbSvgRenderer.#normalizeSemanticLookup(layerName)
         )
 
-        return byName || null
+        return (
+            byName ||
+            PcbSvgRenderer.#layerForPrimitiveLayerAlias(
+                layerName,
+                semanticContext
+            )
+        )
+    }
+
+    /**
+     * Resolves legacy Altium primitive layer names such as MID2 to a layer.
+     * @param {string} layerName Primitive layer name.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {{ layerId?: number, layerKey: string, displayName: string } | null}
+     */
+    static #layerForPrimitiveLayerAlias(layerName, semanticContext) {
+        const legacyLayerId =
+            PcbSvgRenderer.#legacyLayerIdForPrimitiveLayerName(layerName)
+
+        return Number.isInteger(legacyLayerId)
+            ? semanticContext.layersById.get(legacyLayerId) || null
+            : null
+    }
+
+    /**
+     * Converts common primitive layer aliases into legacy layer ids.
+     * @param {string} layerName Primitive layer name.
+     * @returns {number | undefined}
+     */
+    static #legacyLayerIdForPrimitiveLayerName(layerName) {
+        const compact = PcbSvgRenderer.#normalizeSemanticLookup(
+            layerName
+        ).replace(/[\s_-]+/gu, '')
+
+        if (compact === 'TOP' || compact === 'TOPLAYER') {
+            return 1
+        }
+        if (
+            compact === 'BOTTOM' ||
+            compact === 'BOTTOMLAYER' ||
+            compact === 'BOT' ||
+            compact === 'BOTLAYER'
+        ) {
+            return 32
+        }
+
+        const midLayerMatch = compact.match(/^MID(?:DLE)?(?:LAYER)?(\d+)$/u)
+        if (midLayerMatch) {
+            return Number(midLayerMatch[1]) + 1
+        }
+
+        const internalLayerMatch = compact.match(/^(?:INTERNAL|INNER)(\d+)$/u)
+        if (internalLayerMatch) {
+            return Number(internalLayerMatch[1]) + 1
+        }
+
+        return undefined
     }
 
     /**
@@ -1996,6 +2609,29 @@ export class PcbSvgRenderer {
         )
     }
 
+    /**
+     * Renders semantic attributes for a generated pad mask aperture.
+     * @param {object} aperture Pad mask aperture descriptor.
+     * @param {object} semanticContext Semantic lookup context.
+     * @returns {string}
+     */
+    static #padMaskApertureAttributes(aperture, semanticContext) {
+        return (
+            PcbSvgRenderer.#semanticAttributes(
+                aperture.spec.primitiveKind,
+                aperture.primitive,
+                aperture.index,
+                semanticContext
+            ) +
+            PcbSvgRenderer.#renderDataAttributes({
+                'data-pad-number': PcbSvgRenderer.#padNumber(aperture.pad),
+                'data-mask-kind': aperture.spec.kind,
+                'data-mask-side': aperture.spec.side,
+                'data-source-pad-element-key': 'pcb-pad-' + aperture.padIndex
+            })
+        )
+    }
+
     /**
      * Renders one pad drill hole as SVG.
      * @param {{ holeDiameter?: number, holeShape?: number | null, holeSlotLength?: number | null, holeRotation?: number | null }} pad