altium-toolkit 1.4.8 → 1.4.9

package/docs/release-notes-v1.4.9.md

@@ -0,0 +1,37 @@
+# altium-toolkit 1.4.9
+
+Version 1.4.9 restores complete mechanical and documentation artwork in native
+Altium PCB rendering and supports fitting the viewport to visible layers.
+
+## Drawing annotations
+
+- Text from mechanical, assembly, fabrication, documentation, notes, dimension,
+  and courtyard layers is rendered alongside the corresponding drawing
+  geometry.
+- Side-specific assembly annotations follow the active board side.
+- Off-board drawing annotations remain outside the board clip, preserving title
+  blocks and fabrication notes at their authored positions.
+
+## Visible-layer viewport
+
+- PCB render options accept hidden layer aliases when calculating the root SVG
+  viewport.
+- Hidden drawing layers retain their SVG markup for instant visibility toggles
+  while no longer expanding the fitted viewport.
+- Component placements far outside the board are excluded from board-first
+  viewport fitting when drawing layers are hidden.
+
+## Compatibility
+
+- Historical native renderer source remains frozen; the behavior is composed in
+  the public convergence renderer.
+- Existing render calls without hidden layers preserve their previous output and
+  bounds.
+- Layer-only exports retain the historical output contract.
+
+## Verification
+
+- Repository-owned fake regressions cover top- and bottom-side drawing text,
+  unclipped annotations, retained hidden markup, and visible-layer bounds.
+- The complete package suite, formatting check, performance guard, npm package
+  dry run, and ECAD Forge integration gates are required for release.

package/package.json

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

package/src/convergence/PcbConvergenceLayerModel.mjs

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbLayerGroups } from '../core/altium/PcbLayerGroups.mjs'
+
+/**
+ * Resolves normalized layer identity for convergence-owned PCB rendering.
+ */
+export class PcbConvergenceLayerModel {
+    /**
+     * Resolves distinct layer descriptors from stack and primitive metadata.
+     * @param {object} documentModel PCB document.
+     * @returns {object[]}
+     */
+    static resolve(documentModel) {
+        const pcb = documentModel?.pcb || {}
+        const layers = [...(pcb.layers || []), ...(pcb.primitiveLayers || [])]
+        const descriptors = []
+        const identities = new Set()
+
+        for (const layer of layers) {
+            const descriptor = PcbConvergenceLayerModel.#descriptor(layer)
+            const identity = descriptor.layerKey || descriptor.displayName
+            if (!identity || identities.has(identity)) continue
+            identities.add(identity)
+            descriptors.push(descriptor)
+        }
+        return descriptors
+    }
+
+    /**
+     * Builds layer lookup maps for primitive and text matching.
+     * @param {object} documentModel PCB document.
+     * @returns {{ byId: Map<number, object>, byName: Map<string, object>, layers: object[] }}
+     */
+    static buildLookup(documentModel) {
+        const layers = PcbConvergenceLayerModel.resolve(documentModel)
+        const byId = new Map()
+        const byName = new Map()
+        for (const layer of layers) {
+            for (const id of [layer.layerId, layer.legacyLayerId]) {
+                if (Number.isInteger(id) && !byId.has(id)) byId.set(id, layer)
+            }
+            byName.set(
+                PcbConvergenceLayerModel.normalize(layer.displayName),
+                layer
+            )
+        }
+        return { byId, byName, layers }
+    }
+
+    /**
+     * Resolves the known layer for one primitive.
+     * @param {object} primitive Primitive record.
+     * @param {{ byId: Map<number, object>, byName: Map<string, object> }} lookup Layer lookup.
+     * @returns {object | null}
+     */
+    static layerForPrimitive(primitive, lookup) {
+        for (const value of [primitive?.layerId, primitive?.layerCode]) {
+            const id = Number(value)
+            if (Number.isInteger(id) && lookup.byId.has(id)) {
+                return lookup.byId.get(id)
+            }
+        }
+        const name = PcbConvergenceLayerModel.normalize(
+            primitive?.layerName || primitive?.layer || primitive?.side
+        )
+        return name ? lookup.byName.get(name) || null : null
+    }
+
+    /**
+     * Returns all stable aliases for one layer descriptor.
+     * @param {object | null} layer Layer descriptor.
+     * @returns {string[]}
+     */
+    static aliases(layer) {
+        if (!layer) return []
+        return [
+            layer.layerKey,
+            layer.displayName,
+            layer.layerId,
+            layer.legacyLayerId,
+            Number.isInteger(layer.layerId) ? 'L' + layer.layerId : '',
+            Number.isInteger(layer.legacyLayerId)
+                ? 'L' + layer.legacyLayerId
+                : ''
+        ]
+            .map(PcbConvergenceLayerModel.normalize)
+            .filter(Boolean)
+    }
+
+    /**
+     * Returns true for mechanical and documentation drawing layers.
+     * @param {object} layer Layer descriptor.
+     * @returns {boolean}
+     */
+    static isDrawingLayer(layer) {
+        const text = [layer?.displayName, layer?.role]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase()
+        return /(mechanical|assembly|\basm\b|fabrication|\bfab\b|drawing|dimension|documentation|document|notes?|courtyard|crtyd)/u.test(
+            text
+        )
+    }
+
+    /**
+     * Returns true when one drawing layer belongs to the requested side.
+     * @param {object} layer Layer descriptor.
+     * @param {'top' | 'bottom'} side Board side.
+     * @returns {boolean}
+     */
+    static isDrawingLayerForSide(layer, side) {
+        if (!PcbConvergenceLayerModel.isDrawingLayer(layer)) return false
+        const text = [layer?.displayName, layer?.role]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase()
+        const compact = text.replace(/[^a-z0-9]+/gu, '')
+        const bottom =
+            /\bbottom\b|\bbot\b|botside|backassembly|bassembly|bcrtyd/u.test(
+                text
+            ) || compact.includes('assemblybottom')
+        const top =
+            /\btop\b|frontassembly|fassembly|fcrtyd/u.test(text) ||
+            compact.includes('assemblytop')
+
+        if (bottom && !top) return side === 'bottom'
+        if (top && !bottom) return side === 'top'
+        return true
+    }
+
+    /**
+     * Normalizes one semantic layer alias.
+     * @param {unknown} value Raw alias.
+     * @returns {string}
+     */
+    static normalize(value) {
+        return String(value ?? '')
+            .trim()
+            .toUpperCase()
+    }
+
+    /**
+     * Builds one normalized descriptor.
+     * @param {object} layer Source layer.
+     * @returns {object}
+     */
+    static #descriptor(layer) {
+        const layerId = PcbConvergenceLayerModel.#firstInteger([
+            layer?.layerId,
+            layer?.id,
+            layer?.index,
+            layer?.number
+        ])
+        const legacyLayerId = PcbConvergenceLayerModel.#firstInteger([
+            layer?.legacyLayerId,
+            layer?.legacyId
+        ])
+        const displayName = String(
+            layer?.displayName || layer?.name || layer?.label || ''
+        )
+        return {
+            layerId,
+            legacyLayerId,
+            layerKey: Number.isInteger(layerId)
+                ? 'L' + layerId
+                : PcbConvergenceLayerModel.normalize(displayName),
+            displayName,
+            role:
+                layer?.role ||
+                layer?.layerRole ||
+                PcbConvergenceLayerModel.#inferRole(
+                    displayName,
+                    legacyLayerId ?? layerId
+                )
+        }
+    }
+
+    /**
+     * Resolves a broad layer role.
+     * @param {string} name Layer name.
+     * @param {number | undefined} layerId Layer id.
+     * @returns {string}
+     */
+    static #inferRole(name, layerId) {
+        if (PcbLayerGroups.isMechanical(layerId)) return 'mechanical'
+        if (PcbLayerGroups.isOverlay(layerId)) return 'overlay'
+        if (PcbLayerGroups.isCopper(layerId)) return 'copper'
+        const normalized = name.toLowerCase()
+        if (/mechanical|dimension|drawing/u.test(normalized)) {
+            return 'mechanical'
+        }
+        if (/assembly|\basm\b/u.test(normalized)) return 'assembly'
+        if (/notes?|document|courtyard|crtyd/u.test(normalized)) {
+            return 'documentation'
+        }
+        return 'other'
+    }
+
+    /**
+     * Returns the first integer in a value list.
+     * @param {unknown[]} values Candidate values.
+     * @returns {number | undefined}
+     */
+    static #firstInteger(values) {
+        for (const value of values) {
+            const number = Number(value)
+            if (Number.isInteger(number)) return number
+        }
+        return undefined
+    }
+}

package/src/convergence/PcbDrawingTextComposite.mjs

@@ -0,0 +1,121 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbTextPrimitiveRenderer } from '../ui/PcbTextPrimitiveRenderer.mjs'
+import { PcbConvergenceLayerModel } from './PcbConvergenceLayerModel.mjs'
+
+/**
+ * Adds side-correct drawing annotations outside the board-only text clip.
+ */
+export class PcbDrawingTextComposite {
+    /**
+     * Adds mechanical and documentation text to rendered PCB markup.
+     * @param {string} markup Historical renderer markup.
+     * @param {object} documentModel PCB document.
+     * @param {{ side?: 'top' | 'bottom' }} [options] Render options.
+     * @returns {string}
+     */
+    static apply(markup, documentModel, options = {}) {
+        const pcb = documentModel?.pcb
+        if (!pcb) return markup
+        const side = options?.side === 'bottom' ? 'bottom' : 'top'
+        const lookup = PcbConvergenceLayerModel.buildLookup(documentModel)
+        const drawingLayers = lookup.layers.filter((layer) =>
+            PcbConvergenceLayerModel.isDrawingLayerForSide(layer, side)
+        )
+        if (!drawingLayers.length) return markup
+
+        const selectorLayers = drawingLayers
+            .filter((layer) => Number.isInteger(layer.layerId))
+            .map((layer) => ({
+                layerId: layer.layerId,
+                name: 'Top Overlay'
+            }))
+        const texts = PcbTextPrimitiveRenderer.select(
+            selectorLayers,
+            pcb.texts || [],
+            'top'
+        )
+        if (!texts.length) return markup
+
+        const textMarkup = PcbTextPrimitiveRenderer.render(texts, {
+            semanticContext: PcbDrawingTextComposite.#semanticContext(
+                pcb,
+                lookup
+            )
+        })
+        return PcbDrawingTextComposite.#insertDrawingGroup(markup, textMarkup)
+    }
+
+    /**
+     * Builds the public semantic context consumed by the historical text
+     * primitive renderer.
+     * @param {object} pcb PCB model.
+     * @param {{ byId: Map<number, object> }} lookup Layer lookup.
+     * @returns {object}
+     */
+    static #semanticContext(pcb, lookup) {
+        return {
+            layersById: lookup.byId,
+            primitiveIndexes: {
+                texts: new Map(
+                    (pcb.texts || []).map((text, index) => [text, index])
+                )
+            },
+            netByIndex: new Map(
+                (pcb.nets || []).map((net) => [Number(net.netIndex), net])
+            ),
+            netClassNamesByNetName: new Map(),
+            componentsByIndex: new Map(
+                (pcb.components || []).map((component) => [
+                    Number(component.componentIndex),
+                    component
+                ])
+            )
+        }
+    }
+
+    /**
+     * Inserts one un-clipped group immediately after the ordinary text group.
+     * @param {string} markup SVG panel markup.
+     * @param {string} textMarkup Drawing text markup.
+     * @returns {string}
+     */
+    static #insertDrawingGroup(markup, textMarkup) {
+        const start = markup.indexOf('<g class="pcb-texts"')
+        if (start < 0) return markup
+        const openEnd = markup.indexOf('>', start)
+        const end = PcbDrawingTextComposite.#groupEnd(markup, openEnd + 1)
+        if (openEnd < 0 || end < 0) return markup
+        const openTag = markup.slice(start, openEnd + 1)
+        const transform = openTag.match(/\stransform="[^"]*"/u)?.[0] || ''
+        const group =
+            '<g class="pcb-drawing-texts"' +
+            transform +
+            '>' +
+            textMarkup +
+            '</g>'
+        return markup.slice(0, end) + group + markup.slice(end)
+    }
+
+    /**
+     * Finds the offset after the matching close tag for one SVG group.
+     * @param {string} markup SVG markup.
+     * @param {number} contentStart Group content offset.
+     * @returns {number}
+     */
+    static #groupEnd(markup, contentStart) {
+        const pattern = /<g\b[^>]*>|<\/g>/gu
+        let depth = 1
+        pattern.lastIndex = contentStart
+        for (
+            let match = pattern.exec(markup);
+            match;
+            match = pattern.exec(markup)
+        ) {
+            depth += match[0].startsWith('</') ? -1 : 1
+            if (depth === 0) return pattern.lastIndex
+        }
+        return -1
+    }
+}

package/src/convergence/PcbSvgRenderer.mjs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { PcbSvgRenderer as LegacyPcbSvgRenderer } from '../ui/PcbSvgRenderer.mjs'
+import { PcbDrawingTextComposite } from './PcbDrawingTextComposite.mjs'
+import { PcbVisibleLayerViewport } from './PcbVisibleLayerViewport.mjs'
 
 /**
  * Renders native Altium PCB models through the preserved historical renderer
@@ -19,7 +21,22 @@ export class PcbSvgRenderer {
      * @returns {string} Rendered SVG panel markup.
      */
     static render(documentModel, options = {}) {
-        const markup = LegacyPcbSvgRenderer.render(documentModel, options)
+        const historicalMarkup = LegacyPcbSvgRenderer.render(
+            documentModel,
+            options
+        )
+        const drawingMarkup = PcbDrawingTextComposite.apply(
+            historicalMarkup,
+            documentModel,
+            options
+        )
+        const markup = PcbVisibleLayerViewport.apply(
+            drawingMarkup,
+            documentModel,
+            options,
+            (filteredDocument, filteredOptions) =>
+                LegacyPcbSvgRenderer.render(filteredDocument, filteredOptions)
+        )
         const subsurfacePadIndexes = PcbSvgRenderer.#subsurfacePadIndexes(
             documentModel,
             options

package/src/convergence/PcbVisibleLayerViewport.mjs

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbConvergenceLayerModel } from './PcbConvergenceLayerModel.mjs'
+
+/**
+ * Replaces PCB viewport bounds with bounds rendered from visible layers.
+ */
+export class PcbVisibleLayerViewport {
+    /**
+     * Applies visible-layer viewBox bounds while retaining original SVG markup.
+     * @param {string} markup Complete SVG panel markup.
+     * @param {object} documentModel PCB document.
+     * @param {{ hiddenLayers?: (string | number)[] }} options Render options.
+     * @param {(documentModel: object, options: object) => string} renderHistorical Historical render callback.
+     * @returns {string}
+     */
+    static apply(markup, documentModel, options, renderHistorical) {
+        const hidden = new Set(
+            (Array.isArray(options?.hiddenLayers) ? options.hiddenLayers : [])
+                .map(PcbConvergenceLayerModel.normalize)
+                .filter(Boolean)
+        )
+        if (!hidden.size || !documentModel?.pcb) return markup
+
+        const filteredDocument = PcbVisibleLayerViewport.#filterDocument(
+            documentModel,
+            hidden
+        )
+        const filteredMarkup = renderHistorical(filteredDocument, {
+            ...options,
+            hiddenLayers: undefined
+        })
+        const viewBox = filteredMarkup.match(
+            /<svg class="pcb-svg" viewBox="([^"]+)"/u
+        )?.[1]
+        if (!viewBox) return markup
+
+        return markup.replace(
+            /(<svg class="pcb-svg"[^>]*\sviewBox=")[^"]+("[^>]*>)/u,
+            '$1' + viewBox + '$2'
+        )
+    }
+
+    /**
+     * Creates a shallow document clone with hidden-layer primitives removed.
+     * @param {object} documentModel Source document.
+     * @param {Set<string>} hidden Hidden layer aliases.
+     * @returns {object}
+     */
+    static #filterDocument(documentModel, hidden) {
+        const pcb = documentModel.pcb
+        const lookup = PcbConvergenceLayerModel.buildLookup(documentModel)
+        const visible = (primitive) =>
+            !PcbVisibleLayerViewport.#isHidden(primitive, lookup, hidden)
+        const nearBoard = (component) =>
+            PcbVisibleLayerViewport.#isComponentNearBoard(
+                component,
+                pcb.boardOutline
+            )
+        const filterKeys = [
+            'polygons',
+            'fills',
+            'tracks',
+            'arcs',
+            'regions',
+            'shapeBasedRegions',
+            'vias',
+            'pads',
+            'texts',
+            'dimensions'
+        ]
+        const filteredPcb = { ...pcb }
+        for (const key of filterKeys) {
+            filteredPcb[key] = (pcb[key] || []).filter(visible)
+        }
+        filteredPcb.components = (pcb.components || []).filter(
+            (component) => visible(component) && nearBoard(component)
+        )
+        return { ...documentModel, pcb: filteredPcb }
+    }
+
+    /**
+     * Returns true when one primitive belongs to a hidden layer.
+     * @param {object} primitive Primitive record.
+     * @param {object} lookup Layer lookup.
+     * @param {Set<string>} hidden Hidden aliases.
+     * @returns {boolean}
+     */
+    static #isHidden(primitive, lookup, hidden) {
+        const layer = PcbConvergenceLayerModel.layerForPrimitive(
+            primitive,
+            lookup
+        )
+        const aliases = [
+            ...PcbConvergenceLayerModel.aliases(layer),
+            primitive?.layer,
+            primitive?.layerName,
+            primitive?.layerId,
+            primitive?.layerCode
+        ]
+            .map(PcbConvergenceLayerModel.normalize)
+            .filter(Boolean)
+        return aliases.some((alias) => hidden.has(alias))
+    }
+
+    /**
+     * Returns true for placements near enough to affect a board-first fit.
+     * @param {object} component Component placement.
+     * @param {object} outline Board outline.
+     * @returns {boolean}
+     */
+    static #isComponentNearBoard(component, outline) {
+        const x = Number(component?.x)
+        const y = Number(component?.y)
+        if (!Number.isFinite(x) || !Number.isFinite(y)) return true
+        const minX = Number(outline?.minX || 0)
+        const minY = Number(outline?.minY || 0)
+        const maxX = minX + Number(outline?.widthMil || 0)
+        const maxY = minY + Number(outline?.heightMil || 0)
+        const tolerance = 240
+        return (
+            x >= minX - tolerance &&
+            x <= maxX + tolerance &&
+            y >= minY - tolerance &&
+            y <= maxY + tolerance
+        )
+    }
+}