altium-toolkit 1.4.7 → 1.4.9

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

@@ -0,0 +1,42 @@
+# altium-toolkit 1.4.8
+
+Version 1.4.8 corrects embedded STEP placement for bottom-side components and
+for package owners recovered after initial scene construction.
+
+## Signed STEP source orientation
+
+- Embedded STEP registry entries expose signed source bounds derived from the
+  model payload and its declared length units.
+- Bottom-side models whose geometry is predominantly below the authored origin
+  preserve their authored half-turn instead of being normalized upside down.
+- Direct scene construction and asynchronous scene preparation share the same
+  convergence registry and builder path.
+
+## Late-owner model seating
+
+- Final placement owners are reconciled with their original component-body
+  metadata after historical ownership adapters complete.
+- A finite zero authored standoff clears only an unchanged positive source
+  `dzMil`, allowing the shared viewer's model-bounds seating to place the model
+  on the PCB surface.
+- Positive authored standoffs, unresolved bodies, downstream-adjusted offsets,
+  and unrelated model transformations remain unchanged.
+- The rule is derived from ownership and placement metadata without component,
+  model, vendor, package, project, or fixture-specific matching.
+
+## Compatibility
+
+- Historical native source remains frozen; the corrections live in the public
+  convergence layer.
+- Existing parser, renderer, extension, and viewer scene contracts remain
+  unchanged.
+
+## Verification
+
+- Repository-owned fake regressions cover signed-source bottom half-turns,
+  zero-standoff late owners, positive authored standoffs, unresolved bodies,
+  and downstream-adjusted offsets.
+- Exact local-board verification checks the affected model seating together
+  with the previously reported bottom connector orientation.
+- Release gates include the complete package suite, formatting check, npm dry
+  run, ECAD Forge integration tests, structured-data check, and static build.

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.7",
+    "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/PcbScene3dBuilder.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dBuilder as HistoricalPcbScene3dBuilder } from '../ui/PcbScene3dBuilder.mjs'
+
+const NEGATIVE_SOURCE_Z_DOMINANCE_RATIO = 0.8
+const POSITION_EPSILON_MIL = 1e-6
+
+/**
+ * Adds signed-source model orientation correction around the preserved native
+ * scene builder.
+ */
+export class PcbScene3dBuilder {
+    /**
+     * Builds a scene and preserves structurally negative-Z source half-turns.
+     * @param {object} documentModel Parsed Altium document model.
+     * @param {object} [options] Native scene-builder options.
+     * @returns {object}
+     */
+    static build(documentModel, options = {}) {
+        const scene = HistoricalPcbScene3dBuilder.build(documentModel, options)
+        if (!Array.isArray(scene?.externalPlacements)) {
+            return scene
+        }
+
+        return {
+            ...scene,
+            externalPlacements: scene.externalPlacements.map((placement) =>
+                PcbScene3dBuilder.#normalizePlacement(
+                    placement,
+                    documentModel?.pcb?.componentBodies,
+                    documentModel?.pcb?.components
+                )
+            )
+        }
+    }
+
+    /**
+     * Preserves one bottom placement half-turn when its source geometry is
+     * predominantly below the authored origin.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} componentBodies Source component bodies.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {object}
+     */
+    static #normalizePlacement(placement, componentBodies, components) {
+        const componentBody = PcbScene3dBuilder.#resolveComponentBody(
+            placement,
+            componentBodies
+        )
+        const normalizedPlacement =
+            PcbScene3dBuilder.#normalizeRecoveredOwnerVerticalOffset(
+                placement,
+                componentBody,
+                components
+            )
+
+        if (
+            String(normalizedPlacement?.mountSide || '').toLowerCase() !==
+                'bottom' ||
+            !PcbScene3dBuilder.#isDominantlyNegativeSourceZ(
+                normalizedPlacement?.externalModel?.sourceBoundsMil
+            )
+        ) {
+            return normalizedPlacement
+        }
+
+        if (
+            PcbScene3dBuilder.#normalizeAngle(
+                componentBody?.modelRotationDeg?.x ??
+                    normalizedPlacement?.externalModel?.transform?.rotationDeg
+                        ?.x
+            ) !== 180
+        ) {
+            return normalizedPlacement
+        }
+
+        return {
+            ...normalizedPlacement,
+            modelTransform: {
+                ...(normalizedPlacement.modelTransform || {}),
+                rotationDeg: {
+                    ...(normalizedPlacement.modelTransform?.rotationDeg || {}),
+                    x: -180
+                }
+            }
+        }
+    }
+
+    /**
+     * Applies owned-package seating after a later adapter recovered the owner.
+     * @param {object} placement Built external placement.
+     * @param {object | null} componentBody Resolved source component body.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {object}
+     */
+    static #normalizeRecoveredOwnerVerticalOffset(
+        placement,
+        componentBody,
+        components
+    ) {
+        if (
+            !PcbScene3dBuilder.#hasResolvedOwner(placement, components) ||
+            !PcbScene3dBuilder.#hasZeroAuthoredStandoff(componentBody) ||
+            !PcbScene3dBuilder.#retainsPositiveSourceOffset(
+                placement,
+                componentBody
+            )
+        ) {
+            return placement
+        }
+
+        return {
+            ...placement,
+            modelTransform: {
+                ...(placement.modelTransform || {}),
+                dzMil: 0
+            }
+        }
+    }
+
+    /**
+     * Checks whether the final placement designator resolves a source owner.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} components Source PCB components.
+     * @returns {boolean}
+     */
+    static #hasResolvedOwner(placement, components) {
+        const designator = String(placement?.designator || '')
+        return (
+            designator.length > 0 &&
+            (Array.isArray(components) ? components : []).some(
+                (component) =>
+                    String(component?.designator || '') === designator
+            )
+        )
+    }
+
+    /**
+     * Checks whether the source explicitly authors zero model standoff.
+     * @param {object | null} componentBody Resolved source component body.
+     * @returns {boolean}
+     */
+    static #hasZeroAuthoredStandoff(componentBody) {
+        const sourceStandoff = componentBody?.standoffHeightMil
+        if (
+            sourceStandoff === null ||
+            sourceStandoff === undefined ||
+            sourceStandoff === ''
+        ) {
+            return false
+        }
+
+        const standoff = Number(sourceStandoff)
+        return (
+            Number.isFinite(standoff) &&
+            Math.abs(standoff) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Checks whether the final placement still carries the positive source Z.
+     * @param {object} placement Built external placement.
+     * @param {object | null} componentBody Resolved source component body.
+     * @returns {boolean}
+     */
+    static #retainsPositiveSourceOffset(placement, componentBody) {
+        const sourceOffset = Number(componentBody?.dzMil)
+        const placementOffset = Number(placement?.modelTransform?.dzMil)
+
+        return (
+            Number.isFinite(sourceOffset) &&
+            sourceOffset > 0 &&
+            Number.isFinite(placementOffset) &&
+            Math.abs(placementOffset - sourceOffset) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Resolves the source body associated with one built placement.
+     * @param {object} placement Built external placement.
+     * @param {object[] | undefined} componentBodies Source component bodies.
+     * @returns {object | null}
+     */
+    static #resolveComponentBody(placement, componentBodies) {
+        const bodyPosition = placement?.bodyPositionMil || {}
+        const modelName = String(placement?.externalModel?.name || '')
+
+        return (
+            (Array.isArray(componentBodies) ? componentBodies : []).find(
+                (componentBody) =>
+                    String(componentBody?.name || '') === modelName &&
+                    PcbScene3dBuilder.#positionsMatch(
+                        componentBody?.positionMil,
+                        bodyPosition
+                    )
+            ) || null
+        )
+    }
+
+    /**
+     * Checks whether two model positions represent the same authored anchor.
+     * @param {{ x?: number, y?: number } | undefined} left Left position.
+     * @param {{ x?: number, y?: number } | undefined} right Right position.
+     * @returns {boolean}
+     */
+    static #positionsMatch(left, right) {
+        return (
+            Math.abs(Number(left?.x) - Number(right?.x)) <=
+                POSITION_EPSILON_MIL &&
+            Math.abs(Number(left?.y) - Number(right?.y)) <= POSITION_EPSILON_MIL
+        )
+    }
+
+    /**
+     * Checks whether at least four fifths of the source Z span lies below the
+     * authored origin.
+     * @param {{ minZ?: number, maxZ?: number } | null | undefined} sourceBoundsMil Signed source-model bounds.
+     * @returns {boolean}
+     */
+    static #isDominantlyNegativeSourceZ(sourceBoundsMil) {
+        const minZ = Number(sourceBoundsMil?.minZ)
+        const maxZ = Number(sourceBoundsMil?.maxZ)
+        if (!Number.isFinite(minZ) || !Number.isFinite(maxZ) || maxZ <= minZ) {
+            return false
+        }
+
+        const negativeSpan = Math.max(0, Math.min(0, maxZ) - minZ)
+        return negativeSpan / (maxZ - minZ) >= NEGATIVE_SOURCE_Z_DOMINANCE_RATIO
+    }
+
+    /**
+     * Normalizes one angle into the positive 0-359 degree range.
+     * @param {unknown} angle Source angle.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const numericAngle = Number(angle || 0)
+        const normalized = numericAngle % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+}

package/src/convergence/PcbScene3dModelRegistry.mjs

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dModelRegistry as HistoricalPcbScene3dModelRegistry } from '../ui/PcbScene3dModelRegistry.mjs'
+
+const MILS_PER_METER = 39370.07874015748
+const MILS_PER_INCH = 1000
+
+/**
+ * Adds signed STEP source bounds to the preserved native model registry.
+ */
+export class PcbScene3dModelRegistry {
+    #registry
+
+    /**
+     * Creates one converged registry around either a preserved native registry
+     * or the native constructor's normalized model rows.
+     * @param {HistoricalPcbScene3dModelRegistry | object[]} registryOrModelFiles Native registry or normalized session models.
+     * @param {object[]} embeddedModels Normalized embedded models.
+     */
+    constructor(registryOrModelFiles, embeddedModels) {
+        this.#registry =
+            registryOrModelFiles instanceof HistoricalPcbScene3dModelRegistry
+                ? registryOrModelFiles
+                : new HistoricalPcbScene3dModelRegistry(
+                      registryOrModelFiles,
+                      embeddedModels
+                  )
+    }
+
+    /**
+     * Creates one model registry from session and embedded model assets.
+     * @param {{ name?: string, relativePath?: string, source?: string }[]} sessionFiles Session model files.
+     * @param {{ id?: string, checksum?: number | null, name?: string, format?: string, payloadText?: string, sourceStream?: string, transform?: object }[]} [embeddedModels] Embedded model payloads.
+     * @returns {PcbScene3dModelRegistry}
+     */
+    static create(sessionFiles, embeddedModels = []) {
+        return new PcbScene3dModelRegistry(
+            HistoricalPcbScene3dModelRegistry.create(
+                sessionFiles,
+                embeddedModels
+            )
+        )
+    }
+
+    /**
+     * Resolves the best available model for one component.
+     * @param {{ pattern?: string, source?: string, modelPath?: string }} component Component metadata.
+     * @returns {object | null}
+     */
+    resolveComponentModel(component) {
+        return this.#registry.resolveComponentModel(component)
+    }
+
+    /**
+     * Resolves a component-body model and exposes its signed STEP bounds.
+     * @param {{ modelId?: string, checksum?: number | null, name?: string }} componentBody Component-body metadata.
+     * @returns {object | null}
+     */
+    resolveComponentBodyModel(componentBody) {
+        const model = this.#registry.resolveComponentBodyModel(componentBody)
+        const sourceBoundsMil =
+            PcbScene3dModelRegistry.#resolveSourceBoundsMil(model)
+
+        return sourceBoundsMil ? { ...model, sourceBoundsMil } : model
+    }
+
+    /**
+     * Resolves a project-level full-board assembly model.
+     * @param {{ fileName?: string }} documentModel Document metadata.
+     * @returns {object | null}
+     */
+    resolveBoardAssemblyModel(documentModel) {
+        return this.#registry.resolveBoardAssemblyModel(documentModel)
+    }
+
+    /**
+     * Resolves signed bounds for one inline STEP model.
+     * @param {{ format?: string, payloadText?: string } | null} model Resolved model.
+     * @returns {{ minX: number, maxX: number, minY: number, maxY: number, minZ: number, maxZ: number } | null}
+     */
+    static #resolveSourceBoundsMil(model) {
+        const format = String(model?.format || '').toLowerCase()
+        if ((format !== 'step' && format !== 'stp') || !model?.payloadText) {
+            return null
+        }
+
+        const text = String(model.payloadText)
+        const points = []
+        const pointPattern =
+            /CARTESIAN_POINT\s*\(\s*(?:'[^']*'|[^,]*),\s*\(([^)]*)\)\s*\)/giu
+        let match = pointPattern.exec(text)
+
+        while (match) {
+            const coordinates = String(match[1] || '')
+                .split(',')
+                .slice(0, 3)
+                .map((value) => Number(value.trim()))
+            if (
+                coordinates.length === 3 &&
+                coordinates.every((value) => Number.isFinite(value))
+            ) {
+                points.push(coordinates)
+            }
+            match = pointPattern.exec(text)
+        }
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const [firstPoint] = points
+        const bounds = {
+            minX: firstPoint[0],
+            maxX: firstPoint[0],
+            minY: firstPoint[1],
+            maxY: firstPoint[1],
+            minZ: firstPoint[2],
+            maxZ: firstPoint[2]
+        }
+        points.slice(1).forEach(([x, y, z]) => {
+            bounds.minX = Math.min(bounds.minX, x)
+            bounds.maxX = Math.max(bounds.maxX, x)
+            bounds.minY = Math.min(bounds.minY, y)
+            bounds.maxY = Math.max(bounds.maxY, y)
+            bounds.minZ = Math.min(bounds.minZ, z)
+            bounds.maxZ = Math.max(bounds.maxZ, z)
+        })
+
+        const scale = PcbScene3dModelRegistry.#resolveStepMilScale(text)
+        return Object.fromEntries(
+            Object.entries(bounds).map(([key, value]) => [key, value * scale])
+        )
+    }
+
+    /**
+     * Resolves the STEP length-unit scale to mils.
+     * @param {string} payloadText STEP text payload.
+     * @returns {number}
+     */
+    static #resolveStepMilScale(payloadText) {
+        const text = String(payloadText || '').toUpperCase()
+        if (/\bINCH\b|\.INCH\./u.test(text)) {
+            return MILS_PER_INCH
+        }
+
+        const siUnitMatch = text.match(
+            /SI_UNIT\s*\(\s*(\.[A-Z]+\.|\$)\s*,\s*\.METRE\.\s*\)/u
+        )
+        return (
+            PcbScene3dModelRegistry.#resolveSiPrefixScale(siUnitMatch?.[1]) *
+            MILS_PER_METER
+        )
+    }
+
+    /**
+     * Resolves one STEP SI length prefix to a meter multiplier.
+     * @param {string | undefined} prefix STEP SI prefix.
+     * @returns {number}
+     */
+    static #resolveSiPrefixScale(prefix) {
+        const scales = {
+            '.EXA.': 1e18,
+            '.PETA.': 1e15,
+            '.TERA.': 1e12,
+            '.GIGA.': 1e9,
+            '.MEGA.': 1e6,
+            '.KILO.': 1e3,
+            '.HECTO.': 1e2,
+            '.DECA.': 1e1,
+            $: 1,
+            '.DECI.': 1e-1,
+            '.CENTI.': 1e-2,
+            '.MILLI.': 1e-3,
+            '.MICRO.': 1e-6,
+            '.NANO.': 1e-9,
+            '.PICO.': 1e-12,
+            '.FEMTO.': 1e-15,
+            '.ATTO.': 1e-18
+        }
+
+        return scales[prefix || '.MILLI.'] ?? 1e-3
+    }
+}

package/src/convergence/PcbScene3dScenePreparator.mjs

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbScene3dBuilder } from './PcbScene3dBuilder.mjs'
+import { PcbScene3dModelRegistry } from './PcbScene3dModelRegistry.mjs'
+
+/**
+ * Builds converged renderer-ready scene descriptions for async preprocessing.
+ */
+export class PcbScene3dScenePreparator {
+    /**
+     * Builds one scene description with the converged registry and builder.
+     * @param {object} documentModel Parsed Altium document model.
+     * @param {{ sessionAssets?: object[], modelRegistry?: object | null, buildScene?: (documentModel: object, options: { modelRegistry: object }) => object }} [options] Scene preparation options.
+     * @returns {Promise<object>}
+     */
+    static async prepare(documentModel, options = {}) {
+        const modelRegistry =
+            options.modelRegistry ||
+            PcbScene3dModelRegistry.create(
+                options.sessionAssets || [],
+                Array.isArray(documentModel?.pcb?.embeddedModels)
+                    ? documentModel.pcb.embeddedModels
+                    : []
+            )
+        const buildScene =
+            options.buildScene ||
+            ((nextDocumentModel, buildOptions) =>
+                PcbScene3dBuilder.build(nextDocumentModel, buildOptions))
+
+        return buildScene(documentModel, { modelRegistry })
+    }
+}

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
+        )
+    }
+}

package/src/extensions.mjs

@@ -4,9 +4,17 @@
 export * from 'circuitjson-toolkit/extensions'
 
 export { AltiumExtensionResolver } from './convergence/AltiumExtensionResolver.mjs'
+export { PcbScene3dBuilder } from './convergence/PcbScene3dBuilder.mjs'
+export { PcbScene3dModelRegistry } from './convergence/PcbScene3dModelRegistry.mjs'
+export { PcbScene3dScenePreparator } from './convergence/PcbScene3dScenePreparator.mjs'
 export { PcbSvgRenderer } from './convergence/PcbSvgRenderer.mjs'
 export { SchematicSvgRenderer } from './convergence/SchematicSvgRenderer.mjs'
 export * from './legacy-parser.mjs'
 export * from './legacy-netlist-query.mjs'
 export * from './legacy-renderers.mjs'
-export * from './legacy-scene3d.mjs'
+export {
+    AltiumScene3dAuthoredBodyAnchorAdapter,
+    PcbScene3dPackages,
+    PcbScene3dSummaryRenderer,
+    PcbScene3dTextBoxLayoutResolver
+} from './legacy-scene3d.mjs'