altium-toolkit 1.4.10 → 1.4.11

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

@@ -0,0 +1,34 @@
+# altium-toolkit 1.4.11
+
+Version 1.4.11 restores complete native schematic fidelity for embedded
+template frames, footer metadata, signal harnesses, and rotated passive text.
+
+## Native schematic fidelity
+
+- Structurally proven embedded template dimensions remain the authored render
+  frame instead of being replaced by a sparse-content estimate.
+- Complete footer owner groups resolve organization, address, approval, and
+  other native metadata rows from the ownership sidecar.
+- Signal harness trunks, connector brackets, entries, and type labels render as
+  first-class SVG primitives with native additional-list ownership.
+- Right-side vertical component parameters clear narrow passive bodies while
+  left-side designators retain their authored columns.
+
+## Compatibility
+
+- Historical parser and renderer sources remain byte-for-byte frozen.
+- Repairs are isolated to the convergence layer used by current toolkit
+  consumers and do not change public parser or renderer signatures.
+- Geometry and ownership decisions derive from native structure rather than
+  project names, labels, filenames, or fixture-specific values.
+- Existing schematic theme variables, palette behavior, canvas border, and
+  title-block chrome remain unchanged.
+
+## Verification
+
+- Obfuscated repository-owned regressions cover native-frame proof, complete
+  footer owners, implicit harness children, themed harness SVG, and vertical
+  passive annotation columns.
+- The complete package suite, immutable-source checks, feature-preservation
+  check, formatting check, performance guard, and npm package dry run are
+  required for release.

package/package.json

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

package/src/convergence/AltiumSchematicFidelityNormalizer.mjs

@@ -0,0 +1,661 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from '../core/altium/ParserUtils.mjs'
+import { SchematicTypography } from '../ui/SchematicTypography.mjs'
+import { SchematicRotatedOwnerTextPlacement } from '../ui/SchematicRotatedOwnerTextPlacement.mjs'
+
+const PRIMITIVE_FAMILIES = Object.freeze([
+    'lines',
+    'polygons',
+    'rectangles',
+    'roundedRectangles',
+    'ellipses',
+    'arcs',
+    'pies'
+])
+
+/**
+ * Repairs render-only schematic fidelity from the native ownership sidecar
+ * without changing the preserved historical parser or renderer contracts.
+ */
+export class AltiumSchematicFidelityNormalizer {
+    /**
+     * Builds a shallow normalized view for convergence rendering.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @returns {Record<string, any>} Fidelity-normalized render document.
+     */
+    static normalize(documentModel) {
+        const schematic = documentModel?.schematic
+        if (!schematic) return documentModel
+
+        const records = schematic.ownership?.records || []
+        const sheet = AltiumSchematicFidelityNormalizer.#normalizeSheet(
+            schematic,
+            records
+        )
+        const ownerBounds =
+            AltiumSchematicFidelityNormalizer.#collectOwnerBounds(schematic)
+        const footerTexts =
+            AltiumSchematicFidelityNormalizer.#resolveFooterTexts(
+                schematic.texts || [],
+                records,
+                sheet
+            )
+        const texts = AltiumSchematicFidelityNormalizer.#placeOwnerTexts(
+            footerTexts,
+            ownerBounds
+        ).filter((text) => String(text?.recordType || '') !== '217')
+        const harnesses = AltiumSchematicFidelityNormalizer.#normalizeHarnesses(
+            schematic.harnesses,
+            records
+        )
+
+        if (
+            sheet === schematic.sheet &&
+            texts === schematic.texts &&
+            harnesses === schematic.harnesses
+        ) {
+            return documentModel
+        }
+
+        return {
+            ...documentModel,
+            schematic: {
+                ...schematic,
+                sheet,
+                texts,
+                ...(harnesses ? { harnesses } : {})
+            }
+        }
+    }
+
+    /**
+     * Restores a proven embedded native frame from source sheet dimensions.
+     * @param {Record<string, any>} schematic Native schematic model.
+     * @param {Record<string, any>[]} records Ownership records.
+     * @returns {Record<string, any>} Original or normalized sheet.
+     */
+    static #normalizeSheet(schematic, records) {
+        const sheet = schematic.sheet || {}
+        const sourceWidth = Number(sheet.sourceWidth || 0)
+        const sourceHeight = Number(sheet.sourceHeight || 0)
+        const margin = Math.max(Number(sheet.marginWidth || 20), 20)
+        const sheetRecord = records.find(
+            (record) =>
+                AltiumSchematicFidelityNormalizer.#recordType(record) === '31'
+        )
+        const sheetStyle = Number(
+            AltiumSchematicFidelityNormalizer.#field(
+                sheetRecord?.fields,
+                'SheetStyle'
+            ) || 0
+        )
+
+        if (
+            sheetStyle !== 1 ||
+            !sheet.borderOn ||
+            !sheet.paperSize ||
+            sourceWidth <= margin * 2 ||
+            sourceHeight <= margin * 2 ||
+            Number(sheet.width) >= Number(sheet.height) !==
+                sourceWidth >= sourceHeight ||
+            !AltiumSchematicFidelityNormalizer.#hasNativeFrameEdge(
+                schematic,
+                sourceWidth,
+                sourceHeight,
+                margin
+            )
+        ) {
+            return sheet
+        }
+
+        if (
+            Number(sheet.width) === sourceWidth &&
+            Number(sheet.height) === sourceHeight
+        ) {
+            return sheet
+        }
+
+        return {
+            ...sheet,
+            width: sourceWidth,
+            height: sourceHeight,
+            sourceWidth,
+            sourceHeight
+        }
+    }
+
+    /**
+     * Returns true when owner chrome reaches the stored native frame edge and
+     * all authored geometry remains inside that frame.
+     * @param {Record<string, any>} schematic Native schematic model.
+     * @param {number} sourceWidth Stored sheet width.
+     * @param {number} sourceHeight Stored sheet height.
+     * @param {number} margin Sheet margin.
+     * @returns {boolean} Whether the source frame is structurally proven.
+     */
+    static #hasNativeFrameEdge(schematic, sourceWidth, sourceHeight, margin) {
+        const primitives = PRIMITIVE_FAMILIES.flatMap(
+            (family) => schematic[family] || []
+        )
+        const bounds = primitives
+            .map((primitive) => ({
+                ownerIndex: String(primitive?.ownerIndex || '').trim(),
+                bounds: AltiumSchematicFidelityNormalizer.#bounds(primitive)
+            }))
+            .filter((entry) => entry.bounds)
+        const frameEdge = sourceWidth - margin
+
+        return (
+            bounds.some(
+                (entry) =>
+                    entry.ownerIndex &&
+                    Math.abs(entry.bounds.maxX - frameEdge) <= 0.01
+            ) &&
+            bounds.every(
+                (entry) =>
+                    entry.bounds.maxX <= sourceWidth - margin + 0.01 &&
+                    entry.bounds.maxY <= sourceHeight - margin + 0.01
+            )
+        )
+    }
+
+    /**
+     * Resolves every text placeholder in a native footer owner group.
+     * @param {Record<string, any>[]} texts Normalized visible texts.
+     * @param {Record<string, any>[]} records Ownership records.
+     * @param {Record<string, any>} sheet Normalized sheet.
+     * @returns {Record<string, any>[]} Original or resolved texts.
+     */
+    static #resolveFooterTexts(texts, records, sheet) {
+        const metadata = new Map()
+        for (const record of records) {
+            if (AltiumSchematicFidelityNormalizer.#owner(record)) continue
+            const name = AltiumSchematicFidelityNormalizer.#field(
+                record.fields,
+                'Name'
+            )
+            const value = AltiumSchematicFidelityNormalizer.#field(
+                record.fields,
+                'Text'
+            )
+            if (name && value) {
+                metadata.set(name.toLowerCase(), value)
+            }
+        }
+
+        const footerOwners = new Set(
+            records
+                .filter((record) =>
+                    AltiumSchematicFidelityNormalizer.#isFooterSeedRecord(
+                        record,
+                        sheet
+                    )
+                )
+                .map((record) =>
+                    AltiumSchematicFidelityNormalizer.#owner(record)
+                )
+                .filter(Boolean)
+        )
+        if (!footerOwners.size || !metadata.size) return texts
+
+        let changed = false
+        const resolvedTexts = texts.map((text) => {
+            const sourceText = String(text?.text || '').trim()
+            if (
+                !footerOwners.has(String(text?.ownerIndex || '').trim()) ||
+                !sourceText.startsWith('=')
+            ) {
+                return text
+            }
+
+            const replacement = metadata.get(sourceText.slice(1).toLowerCase())
+            if (!replacement) return text
+
+            changed = true
+            return { ...text, text: replacement }
+        })
+
+        return changed ? resolvedTexts : texts
+    }
+
+    /**
+     * Returns true when an ownership record seeds the lower-right footer.
+     * @param {Record<string, any>} record Ownership record.
+     * @param {Record<string, any>} sheet Sheet metadata.
+     * @returns {boolean} Whether the record belongs to a footer owner.
+     */
+    static #isFooterSeedRecord(record, sheet) {
+        if (AltiumSchematicFidelityNormalizer.#recordType(record) !== '4') {
+            return false
+        }
+
+        const x = Number(
+            AltiumSchematicFidelityNormalizer.#field(
+                record.fields,
+                'Location.X'
+            )
+        )
+        const y = Number(
+            AltiumSchematicFidelityNormalizer.#field(
+                record.fields,
+                'Location.Y'
+            )
+        )
+
+        return (
+            Number.isFinite(x) &&
+            Number.isFinite(y) &&
+            x >= Number(sheet?.width || 0) * 0.55 &&
+            y <= 100
+        )
+    }
+
+    /**
+     * Moves right-side vertical component parameters clear of owner bodies.
+     * @param {Record<string, any>[]} texts Schematic text rows.
+     * @param {Map<string, { minX: number, minY: number, maxX: number, maxY: number }>} ownerBounds Owner bounds.
+     * @returns {Record<string, any>[]} Original or placed texts.
+     */
+    static #placeOwnerTexts(texts, ownerBounds) {
+        let changed = false
+        const placedTexts = texts.map((text) => {
+            const viewerFontSize =
+                SchematicTypography.resolveViewerFontSize(text?.fontSize) || 0
+            const x = SchematicRotatedOwnerTextPlacement.resolveX(
+                text,
+                text?.x,
+                viewerFontSize,
+                ownerBounds
+            )
+            if (x === Number(text?.x)) return text
+
+            changed = true
+            return { ...text, x }
+        })
+
+        return changed ? placedTexts : texts
+    }
+
+    /**
+     * Completes harness child ownership from explicit and additional-list rows.
+     * @param {Record<string, any> | null | undefined} harnesses Harness model.
+     * @param {Record<string, any>[]} records Ownership records.
+     * @returns {Record<string, any> | null | undefined} Completed harness model.
+     */
+    static #normalizeHarnesses(harnesses, records) {
+        if (!harnesses?.connectors?.length) return harnesses
+
+        let changed = false
+        const connectors = harnesses.connectors.map((connector) => {
+            const connectorRecord = records.find(
+                (record) =>
+                    record.key === connector.recordKey ||
+                    String(record.recordId || '') ===
+                        String(connector.recordId || '')
+            )
+            if (!connectorRecord) return connector
+
+            const children = AltiumSchematicFidelityNormalizer.#harnessChildren(
+                connectorRecord,
+                records
+            )
+            const entryRecords = children.filter(
+                (record) =>
+                    AltiumSchematicFidelityNormalizer.#recordType(record) ===
+                    '216'
+            )
+            const typeRecord = children.find(
+                (record) =>
+                    AltiumSchematicFidelityNormalizer.#recordType(record) ===
+                    '217'
+            )
+            if (!entryRecords.length && !typeRecord) return connector
+
+            changed = true
+            return {
+                ...connector,
+                entries: entryRecords.map((record) =>
+                    AltiumSchematicFidelityNormalizer.#harnessEntry(record)
+                ),
+                ...(typeRecord
+                    ? {
+                          typeLabel:
+                              AltiumSchematicFidelityNormalizer.#harnessTypeLabel(
+                                  typeRecord
+                              )
+                      }
+                    : {})
+            }
+        })
+        if (!changed) return harnesses
+
+        return {
+            ...harnesses,
+            connectors,
+            bundleLinks: (harnesses.bundleLinks || []).map((link, index) => {
+                const connector = connectors[index]
+                return {
+                    ...link,
+                    harnessType:
+                        connector?.typeLabel?.text ||
+                        connector?.entries?.find((entry) => entry.harnessType)
+                            ?.harnessType,
+                    entries: (connector?.entries || []).map(
+                        (entry) => entry.name
+                    )
+                }
+            })
+        }
+    }
+
+    /**
+     * Collects connector children using native explicit and list ownership.
+     * @param {Record<string, any>} connectorRecord Connector ownership row.
+     * @param {Record<string, any>[]} records Ownership records.
+     * @returns {Record<string, any>[]} Child rows.
+     */
+    static #harnessChildren(connectorRecord, records) {
+        const position = records.indexOf(connectorRecord)
+        const ownerKeys = new Set([
+            String(connectorRecord.recordIndex ?? ''),
+            String(Number(connectorRecord.recordIndex ?? -1) + 1),
+            AltiumSchematicFidelityNormalizer.#field(
+                connectorRecord.fields,
+                'IndexInSheet'
+            ),
+            String(
+                Number(
+                    AltiumSchematicFidelityNormalizer.#field(
+                        connectorRecord.fields,
+                        'IndexInSheet'
+                    ) || -1
+                ) + 1
+            )
+        ])
+        const children = records.filter((record) => {
+            const recordType =
+                AltiumSchematicFidelityNormalizer.#recordType(record)
+            return (
+                (recordType === '216' || recordType === '217') &&
+                ownerKeys.has(AltiumSchematicFidelityNormalizer.#owner(record))
+            )
+        })
+
+        for (let index = position + 1; position >= 0; index += 1) {
+            const record = records[index]
+            const recordType =
+                AltiumSchematicFidelityNormalizer.#recordType(record)
+            if (recordType !== '216' && recordType !== '217') break
+            if (
+                AltiumSchematicFidelityNormalizer.#owner(record) ||
+                !ParserUtils.parseBoolean(
+                    AltiumSchematicFidelityNormalizer.#field(
+                        record.fields,
+                        'OwnerIndexAdditionalList'
+                    )
+                )
+            ) {
+                break
+            }
+            if (!children.includes(record)) children.push(record)
+        }
+
+        return children
+    }
+
+    /**
+     * Builds one normalized harness entry.
+     * @param {Record<string, any>} record Ownership row.
+     * @returns {Record<string, any>} Harness entry.
+     */
+    static #harnessEntry(record) {
+        const fields = record.fields || {}
+        const whole = Number(
+            AltiumSchematicFidelityNormalizer.#field(
+                fields,
+                'DistanceFromTop'
+            ) || 0
+        )
+        const fraction = Number(
+            AltiumSchematicFidelityNormalizer.#field(
+                fields,
+                'DistanceFromTop_Frac1'
+            ) || 0
+        )
+
+        return AltiumSchematicFidelityNormalizer.#stripEmpty({
+            key: 'harness-entry-' + String(record.recordIndex ?? 0),
+            recordKey: record.key,
+            name: AltiumSchematicFidelityNormalizer.#field(fields, 'Name'),
+            side: AltiumSchematicFidelityNormalizer.#side(
+                AltiumSchematicFidelityNormalizer.#field(fields, 'Side')
+            ),
+            distanceFromTop: Number(
+                (whole * 10 + fraction / 100000).toFixed(4)
+            ),
+            harnessType: AltiumSchematicFidelityNormalizer.#field(
+                fields,
+                'HarnessType'
+            ),
+            textStyle: AltiumSchematicFidelityNormalizer.#textStyle(
+                AltiumSchematicFidelityNormalizer.#field(fields, 'TextStyle')
+            ),
+            textColor: ParserUtils.toColor(fields.TEXTCOLOR, '#000000')
+        })
+    }
+
+    /**
+     * Builds one normalized harness type label.
+     * @param {Record<string, any>} record Ownership row.
+     * @returns {Record<string, any>} Harness type label.
+     */
+    static #harnessTypeLabel(record) {
+        const fields = record.fields || {}
+        return {
+            key: 'harness-type-' + String(record.recordIndex ?? 0),
+            recordKey: record.key,
+            text: AltiumSchematicFidelityNormalizer.#field(fields, 'Text'),
+            x: Number(
+                AltiumSchematicFidelityNormalizer.#field(
+                    fields,
+                    'Location.X'
+                ) || 0
+            ),
+            y: Number(
+                AltiumSchematicFidelityNormalizer.#field(
+                    fields,
+                    'Location.Y'
+                ) || 0
+            ),
+            color: ParserUtils.toColor(fields.COLOR, '#000000')
+        }
+    }
+
+    /**
+     * Collects owner envelopes for rotated parameter placement.
+     * @param {Record<string, any>} schematic Native schematic model.
+     * @returns {Map<string, { minX: number, minY: number, maxX: number, maxY: number }>}
+     */
+    static #collectOwnerBounds(schematic) {
+        const ownerBounds = new Map()
+        for (const primitive of PRIMITIVE_FAMILIES.flatMap(
+            (family) => schematic[family] || []
+        )) {
+            const owner = String(primitive?.ownerIndex || '').trim()
+            const bounds = AltiumSchematicFidelityNormalizer.#bounds(primitive)
+            if (!owner || !bounds) continue
+
+            const current = ownerBounds.get(owner)
+            if (!current) {
+                ownerBounds.set(owner, { ...bounds })
+                continue
+            }
+            current.minX = Math.min(current.minX, bounds.minX)
+            current.minY = Math.min(current.minY, bounds.minY)
+            current.maxX = Math.max(current.maxX, bounds.maxX)
+            current.maxY = Math.max(current.maxY, bounds.maxY)
+        }
+        return ownerBounds
+    }
+
+    /**
+     * Resolves primitive coordinate bounds.
+     * @param {Record<string, any>} primitive Primitive row.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null}
+     */
+    static #bounds(primitive) {
+        const points = []
+        if (Array.isArray(primitive?.points)) points.push(...primitive.points)
+        if (
+            Number.isFinite(Number(primitive?.x1)) &&
+            Number.isFinite(Number(primitive?.y1)) &&
+            Number.isFinite(Number(primitive?.x2)) &&
+            Number.isFinite(Number(primitive?.y2))
+        ) {
+            points.push(
+                { x: Number(primitive.x1), y: Number(primitive.y1) },
+                { x: Number(primitive.x2), y: Number(primitive.y2) }
+            )
+        } else if (
+            Number.isFinite(Number(primitive?.x)) &&
+            Number.isFinite(Number(primitive?.y)) &&
+            Number.isFinite(Number(primitive?.width)) &&
+            Number.isFinite(Number(primitive?.height))
+        ) {
+            points.push(
+                { x: Number(primitive.x), y: Number(primitive.y) },
+                {
+                    x: Number(primitive.x) + Number(primitive.width),
+                    y: Number(primitive.y) + Number(primitive.height)
+                }
+            )
+        } else if (
+            Number.isFinite(Number(primitive?.x)) &&
+            Number.isFinite(Number(primitive?.y)) &&
+            (Number.isFinite(Number(primitive?.radius)) ||
+                Number.isFinite(Number(primitive?.radiusX)))
+        ) {
+            const radiusX = Math.abs(
+                Number(primitive.radiusX ?? primitive.radius)
+            )
+            const radiusY = Math.abs(
+                Number(primitive.radiusY ?? primitive.radius)
+            )
+            points.push(
+                {
+                    x: Number(primitive.x) - radiusX,
+                    y: Number(primitive.y) - radiusY
+                },
+                {
+                    x: Number(primitive.x) + radiusX,
+                    y: Number(primitive.y) + radiusY
+                }
+            )
+        }
+
+        const finitePoints = points.filter(
+            (point) =>
+                Number.isFinite(Number(point?.x)) &&
+                Number.isFinite(Number(point?.y))
+        )
+        if (!finitePoints.length) return null
+
+        return {
+            minX: Math.min(...finitePoints.map((point) => Number(point.x))),
+            minY: Math.min(...finitePoints.map((point) => Number(point.y))),
+            maxX: Math.max(...finitePoints.map((point) => Number(point.x))),
+            maxY: Math.max(...finitePoints.map((point) => Number(point.y)))
+        }
+    }
+
+    /**
+     * Resolves one ownership record type.
+     * @param {Record<string, any> | undefined} record Ownership row.
+     * @returns {string} Record type.
+     */
+    static #recordType(record) {
+        return String(
+            record?.recordType ??
+                AltiumSchematicFidelityNormalizer.#field(
+                    record?.fields,
+                    'Record'
+                ) ??
+                ''
+        )
+    }
+
+    /**
+     * Resolves one ownership key.
+     * @param {Record<string, any> | undefined} record Ownership row.
+     * @returns {string} Owner key.
+     */
+    static #owner(record) {
+        return String(
+            record?.ownerIndex ??
+                AltiumSchematicFidelityNormalizer.#field(
+                    record?.fields,
+                    'OwnerIndex'
+                ) ??
+                ''
+        ).trim()
+    }
+
+    /**
+     * Reads one case-insensitive raw field.
+     * @param {Record<string, any> | undefined} fields Raw fields.
+     * @param {string} name Field name.
+     * @returns {string} Field value.
+     */
+    static #field(fields, name) {
+        if (!fields) return ''
+        const key = Object.keys(fields).find(
+            (candidate) => candidate.toLowerCase() === name.toLowerCase()
+        )
+        const value = key ? fields[key] : ''
+        return String(Array.isArray(value) ? value.at(-1) || '' : value || '')
+    }
+
+    /**
+     * Resolves native side codes.
+     * @param {string | number} value Native side code.
+     * @returns {'left' | 'right' | 'top' | 'bottom'} Side label.
+     */
+    static #side(value) {
+        return ['left', 'right', 'top', 'bottom'][Number(value)] || 'left'
+    }
+
+    /**
+     * Resolves native harness entry text style.
+     * @param {string} value Native style.
+     * @returns {string} Normalized style.
+     */
+    static #textStyle(value) {
+        const normalized = String(value || '').toLowerCase()
+        if (normalized === '1' || normalized === 'abbreviated') {
+            return 'abbreviated'
+        }
+        if (normalized === '2' || normalized === 'short') return 'short'
+        return 'full'
+    }
+
+    /**
+     * Removes empty fields while retaining false and zero.
+     * @param {Record<string, any>} value Candidate record.
+     * @returns {Record<string, any>} Compact record.
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value).filter(
+                ([, fieldValue]) =>
+                    fieldValue !== null &&
+                    fieldValue !== undefined &&
+                    fieldValue !== ''
+            )
+        )
+    }
+}
+
+Object.freeze(AltiumSchematicFidelityNormalizer.prototype)
+Object.freeze(AltiumSchematicFidelityNormalizer)

package/src/convergence/SchematicSvgRenderer.mjs

@@ -4,6 +4,8 @@
 import { SchematicSvgRenderer as LegacySchematicSvgRenderer } from '../ui/SchematicSvgRenderer.mjs'
 import { AltiumSchematicImageNormalizer } from './AltiumSchematicImageNormalizer.mjs'
 import { AltiumSchematicNativeFooterOwnerAligner } from './AltiumSchematicNativeFooterOwnerAligner.mjs'
+import { AltiumSchematicFidelityNormalizer } from './AltiumSchematicFidelityNormalizer.mjs'
+import { SchematicHarnessRenderer } from '../ui/SchematicHarnessRenderer.mjs'
 
 /**
  * Renders native Altium schematic models through the preserved historical
@@ -21,12 +23,42 @@ export class SchematicSvgRenderer {
     static render(documentModel, options = {}) {
         const normalized =
             AltiumSchematicImageNormalizer.normalize(documentModel)
+        const fidelityNormalized =
+            AltiumSchematicFidelityNormalizer.normalize(normalized)
         const aligned =
-            AltiumSchematicNativeFooterOwnerAligner.align(normalized)
-        return LegacySchematicSvgRenderer.render(
-            SchematicSvgRenderer.#visibilityAwareDocument(aligned),
+            AltiumSchematicNativeFooterOwnerAligner.align(fidelityNormalized)
+        const renderDocument =
+            SchematicSvgRenderer.#visibilityAwareDocument(aligned)
+        const markup = LegacySchematicSvgRenderer.render(
+            renderDocument,
             options
         )
+
+        return SchematicSvgRenderer.#injectHarnessMarkup(markup, renderDocument)
+    }
+
+    /**
+     * Inserts first-class harness markup into the preserved SVG hierarchy.
+     * @param {string} markup Historical schematic SVG markup.
+     * @param {Record<string, any>} documentModel Fidelity-normalized document.
+     * @returns {string} SVG markup with harness primitives.
+     */
+    static #injectHarnessMarkup(markup, documentModel) {
+        if (markup.includes('class="schematic-harnesses"')) return markup
+
+        const schematic = documentModel?.schematic
+        const harnessMarkup = SchematicHarnessRenderer.buildMarkup(
+            schematic?.harnesses,
+            Number(schematic?.sheet?.height || 0),
+            schematic?.sheet || {}
+        )
+        if (!harnessMarkup) return markup
+
+        const marker = '<g class="schematic-images">'
+        return markup.replace(
+            marker,
+            '<g class="schematic-harnesses">' + harnessMarkup + '</g>' + marker
+        )
     }
 
     /**

package/src/ui/SchematicHarnessRenderer.mjs

@@ -0,0 +1,346 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+import { SchematicTypography } from './SchematicTypography.mjs'
+import { SchematicColorResolver } from './SchematicColorResolver.mjs'
+
+const { createSvgText, escapeHtml, formatNumber, projectSchematicY } =
+    SchematicSvgUtils
+
+/**
+ * Renders normalized signal harness trunks, connectors, entries, and labels.
+ */
+export class SchematicHarnessRenderer {
+    /**
+     * Builds complete harness markup.
+     * @param {{ connectors?: object[], signalHarnesses?: object[] } | null | undefined} harnesses
+     * @param {number} sheetHeight
+     * @param {{ fonts?: Record<string, { size: number, family: string, bold: boolean }> }} sheet
+     * @returns {string}
+     */
+    static buildMarkup(harnesses, sheetHeight, sheet) {
+        const signalHarnessMarkup = (harnesses?.signalHarnesses || [])
+            .map((signalHarness) =>
+                SchematicHarnessRenderer.#buildSignalHarnessMarkup(
+                    signalHarness,
+                    sheetHeight
+                )
+            )
+            .join('')
+        const connectorMarkup = (harnesses?.connectors || [])
+            .map((connector) =>
+                SchematicHarnessRenderer.#buildConnectorMarkup(
+                    connector,
+                    sheetHeight,
+                    sheet
+                )
+            )
+            .join('')
+
+        return signalHarnessMarkup + connectorMarkup
+    }
+
+    /**
+     * Builds one signal-harness polyline.
+     * @param {{ points?: { x: number, y: number }[], color?: string, lineWidth?: number }} signalHarness
+     * @param {number} sheetHeight
+     * @returns {string}
+     */
+    static #buildSignalHarnessMarkup(signalHarness, sheetHeight) {
+        const points = (signalHarness.points || [])
+            .map(
+                (point) =>
+                    formatNumber(point.x) +
+                    ',' +
+                    formatNumber(projectSchematicY(sheetHeight, point.y))
+            )
+            .join(' ')
+
+        if (!points) return ''
+
+        return (
+            '<polyline class="schematic-signal-harness" points="' +
+            escapeHtml(points) +
+            '" fill="none" stroke="' +
+            escapeHtml(
+                SchematicColorResolver.resolveNonTextColor(
+                    signalHarness.color,
+                    '--schematic-default-ink-color',
+                    true
+                )
+            ) +
+            '" stroke-width="' +
+            formatNumber(Math.max(Number(signalHarness.lineWidth) || 1, 1)) +
+            '" stroke-linecap="round" stroke-linejoin="round" />'
+        )
+    }
+
+    /**
+     * Builds one harness connector with its entry labels and type label.
+     * @param {{ x: number, y: number, width: number, height: number, side?: 'left' | 'right' | 'top' | 'bottom', primaryConnectionPosition?: number, lineWidth?: number, color?: string, fill?: string, entries?: object[], typeLabel?: object }} connector
+     * @param {number} sheetHeight
+     * @param {{ fonts?: Record<string, { size: number, family: string, bold: boolean }> }} sheet
+     * @returns {string}
+     */
+    static #buildConnectorMarkup(connector, sheetHeight, sheet) {
+        const stroke = SchematicColorResolver.resolveNonTextColor(
+            connector.color,
+            '--schematic-default-ink-color',
+            true
+        )
+        const fill = SchematicColorResolver.resolveFill(
+            connector.fill,
+            '--schematic-fill-light-color'
+        )
+        const textOptions =
+            SchematicTypography.buildDefaultSchematicFontOptions(sheet)
+        const entryMarkup = (connector.entries || [])
+            .map((entry) =>
+                SchematicHarnessRenderer.#buildEntryMarkup(
+                    connector,
+                    entry,
+                    sheetHeight,
+                    textOptions,
+                    stroke
+                )
+            )
+            .join('')
+        const typeMarkup = connector.typeLabel
+            ? SchematicHarnessRenderer.#buildTypeLabelMarkup(
+                  connector.typeLabel,
+                  sheetHeight,
+                  textOptions
+              )
+            : ''
+
+        return (
+            '<g class="schematic-harness-connector">' +
+            '<polygon points="' +
+            escapeHtml(
+                SchematicHarnessRenderer.#connectorPoints(
+                    connector,
+                    sheetHeight
+                )
+            ) +
+            '" fill="' +
+            escapeHtml(fill) +
+            '" stroke="' +
+            escapeHtml(stroke) +
+            '" stroke-width="' +
+            formatNumber(Math.max(Number(connector.lineWidth) || 1, 1)) +
+            '" stroke-linejoin="round" />' +
+            entryMarkup +
+            typeMarkup +
+            '</g>'
+        )
+    }
+
+    /**
+     * Builds the concave connector outline from its primary connection side.
+     * @param {{ x: number, y: number, width: number, height: number, side?: 'left' | 'right' | 'top' | 'bottom', primaryConnectionPosition?: number }} connector
+     * @param {number} sheetHeight
+     * @returns {string}
+     */
+    static #connectorPoints(connector, sheetHeight) {
+        const x = Number(connector.x) || 0
+        const y = Number(connector.y) || 0
+        const width = Math.max(Number(connector.width) || 0, 1)
+        const height = Math.max(Number(connector.height) || 0, 1)
+        const inset = Math.min(12, width / 3, height / 3)
+        const primary = Math.min(
+            Math.max(Number(connector.primaryConnectionPosition) || 0, 0),
+            connector.side === 'top' || connector.side === 'bottom'
+                ? width
+                : height
+        )
+        const side = connector.side || 'left'
+        let points
+
+        if (side === 'right') {
+            points = [
+                { x, y },
+                { x: x + width - inset, y },
+                { x: x + width, y: y - primary },
+                { x: x + width - inset, y: y - height },
+                { x, y: y - height }
+            ]
+        } else if (side === 'top') {
+            points = [
+                { x, y: y - inset },
+                { x: x + primary, y },
+                { x: x + width, y: y - inset },
+                { x: x + width, y: y - height },
+                { x, y: y - height }
+            ]
+        } else if (side === 'bottom') {
+            points = [
+                { x, y },
+                { x: x + width, y },
+                { x: x + width, y: y - height + inset },
+                { x: x + primary, y: y - height },
+                { x, y: y - height + inset }
+            ]
+        } else {
+            points = [
+                { x: x + inset, y },
+                { x: x + width, y },
+                { x: x + width, y: y - height },
+                { x: x + inset, y: y - height },
+                { x, y: y - primary }
+            ]
+        }
+
+        return points
+            .map(
+                (point) =>
+                    formatNumber(point.x) +
+                    ',' +
+                    formatNumber(projectSchematicY(sheetHeight, point.y))
+            )
+            .join(' ')
+    }
+
+    /**
+     * Builds one harness-entry stub and label.
+     * @param {{ x: number, y: number, width: number, height: number }} connector
+     * @param {{ name?: string, side?: 'left' | 'right' | 'top' | 'bottom', distanceFromTop?: number, textColor?: string }} entry
+     * @param {number} sheetHeight
+     * @param {{ fontSize: number, fontFamily: string, fontWeight: number }} textOptions
+     * @param {string} connectorStroke
+     * @returns {string}
+     */
+    static #buildEntryMarkup(
+        connector,
+        entry,
+        sheetHeight,
+        textOptions,
+        connectorStroke
+    ) {
+        const placement = SchematicHarnessRenderer.#entryPlacement(
+            connector,
+            entry,
+            sheetHeight
+        )
+        const labelColor = SchematicColorResolver.resolveColor(
+            entry.textColor,
+            '--schematic-default-ink-color',
+            true
+        )
+
+        return (
+            '<g class="schematic-harness-entry"><line x1="' +
+            formatNumber(placement.x1) +
+            '" y1="' +
+            formatNumber(placement.y1) +
+            '" x2="' +
+            formatNumber(placement.x2) +
+            '" y2="' +
+            formatNumber(placement.y2) +
+            '" stroke="' +
+            escapeHtml(connectorStroke) +
+            '" />' +
+            createSvgText(
+                'schematic-harness-entry-label',
+                placement.labelX,
+                placement.labelY,
+                entry.name || '',
+                labelColor,
+                placement.anchor,
+                textOptions
+            ) +
+            '</g>'
+        )
+    }
+
+    /**
+     * Resolves the entry stub and text placement for every connector side.
+     * @param {{ x: number, y: number, width: number, height: number }} connector
+     * @param {{ side?: 'left' | 'right' | 'top' | 'bottom', distanceFromTop?: number }} entry
+     * @param {number} sheetHeight
+     * @returns {{ x1: number, y1: number, x2: number, y2: number, labelX: number, labelY: number, anchor: 'start' | 'middle' | 'end' }}
+     */
+    static #entryPlacement(connector, entry, sheetHeight) {
+        const x = Number(connector.x) || 0
+        const y = Number(connector.y) || 0
+        const width = Number(connector.width) || 0
+        const height = Number(connector.height) || 0
+        const distance = Number(entry.distanceFromTop) || 0
+        const side = entry.side || 'right'
+        const baselineLift = 3
+
+        if (side === 'left') {
+            const entryY = projectSchematicY(sheetHeight, y - distance)
+            return {
+                x1: x,
+                y1: entryY,
+                x2: x - 10,
+                y2: entryY,
+                labelX: x - 14,
+                labelY: entryY + baselineLift,
+                anchor: 'end'
+            }
+        }
+        if (side === 'top') {
+            const entryX = x + distance
+            const entryY = projectSchematicY(sheetHeight, y)
+            return {
+                x1: entryX,
+                y1: entryY,
+                x2: entryX,
+                y2: entryY - 10,
+                labelX: entryX,
+                labelY: entryY - 13,
+                anchor: 'middle'
+            }
+        }
+        if (side === 'bottom') {
+            const entryX = x + distance
+            const entryY = projectSchematicY(sheetHeight, y - height)
+            return {
+                x1: entryX,
+                y1: entryY,
+                x2: entryX,
+                y2: entryY + 10,
+                labelX: entryX,
+                labelY: entryY + 19,
+                anchor: 'middle'
+            }
+        }
+
+        const entryY = projectSchematicY(sheetHeight, y - distance)
+        return {
+            x1: x + width,
+            y1: entryY,
+            x2: x + width + 10,
+            y2: entryY,
+            labelX: x + width + 14,
+            labelY: entryY + baselineLift,
+            anchor: 'start'
+        }
+    }
+
+    /**
+     * Builds the connector harness-type label.
+     * @param {{ text?: string, x: number, y: number, color?: string }} typeLabel
+     * @param {number} sheetHeight
+     * @param {{ fontSize: number, fontFamily: string, fontWeight: number }} textOptions
+     * @returns {string}
+     */
+    static #buildTypeLabelMarkup(typeLabel, sheetHeight, textOptions) {
+        return createSvgText(
+            'schematic-harness-type',
+            typeLabel.x,
+            projectSchematicY(sheetHeight, typeLabel.y),
+            typeLabel.text || '',
+            SchematicColorResolver.resolveColor(
+                typeLabel.color,
+                '--schematic-default-ink-color',
+                true
+            ),
+            'start',
+            textOptions
+        )
+    }
+}

package/src/ui/SchematicRotatedOwnerTextPlacement.mjs

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Places vertical owner annotations in columns clear of narrow symbol bodies.
+ */
+export class SchematicRotatedOwnerTextPlacement {
+    /**
+     * Resolves the horizontal baseline for one rotated owner annotation.
+     * @param {{ ownerIndex?: string, recordType?: string, rotation?: number }} text
+     * @param {number} sourceX
+     * @param {number} fontSize
+     * @param {Map<string, { minX: number, minY: number, maxX: number, maxY: number }>} ownerBodyBounds
+     * @returns {number}
+     */
+    static resolveX(text, sourceX, fontSize, ownerBodyBounds) {
+        const numericX = Number(sourceX)
+        const numericFontSize = Number(fontSize)
+        const ownerIndex = String(text?.ownerIndex || '').trim()
+        const rotation = SchematicRotatedOwnerTextPlacement.#normalizeDegrees(
+            text?.rotation
+        )
+
+        if (
+            text?.recordType !== '41' ||
+            !ownerIndex ||
+            (rotation !== 90 && rotation !== 270) ||
+            !Number.isFinite(numericX) ||
+            !Number.isFinite(numericFontSize) ||
+            numericFontSize <= 0
+        ) {
+            return numericX
+        }
+
+        const bounds = ownerBodyBounds.get(ownerIndex)
+        if (!bounds || numericX < Number(bounds.maxX)) {
+            return numericX
+        }
+
+        return numericX + numericFontSize
+    }
+
+    /**
+     * Normalizes a source angle to the positive 0-359 degree range.
+     * @param {number | undefined} value
+     * @returns {number}
+     */
+    static #normalizeDegrees(value) {
+        const numericValue = Number(value)
+        if (!Number.isFinite(numericValue)) return 0
+
+        return ((numericValue % 360) + 360) % 360
+    }
+}