altium-toolkit 1.4.8 → 1.4.10

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

@@ -0,0 +1,29 @@
+# altium-toolkit 1.4.10
+
+Version 1.4.10 keeps complete authored schematic footer assemblies aligned when
+a recovered standard sheet is wider than its stored native template.
+
+## Native schematic footer alignment
+
+- The convergence renderer detects structurally seeded native-footer owners
+  across every supported schematic primitive family.
+- Lines, shapes, text, and embedded images belonging to the same authored owner
+  receive one shared effective right-edge translation.
+- Multiple footer owners use the exact single offset computed by the preserved
+  historical renderer, while unrelated and ownerless content remains fixed.
+
+## Compatibility
+
+- Historical native renderer and partitioner sources remain byte-for-byte
+  frozen.
+- The correction is a render-only convergence adaptation and does not mutate
+  parsed documents or change public parser and renderer signatures.
+- Detection derives from promoted-sheet metadata, authored ownership, and
+  primitive geometry without matching project names, labels, or sample data.
+
+## Verification
+
+- Repository-owned fake regressions cover lower footer seeds, upper geometry,
+  text, embedded images, multiple seeded owners, and unrelated content.
+- The complete package suite, formatting check, performance guard, npm package
+  dry run, and ECAD Forge integration gates are required for release.

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.10",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/convergence/AltiumSchematicNativeFooterOwnerAligner.mjs

@@ -0,0 +1,351 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const PRIMITIVE_FAMILIES = Object.freeze([
+    'lines',
+    'polygons',
+    'rectangles',
+    'roundedRectangles',
+    'ellipses',
+    'arcs',
+    'beziers',
+    'pies',
+    'ieeeSymbols',
+    'texts',
+    'images'
+])
+
+/**
+ * Aligns complete authored footer-owner groups before the preserved historical
+ * renderer partitions individual native footer primitives.
+ */
+export class AltiumSchematicNativeFooterOwnerAligner {
+    /**
+     * Builds a render-only schematic view whose non-seed footer-owner members
+     * receive the same effective translation as the historical footer group.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @returns {Record<string, any>} Owner-aligned render document.
+     */
+    static align(documentModel) {
+        const schematic = documentModel?.schematic
+        const sheet = schematic?.sheet
+        if (
+            !schematic ||
+            !AltiumSchematicNativeFooterOwnerAligner.#shouldAlign(sheet)
+        ) {
+            return documentModel
+        }
+
+        const seededOwners = new Set()
+        let seedMaximumX = -Infinity
+        for (const family of PRIMITIVE_FAMILIES) {
+            for (const primitive of schematic[family] || []) {
+                if (
+                    !AltiumSchematicNativeFooterOwnerAligner.#isFooterSeed(
+                        primitive,
+                        sheet
+                    )
+                ) {
+                    continue
+                }
+
+                const owner =
+                    AltiumSchematicNativeFooterOwnerAligner.#owner(primitive)
+                const bounds =
+                    AltiumSchematicNativeFooterOwnerAligner.#bounds(primitive)
+                seededOwners.add(owner)
+                seedMaximumX = Math.max(seedMaximumX, bounds.maxX)
+            }
+        }
+        if (!seededOwners.size) return documentModel
+
+        const margin = Math.max(Number(sheet?.marginWidth || 20), 10)
+        const offset = Math.max(Number(sheet.width) - margin - seedMaximumX, 0)
+        if (!(offset > 0)) return documentModel
+        const alignedFamilies = {}
+        let changed = false
+
+        for (const family of PRIMITIVE_FAMILIES) {
+            const primitives = schematic[family]
+            if (!Array.isArray(primitives)) continue
+
+            let familyChanged = false
+            const alignedPrimitives = primitives.map((primitive) => {
+                if (
+                    !seededOwners.has(
+                        AltiumSchematicNativeFooterOwnerAligner.#owner(
+                            primitive
+                        )
+                    ) ||
+                    AltiumSchematicNativeFooterOwnerAligner.#isFooterSeed(
+                        primitive,
+                        sheet
+                    )
+                ) {
+                    return primitive
+                }
+
+                familyChanged = true
+                return AltiumSchematicNativeFooterOwnerAligner.#translate(
+                    primitive,
+                    offset
+                )
+            })
+
+            if (familyChanged) {
+                alignedFamilies[family] = alignedPrimitives
+                changed = true
+            }
+        }
+
+        if (!changed) return documentModel
+
+        return {
+            ...documentModel,
+            schematic: {
+                ...schematic,
+                ...alignedFamilies
+            }
+        }
+    }
+
+    /**
+     * Returns true when a promoted standard sheet requires native-footer
+     * alignment.
+     * @param {Record<string, any> | undefined} sheet Sheet metadata.
+     * @returns {boolean} Whether alignment can apply.
+     */
+    static #shouldAlign(sheet) {
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        const sourceWidth = Number(sheet?.sourceWidth || 0)
+        const sourceHeight = Number(sheet?.sourceHeight || 0)
+
+        return Boolean(
+            sheet?.borderOn &&
+            sheet?.paperSize &&
+            sourceWidth > 0 &&
+            sourceHeight > 0 &&
+            (width > sourceWidth || height > sourceHeight)
+        )
+    }
+
+    /**
+     * Returns true when one primitive triggers the preserved lower-right
+     * native-footer partitioning predicate.
+     * @param {Record<string, any>} primitive Primitive candidate.
+     * @param {Record<string, any>} sheet Sheet metadata.
+     * @returns {boolean} Whether the primitive seeds a footer owner.
+     */
+    static #isFooterSeed(primitive, sheet) {
+        if (!AltiumSchematicNativeFooterOwnerAligner.#owner(primitive)) {
+            return false
+        }
+
+        const bounds =
+            AltiumSchematicNativeFooterOwnerAligner.#bounds(primitive)
+        if (!bounds) return false
+
+        const margin = Math.max(Number(sheet?.marginWidth || 20), 10)
+        const footerLimit = Math.max(margin * 6, 120)
+        const footerStartX = Math.max(Number(sheet?.width || 0), 0) * 0.5
+
+        return bounds.maxY <= footerLimit && bounds.maxX >= footerStartX
+    }
+
+    /**
+     * Normalizes one primitive owner for structural grouping.
+     * @param {Record<string, any> | undefined} primitive Primitive candidate.
+     * @returns {string} Normalized owner key.
+     */
+    static #owner(primitive) {
+        return String(primitive?.ownerIndex || '').trim()
+    }
+
+    /**
+     * Resolves the document-space bounds of one normalized primitive.
+     * @param {Record<string, any>} primitive Primitive candidate.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null} Primitive bounds.
+     */
+    static #bounds(primitive) {
+        const points =
+            AltiumSchematicNativeFooterOwnerAligner.#primitivePoints(primitive)
+        if (!points.length) return null
+
+        return {
+            minX: Math.min(...points.map((point) => point.x)),
+            minY: Math.min(...points.map((point) => point.y)),
+            maxX: Math.max(...points.map((point) => point.x)),
+            maxY: Math.max(...points.map((point) => point.y))
+        }
+    }
+
+    /**
+     * Collects finite point coordinates from one normalized primitive.
+     * @param {Record<string, any>} primitive Primitive candidate.
+     * @returns {{ x: number, y: number }[]} Primitive points.
+     */
+    static #primitivePoints(primitive) {
+        if (Array.isArray(primitive?.points)) {
+            return primitive.points
+                .map((point) =>
+                    AltiumSchematicNativeFooterOwnerAligner.#point(
+                        point?.x,
+                        point?.y
+                    )
+                )
+                .filter(Boolean)
+        }
+        if (Array.isArray(primitive?.segments)) {
+            return primitive.segments.flatMap((segment) =>
+                [
+                    AltiumSchematicNativeFooterOwnerAligner.#point(
+                        segment?.x1,
+                        segment?.y1
+                    ),
+                    AltiumSchematicNativeFooterOwnerAligner.#point(
+                        segment?.x2,
+                        segment?.y2
+                    )
+                ].filter(Boolean)
+            )
+        }
+        if (
+            Number.isFinite(Number(primitive?.x1)) &&
+            Number.isFinite(Number(primitive?.y1)) &&
+            Number.isFinite(Number(primitive?.x2)) &&
+            Number.isFinite(Number(primitive?.y2))
+        ) {
+            return [
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    primitive.x1,
+                    primitive.y1
+                ),
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    primitive.x2,
+                    primitive.y2
+                )
+            ]
+        }
+        if (
+            Number.isFinite(Number(primitive?.cornerX)) &&
+            Number.isFinite(Number(primitive?.cornerY))
+        ) {
+            return [
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    primitive.x,
+                    primitive.y
+                ),
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    primitive.cornerX,
+                    primitive.cornerY
+                )
+            ].filter(Boolean)
+        }
+        if (
+            Number.isFinite(Number(primitive?.width)) &&
+            Number.isFinite(Number(primitive?.height))
+        ) {
+            return [
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    primitive.x,
+                    primitive.y
+                ),
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    Number(primitive.x || 0) + Number(primitive.width || 0),
+                    Number(primitive.y || 0) + Number(primitive.height || 0)
+                )
+            ].filter(Boolean)
+        }
+        if (
+            Number.isFinite(Number(primitive?.radius)) ||
+            Number.isFinite(Number(primitive?.radiusX))
+        ) {
+            const radiusX = Math.max(
+                Number(primitive?.radiusX || primitive?.radius || 0),
+                0
+            )
+            const radiusY = Math.max(
+                Number(primitive?.radiusY || primitive?.radius || 0),
+                0
+            )
+
+            return [
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    Number(primitive.x || 0) - radiusX,
+                    Number(primitive.y || 0) - radiusY
+                ),
+                AltiumSchematicNativeFooterOwnerAligner.#point(
+                    Number(primitive.x || 0) + radiusX,
+                    Number(primitive.y || 0) + radiusY
+                )
+            ]
+        }
+
+        return [
+            AltiumSchematicNativeFooterOwnerAligner.#point(
+                primitive?.x,
+                primitive?.y
+            )
+        ].filter(Boolean)
+    }
+
+    /**
+     * Builds one finite point.
+     * @param {number | string | undefined} x Raw x coordinate.
+     * @param {number | string | undefined} y Raw y coordinate.
+     * @returns {{ x: number, y: number } | null} Finite point.
+     */
+    static #point(x, y) {
+        const normalizedX = Number(x)
+        const normalizedY = Number(y)
+        if (!Number.isFinite(normalizedX) || !Number.isFinite(normalizedY)) {
+            return null
+        }
+
+        return { x: normalizedX, y: normalizedY }
+    }
+
+    /**
+     * Copies one primitive while translating each present horizontal geometry
+     * coordinate.
+     * @param {Record<string, any>} primitive Primitive to translate.
+     * @param {number} offset Positive horizontal offset.
+     * @returns {Record<string, any>} Translated primitive.
+     */
+    static #translate(primitive, offset) {
+        const translated = { ...primitive }
+        for (const field of ['x', 'x1', 'x2', 'cornerX']) {
+            if (
+                Object.hasOwn(primitive, field) &&
+                Number.isFinite(Number(primitive[field]))
+            ) {
+                translated[field] = Number(primitive[field]) + offset
+            }
+        }
+        if (Array.isArray(primitive.points)) {
+            translated.points = primitive.points.map((point) => ({
+                ...point,
+                ...(Number.isFinite(Number(point?.x))
+                    ? { x: Number(point.x) + offset }
+                    : {})
+            }))
+        }
+        if (Array.isArray(primitive.segments)) {
+            translated.segments = primitive.segments.map((segment) => ({
+                ...segment,
+                ...(Number.isFinite(Number(segment?.x1))
+                    ? { x1: Number(segment.x1) + offset }
+                    : {}),
+                ...(Number.isFinite(Number(segment?.x2))
+                    ? { x2: Number(segment.x2) + offset }
+                    : {})
+            }))
+        }
+
+        return translated
+    }
+}
+
+Object.freeze(AltiumSchematicNativeFooterOwnerAligner.prototype)
+Object.freeze(AltiumSchematicNativeFooterOwnerAligner)

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

package/src/convergence/SchematicSvgRenderer.mjs

@@ -3,6 +3,7 @@
 
 import { SchematicSvgRenderer as LegacySchematicSvgRenderer } from '../ui/SchematicSvgRenderer.mjs'
 import { AltiumSchematicImageNormalizer } from './AltiumSchematicImageNormalizer.mjs'
+import { AltiumSchematicNativeFooterOwnerAligner } from './AltiumSchematicNativeFooterOwnerAligner.mjs'
 
 /**
  * Renders native Altium schematic models through the preserved historical
@@ -20,8 +21,10 @@ export class SchematicSvgRenderer {
     static render(documentModel, options = {}) {
         const normalized =
             AltiumSchematicImageNormalizer.normalize(documentModel)
+        const aligned =
+            AltiumSchematicNativeFooterOwnerAligner.align(normalized)
         return LegacySchematicSvgRenderer.render(
-            SchematicSvgRenderer.#visibilityAwareDocument(normalized),
+            SchematicSvgRenderer.#visibilityAwareDocument(aligned),
             options
         )
     }