altium-toolkit 1.0.1 → 1.0.2

package/package.json

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

package/src/styles/altium-renderers.css

@@ -141,6 +141,7 @@
     --pcb-via-hole-fill: #0f746c;
     --pcb-footprint-fill: rgba(247, 230, 117, 0.14);
     --pcb-footprint-track-color: rgba(237, 172, 36, 1);
+    --pcb-text-knockout-fill: rgba(248, 246, 239, 0.96);
     --pcb-component-top-fill: rgba(244, 219, 198, 0.92);
     --pcb-component-bottom-fill: rgba(15, 116, 108, 0.84);
     --pcb-component-stroke: rgba(110, 64, 38, 0.28);
@@ -178,6 +179,8 @@
     fill: var(--pcb-board-fill);
     stroke: var(--pcb-board-stroke);
     stroke-width: 18;
+    stroke-linecap: round;
+    stroke-linejoin: round;
 }
 
 .board-outline--stroke {
@@ -252,7 +255,7 @@
 }
 
 .pcb-footprint-region {
-    fill: var(--pcb-footprint-track-color);
+    fill: var(--pcb-footprint-region-fill, var(--pcb-footprint-track-color));
 }
 
 .pcb-footprint-track,
@@ -278,6 +281,14 @@
     pointer-events: none;
 }
 
+.pcb-text__knockout-fill {
+    fill: var(--pcb-text-knockout-fill);
+}
+
+.pcb-text__knockout-glyphs {
+    fill: #000;
+}
+
 .bom-panel {
     display: grid;
     gap: 1rem;

package/src/ui/PcbNativeTextKnockoutDetector.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Detects native overlay artwork that already contains text knockout holes.
+ */
+export class PcbNativeTextKnockoutDetector {
+    static #DENSE_OVERLAY_MIN_REGION_AREA_RATIO = 0.2
+    static #DENSE_OVERLAY_MIN_TRACK_COUNT = 250
+
+    /**
+     * Returns true when side-resolved overlay primitives carry native text
+     * knockouts, so source inverted TrueType labels would duplicate artwork.
+     * @param {{ fills?: object[], regions?: object[], tracks?: object[], arcs?: object[] }} primitives Side-resolved overlay primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static hasNativeTextKnockouts(primitives, board) {
+        const fills = [
+            ...(Array.isArray(primitives?.fills) ? primitives.fills : []),
+            ...(Array.isArray(primitives?.regions) ? primitives.regions : [])
+        ]
+
+        return (
+            PcbNativeTextKnockoutDetector.#isDenseOverlayArtwork(
+                {
+                    fills,
+                    tracks: primitives?.tracks,
+                    arcs: primitives?.arcs
+                },
+                board
+            ) &&
+            fills.some(
+                (fill) => Array.isArray(fill?.holes) && fill.holes.length > 0
+            )
+        )
+    }
+
+    /**
+     * Detects dense overlay artwork from structural density.
+     * @param {{ fills?: object[], tracks?: object[], arcs?: object[] }} side Side primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {boolean}
+     */
+    static #isDenseOverlayArtwork(side, board) {
+        const strokeCount =
+            (Array.isArray(side?.tracks) ? side.tracks.length : 0) +
+            (Array.isArray(side?.arcs) ? side.arcs.length : 0)
+
+        return (
+            strokeCount >=
+                PcbNativeTextKnockoutDetector.#DENSE_OVERLAY_MIN_TRACK_COUNT &&
+            PcbNativeTextKnockoutDetector.#maxFillAreaRatio(
+                side?.fills,
+                board
+            ) >=
+                PcbNativeTextKnockoutDetector
+                    .#DENSE_OVERLAY_MIN_REGION_AREA_RATIO
+        )
+    }
+
+    /**
+     * Resolves the largest fill-to-board bounding-box area ratio.
+     * @param {object[] | undefined} fills Fill primitives.
+     * @param {{ widthMil?: number, heightMil?: number }} board Board bounds.
+     * @returns {number}
+     */
+    static #maxFillAreaRatio(fills, board) {
+        const boardArea =
+            Math.max(Number(board?.widthMil || 0), 0) *
+            Math.max(Number(board?.heightMil || 0), 0)
+        if (!boardArea) {
+            return 0
+        }
+
+        return (Array.isArray(fills) ? fills : []).reduce((maxRatio, fill) => {
+            const bounds =
+                PcbNativeTextKnockoutDetector.#resolveFillBounds(fill)
+            if (!bounds) {
+                return maxRatio
+            }
+
+            const fillArea =
+                Math.max(bounds.maxX - bounds.minX, 0) *
+                Math.max(bounds.maxY - bounds.minY, 0)
+
+            return Math.max(maxRatio, fillArea / boardArea)
+        }, 0)
+    }
+
+    /**
+     * Resolves rough authored bounds for one rectangular or polygon fill.
+     * @param {{ x1?: number, y1?: number, x2?: number, y2?: number, points?: { x?: number, y?: number }[] }} fill Fill primitive.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static #resolveFillBounds(fill) {
+        const points = Array.isArray(fill?.points)
+            ? fill.points
+                  .map((point) => ({
+                      x: Number(point?.x),
+                      y: Number(point?.y)
+                  }))
+                  .filter(
+                      (point) =>
+                          Number.isFinite(point.x) && Number.isFinite(point.y)
+                  )
+            : [
+                  { x: Number(fill?.x1), y: Number(fill?.y1) },
+                  { x: Number(fill?.x2), y: Number(fill?.y2) }
+              ].filter(
+                  (point) =>
+                      Number.isFinite(point.x) && Number.isFinite(point.y)
+              )
+
+        if (points.length < 2) {
+            return null
+        }
+
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+
+        return {
+            minX: Math.min(...xs),
+            minY: Math.min(...ys),
+            maxX: Math.max(...xs),
+            maxY: Math.max(...ys)
+        }
+    }
+}

package/src/ui/PcbSvgRenderer.mjs

@@ -7,7 +7,9 @@ import { PcbEdgeFacingGlyphNormalizer } from './PcbEdgeFacingGlyphNormalizer.mjs
 import { PcbEmbeddedFontFaceRenderer } from './PcbEmbeddedFontFaceRenderer.mjs'
 import { PcbFootprintPrimitiveSelector } from './PcbFootprintPrimitiveSelector.mjs'
 import { PcbCopperPrimitiveSplitter } from './PcbCopperPrimitiveSplitter.mjs'
+import { PcbNativeTextKnockoutDetector } from './PcbNativeTextKnockoutDetector.mjs'
 import { PcbRegionPrimitiveRenderer } from './PcbRegionPrimitiveRenderer.mjs'
+import { PcbScene3dBoardOutlineRefiner } from './PcbScene3dBoardOutlineRefiner.mjs'
 import { PcbTextPrimitiveRenderer } from './PcbTextPrimitiveRenderer.mjs'
 import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
 /**
@@ -27,7 +29,10 @@ export class PcbSvgRenderer {
         if (!pcb) {
             return '<section class="altium-renderer-empty">No PCB entities were recovered from this file.</section>'
         }
-        const outline = pcb.boardOutline
+        const outline = PcbScene3dBoardOutlineRefiner.refine(
+            { board: pcb.boardOutline },
+            documentModel
+        ).board
         const polygons = pcb.polygons || []
         const fills = pcb.fills || []
         const tracks = pcb.tracks || []
@@ -43,11 +48,6 @@ export class PcbSvgRenderer {
         const stackLayers = Array.isArray(pcb.layers) ? pcb.layers : []
         const primitiveLayers = pcb.primitiveLayers || []
         const displayLayers = stackLayers.length ? stackLayers : primitiveLayers
-        const texts = PcbTextPrimitiveRenderer.select(
-            primitiveLayers,
-            pcb.texts || [],
-            'top'
-        )
         const copperGroups = PcbCopperPrimitiveSplitter.split(
             polygons,
             fills,
@@ -66,6 +66,18 @@ export class PcbSvgRenderer {
             ),
             outline
         )
+        const texts = PcbTextPrimitiveRenderer.select(
+            primitiveLayers,
+            pcb.texts || [],
+            'top',
+            {
+                nativeTextKnockouts:
+                    PcbNativeTextKnockoutDetector.hasNativeTextKnockouts(
+                        footprintPrimitives,
+                        outline
+                    )
+            }
+        )
         const path = PcbSvgRenderer.#buildBoardPath(outline.segments)
         const clipPathId = 'pcb-board-clip'
         const viewBox = PcbSvgRenderer.#buildViewBox(
@@ -256,6 +268,9 @@ export class PcbSvgRenderer {
             'pcb-footprint-region'
         )
         const textMarkup = PcbTextPrimitiveRenderer.render(texts)
+        const textGroupTransform = PcbSvgRenderer.#renderTextGroupTransform(
+            pcb.textGroupTransform
+        )
         const fontFaceMarkup = PcbEmbeddedFontFaceRenderer.buildMarkup(
             pcb.embeddedFonts || []
         )
@@ -355,17 +370,19 @@ export class PcbSvgRenderer {
             footprintArcMarkup +
             footprintRegionMarkup +
             '</g>' +
+            '<g class="pcb-components">' +
+            componentMarkup +
+            '</g>' +
             '<g class="pcb-texts" clip-path="url(#' +
             clipPathId +
-            ')">' +
+            ')"' +
+            textGroupTransform +
+            '>' +
             textMarkup +
             '</g>' +
             '<path class="board-outline board-outline--stroke" d="' +
             SchematicSvgUtils.escapeHtml(path) +
             '" />' +
-            '<g class="pcb-components">' +
-            componentMarkup +
-            '</g>' +
             '</svg></div></section>'
         )
     }
@@ -415,6 +432,62 @@ export class PcbSvgRenderer {
         return path + ' Z'
     }
 
+    /**
+     * Renders an optional transform for the whole PCB text layer.
+     * @param {{ translateX?: number, translateY?: number, scaleX?: number, scaleY?: number } | undefined} transform Text group transform.
+     * @returns {string}
+     */
+    static #renderTextGroupTransform(transform) {
+        if (!transform || typeof transform !== 'object') {
+            return ''
+        }
+
+        const translateX = Number(transform.translateX || 0)
+        const translateY = Number(transform.translateY || 0)
+        const scaleX =
+            transform.scaleX === null || transform.scaleX === undefined
+                ? 1
+                : Number(transform.scaleX)
+        const scaleY =
+            transform.scaleY === null || transform.scaleY === undefined
+                ? 1
+                : Number(transform.scaleY)
+        if (
+            !Number.isFinite(translateX) ||
+            !Number.isFinite(translateY) ||
+            !Number.isFinite(scaleX) ||
+            !Number.isFinite(scaleY) ||
+            (translateX === 0 &&
+                translateY === 0 &&
+                scaleX === 1 &&
+                scaleY === 1)
+        ) {
+            return ''
+        }
+
+        const parts = []
+        if (translateX !== 0 || translateY !== 0) {
+            parts.push(
+                'translate(' +
+                    SchematicSvgUtils.formatNumber(translateX) +
+                    ' ' +
+                    SchematicSvgUtils.formatNumber(translateY) +
+                    ')'
+            )
+        }
+        if (scaleX !== 1 || scaleY !== 1) {
+            parts.push(
+                'scale(' +
+                    SchematicSvgUtils.formatNumber(scaleX) +
+                    ' ' +
+                    SchematicSvgUtils.formatNumber(scaleY) +
+                    ')'
+            )
+        }
+
+        return ' transform="' + parts.join(' ') + '"'
+    }
+
     /**
      * Computes a reasonable viewBox.
      * @param {{ minX: number, minY: number, widthMil: number, heightMil: number, segments: Array<Record<string, number | string>> }} outline

package/src/ui/PcbTextPrimitiveRenderer.mjs

@@ -8,14 +8,25 @@ import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
  * Renders recovered PCB text primitives.
  */
 export class PcbTextPrimitiveRenderer {
+    static #DEFAULT_TRUETYPE_EM_SCALE = 0.895
+    static #TEXTURE_PADDING_RATIO = 0.14
+    static #MIN_CANVAS_PADDING = 2
+    static #LINE_HEIGHT_RATIO = 1.16
+    static #FONT_ASCENT_RATIO = 0.82
+    static #FONT_DESCENT_RATIO = 0.18
+    static #DEFAULT_GLYPH_WIDTH_RATIO = 0.56
+    static #MONOSPACE_GLYPH_WIDTH_RATIO = 0.62
+    static #DEFAULT_FONT_FAMILY = 'Arial'
+
     /**
      * Selects texts that belong to the requested board-side composite.
      * @param {{ layerId: number, name: string }[]} primitiveLayers
      * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, visible?: boolean }[]} texts
      * @param {'top' | 'bottom'} [side]
+     * @param {{ nativeTextKnockouts?: boolean }} [options] Selection options.
      * @returns {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, visible?: boolean }[]}
      */
-    static select(primitiveLayers, texts, side = 'top') {
+    static select(primitiveLayers, texts, side = 'top', options = {}) {
         const layerIds = PcbTextPrimitiveRenderer.#resolveLayerIds(
             primitiveLayers || [],
             side
@@ -27,6 +38,10 @@ export class PcbTextPrimitiveRenderer {
                 text?.visible !== false &&
                 String(text?.text || '').trim() &&
                 !PcbTextPrimitiveRenderer.#isPlaceholderText(text) &&
+                !PcbTextPrimitiveRenderer.#shouldSkipNativeTextKnockout(
+                    text,
+                    options
+                ) &&
                 Number.isInteger(layerId) &&
                 layerIds.has(layerId)
             )
@@ -40,22 +55,33 @@ export class PcbTextPrimitiveRenderer {
      */
     static render(texts) {
         return (texts || [])
-            .map((text) => PcbTextPrimitiveRenderer.#renderText(text))
+            .map((text, index) =>
+                PcbTextPrimitiveRenderer.#renderText(text, index)
+            )
             .join('')
     }
 
     /**
      * Renders one PCB text primitive.
      * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, fontFamily?: string, fontWeight?: number, fontStyle?: string }} text
+     * @param {number} index Text index for stable SVG resource ids.
      * @returns {string}
      */
-    static #renderText(text) {
-        const fontSize = Math.max(Number(text.height || 0), 8)
+    static #renderText(text, index) {
+        const fontSize = PcbTextPrimitiveRenderer.#resolveFontSize(text)
         const rotation = Number(text.rotation || 0)
-        const lines = String(text.text || '')
-            .replace(/\r\n?/gu, '\n')
-            .split('\n')
-            .filter((line) => line.length > 0)
+        const lines = PcbTextPrimitiveRenderer.#textLines(text)
+
+        if (PcbTextPrimitiveRenderer.#isInvertedText(text)) {
+            return PcbTextPrimitiveRenderer.#renderInvertedText(
+                text,
+                index,
+                fontSize,
+                rotation,
+                lines
+            )
+        }
+
         const content = lines.length
             ? PcbTextPrimitiveRenderer.#renderTextLines(lines, fontSize)
             : SchematicSvgUtils.escapeHtml(String(text.text || ''))
@@ -63,14 +89,10 @@ export class PcbTextPrimitiveRenderer {
         return (
             '<text class="pcb-text pcb-text--layer-' +
             SchematicSvgUtils.escapeHtml(String(Number(text.layerId || 0))) +
-            '" transform="translate(' +
-            SchematicSvgUtils.formatNumber(Number(text.x || 0)) +
-            ' ' +
-            SchematicSvgUtils.formatNumber(Number(text.y || 0)) +
-            ') rotate(' +
-            SchematicSvgUtils.formatNumber(rotation) +
-            ')" font-size="' +
-            SchematicSvgUtils.formatNumber(fontSize) +
+            '" transform="' +
+            PcbTextPrimitiveRenderer.#renderTextTransform(text, rotation) +
+            '" font-size="' +
+            PcbTextPrimitiveRenderer.#formatTextNumber(fontSize) +
             '"' +
             PcbTextPrimitiveRenderer.#renderFontAttributes(text) +
             ' text-anchor="start" dominant-baseline="alphabetic">' +
@@ -79,6 +101,599 @@ export class PcbTextPrimitiveRenderer {
         )
     }
 
+    /**
+     * Renders one inverted PCB text primitive as filled artwork with glyph
+     * cutouts, matching Altium's TrueType bottom overlay treatment.
+     * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, fontFamily?: string, fontWeight?: number, fontStyle?: string, isInverted?: boolean, marginBorderWidth?: number, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number, useInvertedRectangle?: boolean }} text
+     * @param {number} index Text index for stable SVG mask ids.
+     * @param {number} fontSize Text font size in board units.
+     * @param {number} rotation Text rotation in degrees.
+     * @param {string[]} lines Text lines to render.
+     * @returns {string}
+     */
+    static #renderInvertedText(text, index, fontSize, rotation, lines) {
+        const metrics = PcbTextPrimitiveRenderer.#measureLines(
+            text,
+            lines,
+            fontSize
+        )
+        const padding = PcbTextPrimitiveRenderer.#resolveTextPadding(
+            text,
+            fontSize
+        )
+        const layout = PcbTextPrimitiveRenderer.#resolveTextLayout(
+            text,
+            metrics,
+            padding
+        )
+        const maskId = 'pcb-text-knockout-' + String(index)
+        const content = PcbTextPrimitiveRenderer.#renderTextLines(
+            lines,
+            metrics.lineHeight
+        )
+        const rectX = -layout.anchorX
+        const rectY = layout.anchorY - layout.height
+        const cornerRadius = Math.min(
+            padding,
+            layout.width / 2,
+            layout.height / 2
+        )
+
+        return (
+            '<g class="pcb-text pcb-text--layer-' +
+            SchematicSvgUtils.escapeHtml(String(Number(text.layerId || 0))) +
+            ' pcb-text--inverted" transform="' +
+            PcbTextPrimitiveRenderer.#renderTextTransform(text, rotation) +
+            '">' +
+            '<mask id="' +
+            SchematicSvgUtils.escapeHtml(maskId) +
+            '" maskUnits="userSpaceOnUse" mask-type="luminance" x="' +
+            SchematicSvgUtils.formatNumber(rectX) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(rectY) +
+            '" width="' +
+            SchematicSvgUtils.formatNumber(layout.width) +
+            '" height="' +
+            SchematicSvgUtils.formatNumber(layout.height) +
+            '">' +
+            '<rect class="pcb-text__knockout-mask-fill" x="' +
+            SchematicSvgUtils.formatNumber(rectX) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(rectY) +
+            '" width="' +
+            SchematicSvgUtils.formatNumber(layout.width) +
+            '" height="' +
+            SchematicSvgUtils.formatNumber(layout.height) +
+            '" rx="' +
+            SchematicSvgUtils.formatNumber(cornerRadius) +
+            '" fill="#fff" />' +
+            '<text class="pcb-text__knockout-glyphs" x="0" y="0" font-size="' +
+            PcbTextPrimitiveRenderer.#formatTextNumber(fontSize) +
+            '"' +
+            PcbTextPrimitiveRenderer.#renderFontAttributes(text) +
+            ' text-anchor="start" dominant-baseline="alphabetic" fill="#000">' +
+            content +
+            '</text>' +
+            '</mask>' +
+            '<rect class="pcb-text__knockout-fill" x="' +
+            SchematicSvgUtils.formatNumber(rectX) +
+            '" y="' +
+            SchematicSvgUtils.formatNumber(rectY) +
+            '" width="' +
+            SchematicSvgUtils.formatNumber(layout.width) +
+            '" height="' +
+            SchematicSvgUtils.formatNumber(layout.height) +
+            '" rx="' +
+            SchematicSvgUtils.formatNumber(cornerRadius) +
+            '" mask="url(#' +
+            SchematicSvgUtils.escapeHtml(maskId) +
+            ')" />' +
+            '</g>'
+        )
+    }
+
+    /**
+     * Renders the local text transform, including authored PCB text mirroring.
+     * @param {{ x?: number, y?: number, mirrored?: boolean }} text Text record.
+     * @param {number} rotation Text rotation in degrees.
+     * @returns {string}
+     */
+    static #renderTextTransform(text, rotation) {
+        const mirrorTransform = text?.mirrored === true ? ' scale(-1 1)' : ''
+
+        return (
+            'translate(' +
+            SchematicSvgUtils.formatNumber(Number(text.x || 0)) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(Number(text.y || 0)) +
+            ') rotate(' +
+            SchematicSvgUtils.formatNumber(rotation) +
+            ')' +
+            mirrorTransform
+        )
+    }
+
+    /**
+     * Resolves the SVG font size from Altium text metadata.
+     * @param {{ height?: number, sizeX?: number, sizeY?: number, trueTypeFontScale?: number, fontMetrics?: { emScaleFromPcbHeight?: number }, fontType?: number | string, fontTypeName?: string, isTrueType?: boolean }} text Text record.
+     * @returns {number}
+     */
+    static #resolveFontSize(text) {
+        const height = Math.max(
+            Number(text?.sizeX) || Number(text?.height) || Number(text?.sizeY),
+            1
+        )
+
+        if (PcbTextPrimitiveRenderer.#isTrueTypeText(text)) {
+            return height * PcbTextPrimitiveRenderer.#fontScale(text)
+        }
+
+        return Math.max(height, 8)
+    }
+
+    /**
+     * Checks whether a text primitive uses imported TrueType glyph geometry.
+     * @param {{ fontType?: number | string, fontTypeName?: string, isTrueType?: boolean }} text Text record.
+     * @returns {boolean}
+     */
+    static #isTrueTypeText(text) {
+        const fontTypeName = String(text?.fontTypeName || '').toUpperCase()
+
+        return (
+            text?.isTrueType === true ||
+            Number(text?.fontType) === 1 ||
+            fontTypeName.includes('TRUETYPE')
+        )
+    }
+
+    /**
+     * Resolves the imported TrueType scale used by browser outline fonts.
+     * @param {{ trueTypeFontScale?: number, fontMetrics?: { emScaleFromPcbHeight?: number } }} text Text record.
+     * @returns {number}
+     */
+    static #fontScale(text) {
+        if (Number.isFinite(Number(text?.trueTypeFontScale))) {
+            return Math.max(Number(text.trueTypeFontScale), 0.01)
+        }
+
+        if (Number.isFinite(Number(text?.fontMetrics?.emScaleFromPcbHeight))) {
+            return Math.max(Number(text.fontMetrics.emScaleFromPcbHeight), 0.01)
+        }
+
+        return PcbTextPrimitiveRenderer.#DEFAULT_TRUETYPE_EM_SCALE
+    }
+
+    /**
+     * Checks whether a text primitive should draw as reversed knockout artwork.
+     * @param {{ isInverted?: boolean }} text Text record.
+     * @returns {boolean}
+     */
+    static #isInvertedText(text) {
+        return Boolean(text?.isInverted)
+    }
+
+    /**
+     * Splits one text record into drawable lines.
+     * @param {{ value?: string, text?: string }} text Text record.
+     * @returns {string[]}
+     */
+    static #textLines(text) {
+        const lines = String(text?.value ?? text?.text ?? '').split(/\r?\n/u)
+
+        return lines.length ? lines : ['']
+    }
+
+    /**
+     * Estimates SVG text metrics using the same fallback ratios as the 3D text
+     * texture path when browser canvas measurements are unavailable.
+     * @param {{ fontFamily?: string, fontName?: string }} text Text record.
+     * @param {string[]} lines Text lines.
+     * @param {number} fontSize Text font size.
+     * @returns {{ width: number, height: number, ascent: number, descent: number, lineHeight: number }}
+     */
+    static #measureLines(text, lines, fontSize) {
+        const measured = PcbTextPrimitiveRenderer.#measureCanvasLines(
+            text,
+            lines,
+            fontSize
+        )
+        if (measured) {
+            return measured
+        }
+
+        const ascent = fontSize * PcbTextPrimitiveRenderer.#FONT_ASCENT_RATIO
+        const descent = fontSize * PcbTextPrimitiveRenderer.#FONT_DESCENT_RATIO
+        const glyphHeight = Math.max(ascent + descent, 1)
+        const lineHeight = Math.max(
+            glyphHeight * PcbTextPrimitiveRenderer.#LINE_HEIGHT_RATIO,
+            glyphHeight
+        )
+        const glyphWidth =
+            fontSize * PcbTextPrimitiveRenderer.#glyphWidthRatio(text)
+
+        return {
+            width: Math.max(
+                ...lines.map((line) =>
+                    Math.max(String(line || ' ').length * glyphWidth, 1)
+                )
+            ),
+            height: glyphHeight + lineHeight * (lines.length - 1),
+            ascent,
+            descent,
+            lineHeight
+        }
+    }
+
+    /**
+     * Resolves a stable glyph-width ratio for coarse SVG layout.
+     * @param {{ fontFamily?: string, fontName?: string }} text Text record.
+     * @returns {number}
+     */
+    static #glyphWidthRatio(text) {
+        const metricsRatio =
+            PcbTextPrimitiveRenderer.#fontMetricsAverageWidthRatio(text)
+        if (metricsRatio) {
+            return metricsRatio
+        }
+
+        const family = PcbTextPrimitiveRenderer.#cleanFontFamily(
+            text?.fontFamily || text?.fontName
+        )
+
+        return PcbTextPrimitiveRenderer.#isMonospaceFamily(family)
+            ? PcbTextPrimitiveRenderer.#MONOSPACE_GLYPH_WIDTH_RATIO
+            : PcbTextPrimitiveRenderer.#DEFAULT_GLYPH_WIDTH_RATIO
+    }
+
+    /**
+     * Measures text with a browser canvas when the renderer runs in the app.
+     * @param {{ fontFamily?: string, fontName?: string, isBold?: boolean, fontWeight?: number, isItalic?: boolean }} text Text record.
+     * @param {string[]} lines Text lines.
+     * @param {number} fontSize Text font size.
+     * @returns {{ width: number, height: number, ascent: number, descent: number, lineHeight: number } | null}
+     */
+    static #measureCanvasLines(text, lines, fontSize) {
+        const canvas = globalThis.document?.createElement?.('canvas')
+        const context = canvas?.getContext?.('2d')
+
+        if (!context) {
+            return null
+        }
+
+        context.font = PcbTextPrimitiveRenderer.#buildCanvasFont(text, fontSize)
+
+        const measured = lines.map((line) => context.measureText(line || ' '))
+        const ascent = PcbTextPrimitiveRenderer.#resolveMeasuredExtent(
+            measured,
+            'actualBoundingBoxAscent',
+            fontSize * PcbTextPrimitiveRenderer.#FONT_ASCENT_RATIO
+        )
+        const descent = PcbTextPrimitiveRenderer.#resolveMeasuredExtent(
+            measured,
+            'actualBoundingBoxDescent',
+            fontSize * PcbTextPrimitiveRenderer.#FONT_DESCENT_RATIO
+        )
+        const glyphHeight = Math.max(ascent + descent, 1)
+        const lineHeight = Math.max(
+            glyphHeight * PcbTextPrimitiveRenderer.#LINE_HEIGHT_RATIO,
+            glyphHeight
+        )
+
+        return {
+            width: Math.max(...measured.map((metric) => Number(metric.width))),
+            height: glyphHeight + lineHeight * (lines.length - 1),
+            ascent,
+            descent,
+            lineHeight
+        }
+    }
+
+    /**
+     * Resolves a measured text extent with a stable fallback.
+     * @param {TextMetrics[]} measured Browser text metrics.
+     * @param {'actualBoundingBoxAscent' | 'actualBoundingBoxDescent'} field Extent field.
+     * @param {number} fallback Fallback extent.
+     * @returns {number}
+     */
+    static #resolveMeasuredExtent(measured, field, fallback) {
+        const values = measured
+            .map((metric) => Number(metric?.[field]))
+            .filter((value) => Number.isFinite(value) && value > 0)
+
+        return values.length ? Math.max(...values) : fallback
+    }
+
+    /**
+     * Builds the CSS font string used for optional canvas measurement.
+     * @param {{ fontFamily?: string, fontName?: string, isBold?: boolean, fontWeight?: number, isItalic?: boolean }} text Text record.
+     * @param {number} fontSize Text font size.
+     * @returns {string}
+     */
+    static #buildCanvasFont(text, fontSize) {
+        const weight =
+            text?.isBold || Number(text?.fontWeight) >= 600 ? '700' : '400'
+        const style = text?.isItalic ? 'italic' : 'normal'
+        const family = PcbTextPrimitiveRenderer.#buildCanvasFontFamily(
+            text?.fontFamily || text?.fontName
+        )
+
+        return `${style} ${weight} ${fontSize}px ${family}`
+    }
+
+    /**
+     * Builds a browser font-family stack matching the 3D TrueType path.
+     * @param {unknown} family Font family value.
+     * @returns {string}
+     */
+    static #buildCanvasFontFamily(family) {
+        const cleaned = PcbTextPrimitiveRenderer.#cleanFontFamily(family)
+        const quoted = PcbTextPrimitiveRenderer.#quoteFontFamily(cleaned)
+
+        if (PcbTextPrimitiveRenderer.#isMonospaceFamily(cleaned)) {
+            return [
+                quoted,
+                '"Menlo"',
+                '"Monaco"',
+                '"Liberation Mono"',
+                '"Courier New"',
+                'monospace'
+            ].join(', ')
+        }
+
+        if (PcbTextPrimitiveRenderer.#isArialFamily(cleaned)) {
+            return [
+                quoted,
+                '"Helvetica Neue"',
+                'Helvetica',
+                'Arial',
+                'sans-serif'
+            ].join(', ')
+        }
+
+        return [quoted, 'Arial', 'sans-serif'].join(', ')
+    }
+
+    /**
+     * Quotes one CSS font-family token.
+     * @param {string} family Font family name.
+     * @returns {string}
+     */
+    static #quoteFontFamily(family) {
+        return `"${family.replace(/["\\]/gu, '\\$&')}"`
+    }
+
+    /**
+     * Resolves embedded font average advance width when available.
+     * @param {{ fontMetrics?: { averageAdvanceWidth?: number, unitsPerEm?: number } }} text Text record.
+     * @returns {number | null}
+     */
+    static #fontMetricsAverageWidthRatio(text) {
+        const averageAdvanceWidth = Number(
+            text?.fontMetrics?.averageAdvanceWidth
+        )
+        const unitsPerEm = Number(text?.fontMetrics?.unitsPerEm)
+        const ratio = averageAdvanceWidth / unitsPerEm
+
+        return Number.isFinite(ratio) && ratio >= 0.3 && ratio <= 1.2
+            ? ratio
+            : null
+    }
+
+    /**
+     * Resolves padding around one inverted text primitive.
+     * @param {{ marginBorderWidth?: number }} text Text record.
+     * @param {number} fontSize Text font size.
+     * @returns {number}
+     */
+    static #resolveTextPadding(text, fontSize) {
+        const basePadding = Math.max(
+            fontSize * PcbTextPrimitiveRenderer.#TEXTURE_PADDING_RATIO,
+            PcbTextPrimitiveRenderer.#MIN_CANVAS_PADDING
+        )
+        const marginBorderWidth = Number(text?.marginBorderWidth)
+
+        return Number.isFinite(marginBorderWidth) && marginBorderWidth >= 0
+            ? marginBorderWidth
+            : basePadding
+    }
+
+    /**
+     * Resolves the local rectangle and baseline used to anchor SVG text at the
+     * Altium insertion point.
+     * @param {{ useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number }} text Text record.
+     * @param {{ width: number, height: number, ascent: number }} metrics Text metrics.
+     * @param {number} padding Background padding.
+     * @returns {{ width: number, height: number, baselineX: number, baselineY: number, anchorX: number, anchorY: number }}
+     */
+    static #resolveTextLayout(text, metrics, padding) {
+        const authoredRectangle =
+            PcbTextPrimitiveRenderer.#resolveAuthoredRectangle(text)
+        const width =
+            authoredRectangle?.width ||
+            Math.max(Number(metrics.width || 0), 1) + padding * 2
+        const height =
+            authoredRectangle?.height ||
+            Math.max(Number(metrics.height || 0), 1) + padding * 2
+
+        if (!authoredRectangle) {
+            return {
+                width,
+                height,
+                baselineX: padding,
+                baselineY: padding + Number(metrics.ascent || 0),
+                anchorX: padding,
+                anchorY: padding + Number(metrics.ascent || 0)
+            }
+        }
+
+        const baselineX = PcbTextPrimitiveRenderer.#authoredBaselineX(
+            text,
+            metrics,
+            width,
+            padding
+        )
+        const baselineY = PcbTextPrimitiveRenderer.#authoredBaselineY(
+            text,
+            metrics,
+            height,
+            padding
+        )
+
+        return {
+            width,
+            height,
+            baselineX,
+            baselineY,
+            anchorX: baselineX,
+            anchorY: baselineY
+        }
+    }
+
+    /**
+     * Resolves authored inverted rectangle dimensions from source metadata.
+     * @param {{ useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number }} text Text record.
+     * @returns {{ width: number, height: number } | null}
+     */
+    static #resolveAuthoredRectangle(text) {
+        const width = Number(text?.textboxRectWidth)
+        const height = Number(text?.textboxRectHeight)
+
+        if (
+            !Boolean(text?.useInvertedRectangle) ||
+            !Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0 ||
+            height <= 0
+        ) {
+            return null
+        }
+
+        return { width, height }
+    }
+
+    /**
+     * Resolves horizontal baseline placement inside an authored rectangle.
+     * @param {{ textboxRectJustification?: number }} text Text record.
+     * @param {{ width: number }} metrics Text metrics.
+     * @param {number} width Rectangle width.
+     * @param {number} padding Background padding.
+     * @returns {number}
+     */
+    static #authoredBaselineX(text, metrics, width, padding) {
+        const column = PcbTextPrimitiveRenderer.#justificationColumn(text)
+        const remainingWidth = Math.max(width - Number(metrics.width || 0), 0)
+
+        if (column === 1) {
+            return remainingWidth / 2
+        }
+
+        if (column === 2) {
+            return remainingWidth
+        }
+
+        return Math.min(padding, remainingWidth)
+    }
+
+    /**
+     * Resolves vertical baseline placement inside an authored rectangle.
+     * @param {{ textboxRectJustification?: number }} text Text record.
+     * @param {{ height: number, ascent: number }} metrics Text metrics.
+     * @param {number} height Rectangle height.
+     * @param {number} padding Background padding.
+     * @returns {number}
+     */
+    static #authoredBaselineY(text, metrics, height, padding) {
+        const row = PcbTextPrimitiveRenderer.#justificationRow(text)
+        const remainingHeight = Math.max(
+            height - Number(metrics.height || 0),
+            0
+        )
+
+        if (row === 1) {
+            return remainingHeight / 2 + Number(metrics.ascent || 0)
+        }
+
+        if (row === 2) {
+            return remainingHeight + Number(metrics.ascent || 0)
+        }
+
+        return Math.min(padding, remainingHeight) + Number(metrics.ascent || 0)
+    }
+
+    /**
+     * Resolves the authored horizontal justification column.
+     * @param {{ textboxRectJustification?: number }} text Text record.
+     * @returns {0 | 1 | 2 | null}
+     */
+    static #justificationColumn(text) {
+        const justification = Number(text?.textboxRectJustification)
+
+        return Number.isInteger(justification) && justification > 0
+            ? Math.max(0, Math.min(2, Math.floor((justification - 1) / 3)))
+            : null
+    }
+
+    /**
+     * Resolves the authored vertical justification row.
+     * @param {{ textboxRectJustification?: number }} text Text record.
+     * @returns {0 | 1 | 2 | null}
+     */
+    static #justificationRow(text) {
+        const justification = Number(text?.textboxRectJustification)
+
+        return Number.isInteger(justification) && justification > 0
+            ? (justification - 1) % 3
+            : null
+    }
+
+    /**
+     * Removes fixed-field padding from one font family name.
+     * @param {unknown} family Font family value.
+     * @returns {string}
+     */
+    static #cleanFontFamily(family) {
+        const cleaned = String(
+            family || PcbTextPrimitiveRenderer.#DEFAULT_FONT_FAMILY
+        )
+            .split('\0')[0]
+            ?.trim()
+
+        return cleaned || PcbTextPrimitiveRenderer.#DEFAULT_FONT_FAMILY
+    }
+
+    /**
+     * Checks whether one font family is a common monospace PCB font.
+     * @param {unknown} family Font family value.
+     * @returns {boolean}
+     */
+    static #isMonospaceFamily(family) {
+        return /^(consolas|courier|courier new|menlo|monaco|liberation mono)$/iu.test(
+            PcbTextPrimitiveRenderer.#cleanFontFamily(family)
+        )
+    }
+
+    /**
+     * Checks whether an imported family is Arial-like.
+     * @param {unknown} family Font family value.
+     * @returns {boolean}
+     */
+    static #isArialFamily(family) {
+        return /^arial(?:\b|$)/iu.test(
+            PcbTextPrimitiveRenderer.#cleanFontFamily(family)
+        )
+    }
+
+    /**
+     * Formats concise text metrics without keeping cosmetic trailing zeros.
+     * @param {number} value Numeric metric value.
+     * @returns {string}
+     */
+    static #formatTextNumber(value) {
+        return SchematicSvgUtils.formatNumber(value)
+            .replace(/(\.\d*?)0+$/u, '$1')
+            .replace(/\.$/u, '')
+    }
+
     /**
      * Renders optional SVG font attributes for TrueType text primitives.
      * @param {{ fontFamily?: string, fontWeight?: number, fontStyle?: string }} text
@@ -114,10 +729,10 @@ export class PcbTextPrimitiveRenderer {
     /**
      * Renders one or more text lines with SVG tspans.
      * @param {string[]} lines
-     * @param {number} fontSize
+     * @param {number} lineStep
      * @returns {string}
      */
-    static #renderTextLines(lines, fontSize) {
+    static #renderTextLines(lines, lineStep) {
         if (lines.length === 1) {
             return SchematicSvgUtils.escapeHtml(lines[0])
         }
@@ -126,7 +741,7 @@ export class PcbTextPrimitiveRenderer {
             .map(
                 (line, index) =>
                     '<tspan x="0" dy="' +
-                    SchematicSvgUtils.formatNumber(index === 0 ? 0 : fontSize) +
+                    SchematicSvgUtils.formatNumber(index === 0 ? 0 : lineStep) +
                     '">' +
                     SchematicSvgUtils.escapeHtml(line) +
                     '</tspan>'
@@ -249,4 +864,18 @@ export class PcbTextPrimitiveRenderer {
     static #isPlaceholderText(text) {
         return text?.isPlaceholder === true
     }
+
+    /**
+     * Returns true when native overlay holes already contain inverted glyphs.
+     * @param {{ isInverted?: boolean, fontType?: number | string, fontTypeName?: string, isTrueType?: boolean }} text Text record.
+     * @param {{ nativeTextKnockouts?: boolean }} options Selection options.
+     * @returns {boolean}
+     */
+    static #shouldSkipNativeTextKnockout(text, options) {
+        return (
+            Boolean(options?.nativeTextKnockouts) &&
+            Boolean(text?.isInverted) &&
+            PcbTextPrimitiveRenderer.#isTrueTypeText(text)
+        )
+    }
 }