altium-toolkit 1.4.1 → 1.4.3

package/README.md

@@ -51,6 +51,12 @@ traces across input edits without changing parser, document, renderer, or
 native-extension contracts. See the
 [1.4.1 release notes](docs/release-notes-v1.4.1.md).
 
+Version 1.4.2 rebuilds project-resolved canonical documents through the
+toolkit-owned validation path and CircuitJSON Toolkit 1.4.2. Large native
+extension graphs retain their proven ownership instead of repeating defensive
+binary classification. See the
+[1.4.2 release notes](docs/release-notes-v1.4.2.md).
+
 Default `extensions: 'canonical'` keeps compact Altium summary metadata.
 Request the complete native read model with `extensions: 'full'`,
 `preserveRaw: true`, or `extensions: ['altium.native-model']`. Project batches
@@ -218,6 +224,7 @@ const legacyCircuitJson = AltiumParser.parseArrayBuffer(file.name, arrayBuffer)
 - [API](docs/api.md)
 - [Capabilities](docs/capabilities.md)
 - [Migration from 1.1.41](docs/migration.md)
+- [1.4.2 release notes](docs/release-notes-v1.4.2.md)
 - [1.4.1 release notes](docs/release-notes-v1.4.1.md)
 - [1.4.0 release notes](docs/release-notes-v1.4.0.md)
 - [1.3.0 release notes](docs/release-notes-v1.3.0.md)

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

@@ -0,0 +1,27 @@
+# altium-toolkit 1.4.2
+
+Version 1.4.2 removes redundant immutable-extension validation from canonical
+project document rebuilding. Parser output, project resolution, extension
+selection, and renderer contracts remain unchanged.
+
+## Faster project resolution
+
+- `AltiumProjectDocumentResolver` rebuilds changed canonical documents through
+  the shared toolkit-owned `DocumentResult` boundary.
+- Already proven and frozen native extension graphs retain their identity when
+  project parameters update canonical or retained-native schematic text.
+- Defensive binary classification is no longer repeated across every record of
+  a large owned extension graph.
+
+## Dependency
+
+- `circuitjson-toolkit` 1.4.2 supplies the owned-extension reuse and atomic
+  cooperative structured-clone finalization behavior.
+- Arbitrary caller data still uses the defensive shared validation path.
+
+## Verification
+
+- An inspector-backed regression bounds exception-driven binary brand probes
+  during a project rebuild.
+- The complete package suite, formatting, performance, feature-preservation,
+  and npm dry-run gates verify the release.

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

@@ -0,0 +1,20 @@
+# altium-toolkit 1.4.3
+
+Version 1.4.3 keeps PCB fabrication details on their authored board side when
+preparing side-resolved render models.
+
+## Side-correct PCB fabrication details
+
+- Front-side views retain top overlay, paste, and solder-mask primitives while
+  excluding their bottom-side counterparts.
+- Back-side views retain bottom overlay, paste, and solder-mask primitives while
+  excluding their top-side counterparts.
+- Shared mechanical and documentation layers remain visible on both sides.
+- Copper projection continues to use the established native Altium behavior.
+
+## Verification
+
+- A side-resolution regression covers fills, tracks, arcs, regions,
+  shape-based regions, and board regions with neutral-layer preservation.
+- The complete package suite, formatting, and npm dry-run gates verify the
+  release.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.4.1",
+    "version": "1.4.3",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",
@@ -67,7 +67,7 @@
         "check:features": "node scripts/check-feature-preservation.mjs"
     },
     "dependencies": {
-        "circuitjson-toolkit": "^1.4.1",
+        "circuitjson-toolkit": "^1.4.2",
         "fflate": "^0.8.2"
     },
     "devDependencies": {

package/src/convergence/AltiumProjectDocumentResolver.mjs

@@ -239,13 +239,13 @@ export class AltiumProjectDocumentResolver {
     }
 
     /**
-     * Rebuilds one canonical document through the validating shared boundary.
+     * Rebuilds one canonical document through the toolkit-owned shared boundary.
      * @param {object} document Existing canonical document.
      * @param {{ model?: object[], extensions?: object, statistics?: object }} fields Replacements.
      * @returns {object} Proven immutable document.
      */
     static #rebuild(document, fields) {
-        return DocumentResult.createValidated(
+        return DocumentResult.createValidatedOwned(
             {
                 id: document.id,
                 model: fields.model || document.model,

package/src/convergence/PcbSideResolvedRenderModel.mjs

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbLayerGroups } from '../core/altium/PcbLayerGroups.mjs'
+import { PcbSideResolvedRenderModel as HistoricalPcbSideResolvedRenderModel } from '../ui/PcbSideResolvedRenderModel.mjs'
+
+/**
+ * Adds side-correct fabrication detail filtering around the preserved native
+ * Altium side projection.
+ */
+export class PcbSideResolvedRenderModel {
+    /**
+     * Resolves a normalized PCB model for the requested board side.
+     * @param {object | null} board
+     * @param {'front' | 'back' | { side?: 'front' | 'back' }} [options]
+     * @returns {object | null}
+     */
+    static resolve(board, options = {}) {
+        const side = PcbSideResolvedRenderModel.#normalizeSide(options)
+        const resolved = HistoricalPcbSideResolvedRenderModel.resolve(
+            board,
+            options
+        )
+        if (!resolved?.pcb) return resolved
+
+        const pcb = resolved.pcb
+        return {
+            ...resolved,
+            pcb: {
+                ...pcb,
+                fills: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.fills,
+                    side
+                ),
+                tracks: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.tracks,
+                    side
+                ),
+                arcs: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.arcs,
+                    side
+                ),
+                regions: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.regions,
+                    side
+                ),
+                shapeBasedRegions: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.shapeBasedRegions,
+                    side
+                ),
+                boardRegions: PcbSideResolvedRenderModel.#filterPrimitives(
+                    pcb.boardRegions,
+                    side
+                )
+            }
+        }
+    }
+
+    /**
+     * Checks whether a primitive belongs to an Altium copper signal layer.
+     * @param {object | null} primitive
+     * @returns {boolean}
+     */
+    static isCopperPrimitive(primitive) {
+        return HistoricalPcbSideResolvedRenderModel.isCopperPrimitive(primitive)
+    }
+
+    /**
+     * Normalizes the caller side option.
+     * @param {'front' | 'back' | { side?: 'front' | 'back' }} options
+     * @returns {'front' | 'back'}
+     */
+    static #normalizeSide(options) {
+        if (options === 'back') return 'back'
+        if (options && typeof options === 'object' && options.side === 'back') {
+            return 'back'
+        }
+        return 'front'
+    }
+
+    /**
+     * Filters one primitive collection to the requested surface.
+     * @param {readonly object[] | undefined} primitives
+     * @param {'front' | 'back'} side
+     * @returns {object[]}
+     */
+    static #filterPrimitives(primitives, side) {
+        return (primitives || []).filter((primitive) =>
+            PcbSideResolvedRenderModel.#isPrimitiveVisibleOnSide(
+                primitive,
+                side
+            )
+        )
+    }
+
+    /**
+     * Checks whether a primitive belongs to the requested surface or a shared
+     * non-surface layer.
+     * @param {object | null} primitive
+     * @param {'front' | 'back'} side
+     * @returns {boolean}
+     */
+    static #isPrimitiveVisibleOnSide(primitive, side) {
+        const layerId = primitive?.layerId ?? primitive?.layerCode
+        if (PcbLayerGroups.isCopper(layerId)) return true
+
+        const layerSide = PcbLayerGroups.describeLayer(layerId).side
+        if (layerSide === 'top') return side === 'front'
+        if (layerSide === 'bottom') return side === 'back'
+        return true
+    }
+}
+
+/**
+ * Resolves a normalized PCB model for the requested board side.
+ * @param {object | null} board
+ * @param {'front' | 'back' | { side?: 'front' | 'back' }} [options]
+ * @returns {object | null}
+ */
+export function preparePcbSideResolvedRenderModel(board, options = {}) {
+    return PcbSideResolvedRenderModel.resolve(board, options)
+}
+
+/**
+ * Checks whether a primitive belongs to an Altium copper signal layer.
+ * @param {object | null} primitive
+ * @returns {boolean}
+ */
+export function isCopperPrimitive(primitive) {
+    return PcbSideResolvedRenderModel.isCopperPrimitive(primitive)
+}

package/src/legacy-renderers.mjs

@@ -15,7 +15,7 @@ export {
     PcbSideResolvedRenderModel,
     isCopperPrimitive,
     preparePcbSideResolvedRenderModel
-} from './ui/PcbSideResolvedRenderModel.mjs'
+} from './convergence/PcbSideResolvedRenderModel.mjs'
 export { PcbSvgRenderer } from './ui/PcbSvgRenderer.mjs'
 export { SchematicColorResolver } from './ui/SchematicColorResolver.mjs'
 export { SchematicContentLayout } from './ui/SchematicContentLayout.mjs'