altium-toolkit 1.4.4 → 1.4.6

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

@@ -0,0 +1,23 @@
+# altium-toolkit 1.4.6
+
+Version 1.4.6 preserves anisotropic ROUND/CIRCLE SMT pad dimensions when
+converting Altium renderer data to Circuit JSON.
+
+## Anisotropic ROUND/CIRCLE SMT projection
+
+- Unequal positive dimensions become dimension-preserving `pill` geometry, or
+  `rotated_pill` when the authored rotation is meaningful.
+- Zero-hole SMT filtering and stable source ordering keep through-hole and
+  unrelated pads unchanged.
+- Equal-diameter ROUND/CIRCLE pads retain their existing circle geometry.
+
+## Verification
+
+- Public `Parser.parse()` regression coverage exercises schematic and PCB-only models,
+  mixed SMT/through-hole order, rotation tolerance, and metadata preservation.
+- The complete test suite, performance check, feature-preservation check,
+  formatting check, and npm publish dry run passed for this release metadata.
+
+## Contributor
+
+Thanks to Ahmed Alshaybani for the original anisotropic pad projection work.

package/package.json

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

package/spec/2026-08-21-anisotropic-round-smt-pad-projection-design.md

@@ -0,0 +1,84 @@
+# Anisotropic Round SMT Pad Projection Design
+
+## Goal
+
+Preserve the authored X/Y geometry of every Altium surface-mount pad whose
+native shape is `ROUND` or `CIRCLE` and whose two positive dimensions differ.
+The canonical CircuitJSON model must expose these pads as `pill` or
+`rotated_pill` records instead of expanding them into overlapping circles.
+
+## Current Behavior and Root Cause
+
+The historical CircuitJSON adapter classifies all Altium `ROUND` pads as
+circles and assigns a radius derived from the larger dimension. That behavior
+is part of the provenance-pinned 1.1.41 implementation and must remain
+unchanged. The public convergence layer currently forwards the lossy SMT pad
+records without restoring the native dimensions.
+
+## Chosen Approach
+
+Apply a source-neutral correction in `AltiumCircuitJsonProjection` after the
+historical adapter has produced its immutable rows. Pair canonical
+`pcb_smtpad` rows with native surface-mount pads in their deterministic source
+order. For native round pads with unequal positive X/Y dimensions, replace only
+the canonical geometry fields:
+
+- use `pill` when rotation is effectively zero;
+- use `rotated_pill` and `ccw_rotation` otherwise;
+- retain width and height in millimetres;
+- set the end radius to half the shorter dimension;
+- preserve identifiers, ownership, layer, port, net, position, and metadata.
+
+Use the same small rotation tolerance as the existing canonical adapter so
+floating-point noise does not create a rotated shape. Equal round pads and all
+other pad shapes remain byte-for-byte unchanged.
+
+## Alternatives Considered
+
+1. Modify the historical adapter. This is smaller locally but violates the
+   frozen native source contract and its feature-preservation gates.
+2. Add an ECAD Forge renderer workaround. This would leave canonical data
+   incorrect for every other consumer and duplicate library behavior in the
+   host app.
+3. Correct the convergence projection. This keeps the historical extension
+   stable while fixing the public canonical contract for all consumers and is
+   therefore the selected approach.
+
+## Testing
+
+Add repo-owned synthetic tests without committing any supplied native board:
+
+- verify the public `Parser.parse()` result for unrotated and rotated
+  anisotropic round SMT pads;
+- verify equal round pads stay circles;
+- verify a through-hole pad interleaved between SMT pads does not disturb the
+  native-to-canonical pairing;
+- verify near-zero rotation uses an ordinary pill;
+- run the complete library test, format, performance, package dry-run, and
+  feature-preservation gates;
+- verify the public parser against the existing local NodeMCU demo as
+  non-committed evidence that all 16 affected SMT pads retain their geometry.
+
+The new test file credits both the original contributor and the project
+copyright holder and remains GPL-3.0-or-later.
+
+## Release and Deployment
+
+Release the fix as the next patch of `altium-toolkit`, preserving the original
+pull-request contributor in commit attribution and release notes. Publish the
+GitHub release and npm package, then verify the registry version and `latest`
+tag.
+
+Update ECAD Forge through npm to the latest published versions of all five
+toolkit dependencies, bump the app patch version, synchronize structured data,
+run the full test, structured-data, static-build, and formatting gates, commit
+and push `main`, create the GitHub release, watch the deployment workflow to a
+successful conclusion, and verify the production app version and corrected pad
+geometry.
+
+## Non-Goals
+
+Anisotropic through-hole copper and slot-hole representation is a related but
+separate canonical-model issue because it requires preserving both the outer
+copper aperture and drill geometry. This release does not silently change that
+contract.

package/spec/2026-08-21-anisotropic-round-smt-pad-projection-plan.md

@@ -0,0 +1,91 @@
+# Anisotropic ROUND SMT Pad Projection Implementation Plan
+
+> **Execution note:** Follow the `superpowers:executing-plans` skill and verify each checkpoint before continuing.
+
+**Goal:** Preserve anisotropic Altium ROUND/CIRCLE SMT pad dimensions by projecting them to Circuit JSON pill geometry, release the fix in `altium-toolkit`, and deploy ECAD Forge with current releases of all toolkit dependencies.
+
+**Architecture:** Keep the vendored parser adapter unchanged. Add a convergence-layer projection after native schematic projection, pairing adapted pads with canonical renderer pads by stable order. Only zero-hole ROUND/CIRCLE pads with unequal positive dimensions are reclassified. Use a small angular epsilon so floating-point noise near zero does not turn a horizontal pill into a rotated pill.
+
+**Tech stack:** Node.js ESM, Node test runner, npm, GitHub CLI, GitHub Actions.
+
+---
+
+## Task 1: Add a public-parser regression test
+
+**Files:**
+
+- Create: `tests/canonical-pcb-round-pad-projection.test.mjs`
+- Reference: `src/Parser.mjs`
+- Reference: `src/AltiumParser.mjs`
+
+1. Add a synthetic renderer-model fixture by temporarily replacing `AltiumParser.parseArrayBufferToRendererModel`.
+2. Exercise `Parser.parse()` rather than the convergence helper directly.
+3. Include, in mixed renderer order:
+    - an unequal ROUND SMT pad at zero rotation;
+    - a through-hole ROUND pad between SMT pads;
+    - an unequal ROUND SMT pad with near-zero rotation;
+    - an unequal ROUND SMT pad at 90 degrees;
+    - an equal-diameter ROUND SMT pad.
+4. Assert the public Circuit JSON output contains `pill`, `pill`, `rotated_pill`, and `circle` respectively, with both anisotropic dimensions preserved.
+5. Run the focused test and confirm it fails because the unequal pads are still circles.
+6. Commit the failing regression test with contributor attribution.
+
+## Task 2: Implement the convergence projection
+
+**Files:**
+
+- Modify: `src/convergence/AltiumCircuitJsonProjection.mjs`
+- Test: `tests/canonical-pcb-round-pad-projection.test.mjs`
+
+1. Add a private projection method that filters native renderer pads to SMT pads and pairs them with canonical SMT pads in stable order.
+2. For renderer `ROUND`/`CIRCLE` pads with zero hole, positive unequal X/Y sizes, update the canonical pad shape:
+    - `pill` when absolute rotation is at most `1e-6` degrees;
+    - `rotated_pill` otherwise.
+3. Set `radius = min(width, height) / 2`, preserve `width` and `height`, and leave IDs, layers, positions, rotations, and metadata untouched.
+4. Call the projection after the existing native schematic projection and before model construction.
+5. Run the focused test and confirm it passes.
+6. Run `npm test`, `npm run check:format`, `npm run test:performance`, and `npm run test:features`.
+7. Parse the noncommitted NodeMCU sample on main and on the fixed tree; verify all 16 previously circular unequal ROUND SMT pads become dimension-preserving pills without changing the total SMT-pad count.
+8. Commit the implementation with `Co-authored-by: Ahmed Alshaybani`.
+
+## Task 3: Review and release `altium-toolkit`
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Create: `docs/release-notes-v1.4.6.md`
+
+1. Request an independent code review of the full change from the original main revision.
+2. Address all valid findings and rerun affected tests.
+3. Bump the package patch version to `1.4.6` without creating an automatic tag.
+4. Add concise release notes describing the generalized ROUND/CIRCLE SMT projection, public-parser regression coverage, and contributor credit.
+5. Run fresh release gates: `npm test`, `npm run check:format`, `npm run test:performance`, `npm run test:features`, and `npm publish --dry-run`.
+6. Commit the release metadata and push `main`.
+7. Create and verify GitHub release `v1.4.6`.
+8. Publish `altium-toolkit@1.4.6` to npm through web authentication and verify the registry version and `latest` dist-tag.
+9. Comment on PR #1 with the adapted release outcome and contributor credit.
+
+## Task 4: Update and verify ECAD Forge
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify generated structured-data HTML under `src/` if the sync command changes it
+
+1. Query npm for the latest versions of `gerber-toolkit`, `circuitjson-toolkit`, `altium-toolkit`, `kicad-toolkit`, and `pcb-scene3d-viewer`.
+2. Install all five current releases explicitly, ensuring `altium-toolkit@1.4.6` is selected.
+3. Bump the ECAD Forge patch version to `1.13.22` without creating an automatic tag.
+4. Run `npm run sync:structured-data` and inspect the generated changes.
+5. Run `npm test`, `npm run check:structured-data`, `npm run build:static`, and the repository format check if present.
+6. Commit only the intended dependency, version, and generated structured-data changes.
+
+## Task 5: Release, deploy, and verify ECAD Forge
+
+1. Push ECAD Forge `main`.
+2. Create and verify GitHub release `v1.13.22` with concise release notes.
+3. Resolve the `Deploy to FTP (main)` workflow run associated with the pushed commit and watch it to a successful conclusion.
+4. Verify the production site responds successfully and reports the new app version.
+5. Load an Altium PCB through the production app and confirm the affected anisotropic ROUND SMT pads render as elongated pads rather than circles.
+6. Confirm both repositories are clean and summarize exact commits, releases, npm versions, test results, deployment conclusion, and production evidence.

package/src/convergence/AltiumCircuitJsonProjection.mjs

@@ -25,11 +25,21 @@ export class AltiumCircuitJsonProjection {
      */
     static project(adapted, native) {
         const nativeSchematic = native?.schematic
-        if (!nativeSchematic) return [...adapted]
+        if (!nativeSchematic) {
+            return AltiumCircuitJsonProjection.#projectPcbSmtPadShapes(
+                adapted,
+                native?.pcb
+            )
+        }
         const schematic =
             AltiumCircuitJsonProjection.#schematicWithSourceTypes(
                 nativeSchematic
             )
+        const elementsWithProjectedPadShapes =
+            AltiumCircuitJsonProjection.#projectPcbSmtPadShapes(
+                adapted,
+                native?.pcb
+            )
 
         const sourceFormat = Primitives.sourceFormat(native)
         const idScope = Primitives.idScope(native, sourceFormat)
@@ -53,18 +63,18 @@ export class AltiumCircuitJsonProjection {
             ])
         )
         const legacySchematicSourceTraceIds = new Set(
-            adapted
+            elementsWithProjectedPadShapes
                 .filter((element) => element?.type === 'schematic_trace')
                 .map((element) => String(element.source_trace_id || ''))
                 .filter(Boolean)
         )
         const protectedPcbSourceTraceIds = new Set(
-            adapted
+            elementsWithProjectedPadShapes
                 .filter((element) => element?.type === 'pcb_trace')
                 .map((element) => String(element.source_trace_id || ''))
                 .filter(Boolean)
         )
-        const model = adapted
+        const model = elementsWithProjectedPadShapes
             .filter((element) =>
                 AltiumCircuitJsonProjection.#preservesAdaptedElement(
                     element,
@@ -109,6 +119,79 @@ export class AltiumCircuitJsonProjection {
         )
     }
 
+    /**
+     * Restores native dimensions for unequal round SMT pads after the frozen
+     * historical adapter has classified them as circles.
+     * @param {object[]} adapted Historical adapter output.
+     * @param {Record<string, any> | undefined} pcb Native PCB model.
+     * @returns {object[]} Canonical rows with projected SMT pad shapes.
+     */
+    static #projectPcbSmtPadShapes(adapted, pcb) {
+        const nativeSmtPads = Primitives.array(pcb?.pads).filter(
+            (pad) => !Primitives.isThroughHolePad(pad)
+        )
+        let smtPadIndex = 0
+
+        return adapted.map((element) => {
+            if (element?.type !== 'pcb_smtpad') return element
+
+            const nativePad = nativeSmtPads[smtPadIndex]
+            smtPadIndex += 1
+            if (
+                !AltiumCircuitJsonProjection.#isAnisotropicRoundSmtPad(
+                    nativePad
+                )
+            ) {
+                return element
+            }
+
+            const width = Primitives.milNumber(
+                nativePad.sizeTopX || nativePad.sizeX || nativePad.width,
+                0
+            )
+            const height = Primitives.milNumber(
+                nativePad.sizeTopY || nativePad.sizeY || nativePad.height,
+                0
+            )
+            const rotation =
+                Primitives.number(
+                    nativePad.rotation || nativePad.holeRotation,
+                    0
+                ) || 0
+            const hasRotation = Math.abs(rotation) > 0.000001
+
+            return {
+                ...element,
+                shape: hasRotation ? 'rotated_pill' : 'pill',
+                width,
+                height,
+                radius: Primitives.round(Math.min(width, height) / 2),
+                ...(hasRotation ? { ccw_rotation: rotation } : {})
+            }
+        })
+    }
+
+    /**
+     * Returns whether a native SMT pad requires a dimension-preserving pill.
+     * @param {Record<string, any> | undefined} pad Native PCB pad.
+     * @returns {boolean} Whether the native pad is an unequal round SMT pad.
+     */
+    static #isAnisotropicRoundSmtPad(pad) {
+        const shape = String(
+            pad?.shapeTopName || pad?.shapeName || pad?.shape || ''
+        )
+            .trim()
+            .toLowerCase()
+        if (shape !== 'round' && shape !== 'circle') return false
+
+        const width =
+            Primitives.number(pad?.sizeTopX ?? pad?.sizeX ?? pad?.width, 0) || 0
+        const height =
+            Primitives.number(pad?.sizeTopY ?? pad?.sizeY ?? pad?.height, 0) ||
+            0
+        return width > 0 && height > 0 && width !== height
+    }
+
     /**
      * Classifies native Altium record-27 wire segments at the convergence
      * boundary while preserving explicit source-neutral classifications.

package/src/convergence/PcbSideResolvedRenderModel.mjs

@@ -123,10 +123,14 @@ export class PcbSideResolvedRenderModel {
         const layerId = PcbSideResolvedRenderModel.#effectivePadLayerId(pad)
         const apertureSide =
             layerId === 1 ? 'front' : layerId === 32 ? 'back' : side
-        if (apertureSide !== 'back') return { ...pad }
+        const projectedPad = {
+            ...pad,
+            copperRenderGroup: apertureSide === side ? 'surface' : 'subsurface'
+        }
+        if (apertureSide !== 'back') return projectedPad
 
         return {
-            ...pad,
+            ...projectedPad,
             sizeTopX: PcbSideResolvedRenderModel.#firstFiniteValue(
                 pad.sizeBottomX,
                 pad.sizeMidX,

package/src/convergence/PcbSvgRenderer.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSvgRenderer as LegacyPcbSvgRenderer } from '../ui/PcbSvgRenderer.mjs'
+
+/**
+ * Renders native Altium PCB models through the preserved historical renderer
+ * while applying convergence-owned copper grouping semantics.
+ */
+export class PcbSvgRenderer {
+    static #SUBSURFACE_GROUP = '<g class="pcb-copper pcb-copper--subsurface">'
+    static #SURFACE_GROUP = '<g class="pcb-copper pcb-copper--surface">'
+
+    /**
+     * Renders one native Altium PCB document as SVG markup.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @param {Record<string, any>} [options] Historical renderer options.
+     * @returns {string} Rendered SVG panel markup.
+     */
+    static render(documentModel, options = {}) {
+        const markup = LegacyPcbSvgRenderer.render(documentModel, options)
+        const subsurfacePadIndexes = PcbSvgRenderer.#subsurfacePadIndexes(
+            documentModel,
+            options
+        )
+        if (subsurfacePadIndexes.length === 0) return markup
+
+        return PcbSvgRenderer.#movePadsToSubsurfaceGroup(
+            markup,
+            subsurfacePadIndexes
+        )
+    }
+
+    /**
+     * Renders one deterministic SVG entry per physical or primitive layer.
+     * Layer exports intentionally preserve the historical layer-only output.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @returns {{ layerId?: number, layerKey: string, displayName: string, role: string, svg: string }[]}
+     */
+    static renderLayerSvgs(documentModel) {
+        return LegacyPcbSvgRenderer.renderLayerSvgs(documentModel)
+    }
+
+    /**
+     * Finds pad indexes whose copper must share the contextual copper group.
+     * Layer-only exports do not use composite surface/subsurface grouping.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @param {Record<string, any>} options Historical renderer options.
+     * @returns {number[]} Stable pad indexes.
+     */
+    static #subsurfacePadIndexes(documentModel, options) {
+        if (options?.layerView) return []
+
+        return (documentModel?.pcb?.pads || [])
+            .map((pad, index) =>
+                pad?.copperRenderGroup === 'subsurface' ? index : -1
+            )
+            .filter((index) => index >= 0)
+    }
+
+    /**
+     * Moves contextual pad groups into the same SVG group as contextual traces
+     * so the browser composites both primitives with one shared opacity.
+     * @param {string} markup Historical renderer markup.
+     * @param {number[]} padIndexes Stable pad indexes to relocate.
+     * @returns {string} Copper-group-aware markup.
+     */
+    static #movePadsToSubsurfaceGroup(markup, padIndexes) {
+        const subsurfaceStart = markup.indexOf(PcbSvgRenderer.#SUBSURFACE_GROUP)
+        const surfaceStart = markup.indexOf(PcbSvgRenderer.#SURFACE_GROUP)
+        if (subsurfaceStart < 0 || surfaceStart <= subsurfaceStart) {
+            return markup
+        }
+
+        const subsurfaceClose = markup.lastIndexOf('</g>', surfaceStart)
+        if (subsurfaceClose < subsurfaceStart) return markup
+
+        let remainingMarkup = markup
+        const relocatedPads = []
+        for (const padIndex of padIndexes) {
+            const result = PcbSvgRenderer.#extractPadGroup(
+                remainingMarkup,
+                padIndex,
+                surfaceStart
+            )
+            if (!result) continue
+            remainingMarkup = result.markup
+            relocatedPads.push(result.padMarkup)
+        }
+        if (relocatedPads.length === 0) return markup
+
+        const updatedSurfaceStart = remainingMarkup.indexOf(
+            PcbSvgRenderer.#SURFACE_GROUP
+        )
+        const updatedSubsurfaceClose = remainingMarkup.lastIndexOf(
+            '</g>',
+            updatedSurfaceStart
+        )
+        return (
+            remainingMarkup.slice(0, updatedSubsurfaceClose) +
+            relocatedPads.join('') +
+            remainingMarkup.slice(updatedSubsurfaceClose)
+        )
+    }
+
+    /**
+     * Extracts one top-level pad group from the historical surface group.
+     * Pad groups contain only leaf SVG shapes, so their first closing group is
+     * also the matching closing tag.
+     * @param {string} markup Current renderer markup.
+     * @param {number} padIndex Stable pad index.
+     * @param {number} minimumStart Earliest valid surface-group position.
+     * @returns {{ markup: string, padMarkup: string } | null} Extraction result.
+     */
+    static #extractPadGroup(markup, padIndex, minimumStart) {
+        const elementKey = 'data-element-key="pcb-pad-' + padIndex + '"'
+        const keyStart = markup.indexOf(elementKey, minimumStart)
+        if (keyStart < 0) return null
+
+        const groupStart = markup.lastIndexOf('<g', keyStart)
+        const groupEndStart = markup.indexOf('</g>', keyStart)
+        if (groupStart < minimumStart || groupEndStart < 0) return null
+
+        const groupEnd = groupEndStart + '</g>'.length
+        return {
+            markup: markup.slice(0, groupStart) + markup.slice(groupEnd),
+            padMarkup: markup.slice(groupStart, groupEnd)
+        }
+    }
+}

package/src/extensions.mjs

@@ -4,6 +4,7 @@
 export * from 'circuitjson-toolkit/extensions'
 
 export { AltiumExtensionResolver } from './convergence/AltiumExtensionResolver.mjs'
+export { PcbSvgRenderer } from './convergence/PcbSvgRenderer.mjs'
 export { SchematicSvgRenderer } from './convergence/SchematicSvgRenderer.mjs'
 export * from './legacy-parser.mjs'
 export * from './legacy-netlist-query.mjs'

package/src/styles/altium-renderers.css

@@ -270,6 +270,10 @@
     fill: var(--pcb-copper-solid-fill);
 }
 
+.pcb-copper--subsurface .pcb-pad--smd .pcb-pad__ring {
+    fill: var(--pcb-subsurface-track-color);
+}
+
 .pcb-footprint-fill {
     fill: var(--pcb-footprint-fill);
 }