altium-toolkit 1.4.12 → 1.4.14

package/package.json

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

package/src/convergence/AltiumDocumentBuilder.mjs

@@ -7,6 +7,7 @@ import { AltiumParser } from '../core/altium/AltiumParser.mjs'
 import { CircuitJsonModelAdapter } from '../core/circuit-json/CircuitJsonModelAdapter.mjs'
 import { CircuitJsonSchematicImageProjection } from '../core/circuit-json/CircuitJsonSchematicImageProjection.mjs'
 import { AltiumCircuitJsonProjection } from './AltiumCircuitJsonProjection.mjs'
+import { AltiumOleInputTailNormalizer } from './AltiumOleInputTailNormalizer.mjs'
 import { AltiumSchematicImageNormalizer } from './AltiumSchematicImageNormalizer.mjs'
 import { ParserInput } from './ParserInput.mjs'
 
@@ -20,7 +21,9 @@ export class AltiumDocumentBuilder {
      * @returns {{ native: Record<string, any>, model: object[], nativeSidecarCount: number }} Decoded source data.
      */
     static decode(normalized) {
-        const buffer = ParserInput.arrayBuffer(normalized.input.data)
+        const buffer = AltiumOleInputTailNormalizer.normalize(
+            ParserInput.arrayBuffer(normalized.input.data)
+        )
         const native = AltiumSchematicImageNormalizer.normalize(
             AltiumParser.parseArrayBufferToRendererModel(
                 normalized.input.fileName,

package/src/convergence/AltiumOleInputTailNormalizer.mjs

@@ -0,0 +1,541 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const HEADER_BYTE_LENGTH = 512
+const DIRECTORY_ENTRY_BYTE_LENGTH = 128
+const END_OF_CHAIN = -2
+const HEADER_SIGNATURE = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]
+const VALID_SECTOR_SHIFTS = new Set([9, 12])
+
+/**
+ * Restores omitted physical padding only after proving every logical OLE byte
+ * and structural sector is present.
+ */
+export class AltiumOleInputTailNormalizer {
+    /**
+     * Returns an aligned owned buffer when only unused final-sector padding is
+     * absent, otherwise preserves the original input for strict native errors.
+     * @param {ArrayBuffer} arrayBuffer OLE candidate bytes.
+     * @returns {ArrayBuffer} Original or safely padded bytes.
+     */
+    static normalize(arrayBuffer) {
+        if (!(arrayBuffer instanceof ArrayBuffer)) return arrayBuffer
+        const bytes = new Uint8Array(arrayBuffer)
+        if (!AltiumOleInputTailNormalizer.#hasOleSignature(bytes)) {
+            return arrayBuffer
+        }
+        if (bytes.byteLength < HEADER_BYTE_LENGTH) return arrayBuffer
+
+        const sourceView = new DataView(arrayBuffer)
+        const sectorShift = sourceView.getUint16(30, true)
+        if (!VALID_SECTOR_SHIFTS.has(sectorShift)) return arrayBuffer
+        const miniSectorShift = sourceView.getUint16(32, true)
+        if (miniSectorShift !== 6) return arrayBuffer
+        const sectorByteLength = 2 ** sectorShift
+        const miniSectorByteLength = 2 ** miniSectorShift
+        const payloadByteLength = bytes.byteLength - HEADER_BYTE_LENGTH
+        if (payloadByteLength % sectorByteLength === 0) return arrayBuffer
+
+        const alignedPayloadByteLength =
+            Math.ceil(payloadByteLength / sectorByteLength) * sectorByteLength
+        const normalizedBytes = new Uint8Array(
+            HEADER_BYTE_LENGTH + alignedPayloadByteLength
+        )
+        normalizedBytes.set(bytes)
+
+        try {
+            const isComplete =
+                AltiumOleInputTailNormalizer.#isLogicallyComplete(
+                    new DataView(normalizedBytes.buffer),
+                    bytes.byteLength,
+                    sectorByteLength,
+                    miniSectorByteLength
+                )
+            return isComplete ? normalizedBytes.buffer : arrayBuffer
+        } catch (_error) {
+            return arrayBuffer
+        }
+    }
+
+    /**
+     * Checks the OLE header signature without parsing the document.
+     * @param {Uint8Array} bytes Source bytes.
+     * @returns {boolean} Whether the signature matches.
+     */
+    static #hasOleSignature(bytes) {
+        return (
+            bytes.byteLength >= HEADER_SIGNATURE.length &&
+            HEADER_SIGNATURE.every((value, index) => bytes[index] === value)
+        )
+    }
+
+    /**
+     * Verifies structural sectors and every regular logical stream byte.
+     * @param {DataView} view Zero-padded aligned candidate view.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @param {number} miniSectorByteLength OLE mini-sector size.
+     * @returns {boolean} Whether padding cannot synthesize declared data.
+     */
+    static #isLogicallyComplete(
+        view,
+        sourceByteLength,
+        sectorByteLength,
+        miniSectorByteLength
+    ) {
+        const fatSectorIds = AltiumOleInputTailNormalizer.#collectFatSectorIds(
+            view,
+            sourceByteLength,
+            sectorByteLength
+        )
+        const numberOfFatSectors = view.getUint32(44, true)
+        if (!numberOfFatSectors || fatSectorIds.length < numberOfFatSectors) {
+            return false
+        }
+        const fatEntries = AltiumOleInputTailNormalizer.#readFatEntries(
+            view,
+            fatSectorIds.slice(0, numberOfFatSectors),
+            sourceByteLength,
+            sectorByteLength
+        )
+        if (fatEntries.length !== (numberOfFatSectors * sectorByteLength) / 4) {
+            return false
+        }
+        const directorySectorIds =
+            AltiumOleInputTailNormalizer.#readSectorChain(
+                view.getInt32(48, true),
+                fatEntries
+            )
+        if (
+            !directorySectorIds.length ||
+            !AltiumOleInputTailNormalizer.#hasFullSectors(
+                directorySectorIds,
+                sourceByteLength,
+                sectorByteLength
+            )
+        ) {
+            return false
+        }
+
+        const numberOfMiniFatSectors = view.getUint32(64, true)
+        let miniFatEntries = []
+        if (numberOfMiniFatSectors) {
+            const miniFatSectorIds =
+                AltiumOleInputTailNormalizer.#readSectorChain(
+                    view.getInt32(60, true),
+                    fatEntries
+                )
+            if (
+                miniFatSectorIds.length !== numberOfMiniFatSectors ||
+                !AltiumOleInputTailNormalizer.#hasFullSectors(
+                    miniFatSectorIds.slice(0, numberOfMiniFatSectors),
+                    sourceByteLength,
+                    sectorByteLength
+                )
+            ) {
+                return false
+            }
+            const miniFatBytes = AltiumOleInputTailNormalizer.#readFullSectors(
+                view,
+                miniFatSectorIds.slice(0, numberOfMiniFatSectors),
+                sectorByteLength
+            )
+            miniFatEntries =
+                AltiumOleInputTailNormalizer.#readInt32Entries(miniFatBytes)
+        }
+
+        const directoryBytes = AltiumOleInputTailNormalizer.#readFullSectors(
+            view,
+            directorySectorIds,
+            sectorByteLength
+        )
+        return AltiumOleInputTailNormalizer.#areStreamsComplete(
+            directoryBytes,
+            fatEntries,
+            miniFatEntries,
+            view.getUint32(56, true),
+            sourceByteLength,
+            sectorByteLength,
+            miniSectorByteLength,
+            Math.floor(
+                (sourceByteLength - HEADER_BYTE_LENGTH) / sectorByteLength
+            )
+        )
+    }
+
+    /**
+     * Decodes little-endian signed integers from structural table bytes.
+     * @param {Uint8Array} bytes Structural sector bytes.
+     * @returns {number[]} Decoded table entries.
+     */
+    static #readInt32Entries(bytes) {
+        const view = new DataView(
+            bytes.buffer,
+            bytes.byteOffset,
+            bytes.byteLength
+        )
+        const entries = []
+        for (let offset = 0; offset < bytes.byteLength; offset += 4) {
+            entries.push(view.getInt32(offset, true))
+        }
+        return entries
+    }
+
+    /**
+     * Collects FAT sector ids from the header and DIFAT chain.
+     * @param {DataView} view Aligned candidate view.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {number[]} FAT sector ids.
+     */
+    static #collectFatSectorIds(view, sourceByteLength, sectorByteLength) {
+        const sectorIds = []
+        for (let index = 0; index < 109; index += 1) {
+            const sectorId = view.getInt32(76 + index * 4, true)
+            if (sectorId >= 0) sectorIds.push(sectorId)
+        }
+
+        const numberOfDifatSectors = view.getUint32(72, true)
+        let currentSectorId = view.getInt32(68, true)
+        const visited = new Set()
+        const entriesPerSector = sectorByteLength / 4
+        for (
+            let index = 0;
+            index < numberOfDifatSectors && currentSectorId >= 0;
+            index += 1
+        ) {
+            if (visited.has(currentSectorId)) return []
+            visited.add(currentSectorId)
+            if (
+                !AltiumOleInputTailNormalizer.#hasFullSector(
+                    currentSectorId,
+                    sourceByteLength,
+                    sectorByteLength
+                )
+            ) {
+                return []
+            }
+            const offset =
+                HEADER_BYTE_LENGTH + currentSectorId * sectorByteLength
+            for (let entry = 0; entry < entriesPerSector - 1; entry += 1) {
+                const sectorId = view.getInt32(offset + entry * 4, true)
+                if (sectorId >= 0) sectorIds.push(sectorId)
+            }
+            currentSectorId = view.getInt32(
+                offset + (entriesPerSector - 1) * 4,
+                true
+            )
+        }
+        if (numberOfDifatSectors && visited.size !== numberOfDifatSectors) {
+            return []
+        }
+        return sectorIds
+    }
+
+    /**
+     * Reads every FAT entry from complete FAT sectors.
+     * @param {DataView} view Aligned candidate view.
+     * @param {number[]} sectorIds FAT sector ids.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {number[]} FAT entries.
+     */
+    static #readFatEntries(
+        view,
+        sectorIds,
+        sourceByteLength,
+        sectorByteLength
+    ) {
+        if (
+            !AltiumOleInputTailNormalizer.#hasFullSectors(
+                sectorIds,
+                sourceByteLength,
+                sectorByteLength
+            )
+        ) {
+            return []
+        }
+        const entries = []
+        for (const sectorId of sectorIds) {
+            const offset = HEADER_BYTE_LENGTH + sectorId * sectorByteLength
+            for (let index = 0; index < sectorByteLength / 4; index += 1) {
+                entries.push(view.getInt32(offset + index * 4, true))
+            }
+        }
+        return entries
+    }
+
+    /**
+     * Reads one FAT chain with loop and bounds protection.
+     * @param {number} startSectorId First sector id.
+     * @param {number[]} fatEntries FAT entries.
+     * @returns {number[]} Ordered sector ids, or an empty invalid chain.
+     */
+    static #readSectorChain(startSectorId, fatEntries) {
+        if (startSectorId < 0) return []
+        const sectorIds = []
+        const visited = new Set()
+        let currentSectorId = startSectorId
+        while (currentSectorId >= 0) {
+            if (
+                currentSectorId >= fatEntries.length ||
+                visited.has(currentSectorId)
+            ) {
+                return []
+            }
+            visited.add(currentSectorId)
+            sectorIds.push(currentSectorId)
+            const nextSectorId = fatEntries[currentSectorId]
+            if (nextSectorId === END_OF_CHAIN) return sectorIds
+            if (!Number.isInteger(nextSectorId) || nextSectorId < 0) return []
+            currentSectorId = nextSectorId
+        }
+        return []
+    }
+
+    /**
+     * Verifies regular, root, and mini-stream entries against source bytes.
+     * @param {Uint8Array} directoryBytes Decoded directory sectors.
+     * @param {number[]} fatEntries FAT entries.
+     * @param {number[]} miniFatEntries Mini-FAT entries.
+     * @param {number} miniStreamCutoff OLE mini-stream cutoff.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @param {number} miniSectorByteLength OLE mini-sector size.
+     * @param {number} partialSectorId Physically partial final sector id.
+     * @returns {boolean} Whether every declared stream is complete.
+     */
+    static #areStreamsComplete(
+        directoryBytes,
+        fatEntries,
+        miniFatEntries,
+        miniStreamCutoff,
+        sourceByteLength,
+        sectorByteLength,
+        miniSectorByteLength,
+        partialSectorId
+    ) {
+        const view = new DataView(
+            directoryBytes.buffer,
+            directoryBytes.byteOffset,
+            directoryBytes.byteLength
+        )
+        const entryCount =
+            directoryBytes.byteLength / DIRECTORY_ENTRY_BYTE_LENGTH
+        const entries = []
+        for (let index = 0; index < entryCount; index += 1) {
+            const offset = index * DIRECTORY_ENTRY_BYTE_LENGTH
+            const type = view.getUint8(offset + 66)
+            const streamSize = Number(view.getBigUint64(offset + 120, true))
+            if (!Number.isSafeInteger(streamSize)) return false
+            entries.push({
+                startSectorId: view.getInt32(offset + 116, true),
+                streamSize,
+                type
+            })
+        }
+
+        const rootEntry = entries.find((entry) => entry.type === 5)
+        const rootStreamByteLength = rootEntry?.streamSize ?? 0
+        let containsDeclaredPartialSector = false
+        for (const entry of entries) {
+            const { startSectorId, streamSize, type } = entry
+            const isRootStream = type === 5 && streamSize > 0
+            const isRegularStream = type === 2 && streamSize >= miniStreamCutoff
+            if (!isRootStream && !isRegularStream) continue
+            const sectorIds = AltiumOleInputTailNormalizer.#readSectorChain(
+                startSectorId,
+                fatEntries
+            )
+            if (
+                !AltiumOleInputTailNormalizer.#isStreamComplete(
+                    sectorIds,
+                    streamSize,
+                    sourceByteLength,
+                    sectorByteLength
+                )
+            ) {
+                return false
+            }
+            if (sectorIds.includes(partialSectorId)) {
+                containsDeclaredPartialSector = true
+            }
+        }
+
+        for (const entry of entries) {
+            const { startSectorId, streamSize, type } = entry
+            const isMiniStream =
+                type === 2 && streamSize > 0 && streamSize < miniStreamCutoff
+            if (!isMiniStream) continue
+            if (!rootEntry || !miniFatEntries.length) return false
+            const miniSectorIds = AltiumOleInputTailNormalizer.#readSectorChain(
+                startSectorId,
+                miniFatEntries
+            )
+            if (
+                !AltiumOleInputTailNormalizer.#isMiniStreamComplete(
+                    miniSectorIds,
+                    streamSize,
+                    rootStreamByteLength,
+                    miniSectorByteLength
+                )
+            ) {
+                return false
+            }
+        }
+        return containsDeclaredPartialSector
+    }
+
+    /**
+     * Checks one mini-stream chain against its declared root stream container.
+     * @param {number[]} miniSectorIds Ordered mini-sector ids.
+     * @param {number} streamByteLength Declared mini-stream length.
+     * @param {number} rootStreamByteLength Declared root stream length.
+     * @param {number} miniSectorByteLength OLE mini-sector size.
+     * @returns {boolean} Whether every mini-stream byte is contained.
+     */
+    static #isMiniStreamComplete(
+        miniSectorIds,
+        streamByteLength,
+        rootStreamByteLength,
+        miniSectorByteLength
+    ) {
+        const requiredSectorCount = Math.ceil(
+            streamByteLength / miniSectorByteLength
+        )
+        if (miniSectorIds.length !== requiredSectorCount) {
+            return false
+        }
+        for (let index = 0; index < miniSectorIds.length; index += 1) {
+            const miniSectorId = miniSectorIds[index]
+            const miniSectorOffset = miniSectorId * miniSectorByteLength
+            if (!Number.isSafeInteger(miniSectorOffset)) return false
+            const remaining = streamByteLength - index * miniSectorByteLength
+            const required = Math.min(
+                miniSectorByteLength,
+                Math.max(0, remaining)
+            )
+            if (!required) continue
+            const available = Math.max(
+                0,
+                Math.min(
+                    miniSectorByteLength,
+                    rootStreamByteLength - miniSectorOffset
+                )
+            )
+            if (available < required) return false
+        }
+        return true
+    }
+
+    /**
+     * Checks every declared byte of one regular stream chain.
+     * @param {number[]} sectorIds Stream sector ids.
+     * @param {number} streamByteLength Declared logical stream length.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {boolean} Whether the logical stream is physically complete.
+     */
+    static #isStreamComplete(
+        sectorIds,
+        streamByteLength,
+        sourceByteLength,
+        sectorByteLength
+    ) {
+        const requiredSectorCount = Math.ceil(
+            streamByteLength / sectorByteLength
+        )
+        if (sectorIds.length !== requiredSectorCount) return false
+        for (let index = 0; index < sectorIds.length; index += 1) {
+            const remaining = streamByteLength - index * sectorByteLength
+            const required = Math.min(sectorByteLength, Math.max(0, remaining))
+            if (!required) continue
+            const available =
+                AltiumOleInputTailNormalizer.#availableSectorByteLength(
+                    sectorIds[index],
+                    sourceByteLength,
+                    sectorByteLength
+                )
+            if (available < required) return false
+        }
+        return true
+    }
+
+    /**
+     * Returns whether every sector is fully present in the original source.
+     * @param {number[]} sectorIds Sector ids.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {boolean} Whether all sectors are complete.
+     */
+    static #hasFullSectors(sectorIds, sourceByteLength, sectorByteLength) {
+        return sectorIds.every((sectorId) =>
+            AltiumOleInputTailNormalizer.#hasFullSector(
+                sectorId,
+                sourceByteLength,
+                sectorByteLength
+            )
+        )
+    }
+
+    /**
+     * Returns whether one full sector is physically present.
+     * @param {number} sectorId Sector id.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {boolean} Whether the sector is complete.
+     */
+    static #hasFullSector(sectorId, sourceByteLength, sectorByteLength) {
+        return (
+            Number.isInteger(sectorId) &&
+            sectorId >= 0 &&
+            AltiumOleInputTailNormalizer.#availableSectorByteLength(
+                sectorId,
+                sourceByteLength,
+                sectorByteLength
+            ) === sectorByteLength
+        )
+    }
+
+    /**
+     * Resolves physical source bytes available for one sector.
+     * @param {number} sectorId Sector id.
+     * @param {number} sourceByteLength Original physical byte length.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {number} Available bytes from zero through one full sector.
+     */
+    static #availableSectorByteLength(
+        sectorId,
+        sourceByteLength,
+        sectorByteLength
+    ) {
+        const offset = HEADER_BYTE_LENGTH + sectorId * sectorByteLength
+        return Math.max(
+            0,
+            Math.min(sectorByteLength, sourceByteLength - offset)
+        )
+    }
+
+    /**
+     * Concatenates complete structural sectors from the aligned view.
+     * @param {DataView} view Aligned candidate view.
+     * @param {number[]} sectorIds Sector ids.
+     * @param {number} sectorByteLength OLE sector size.
+     * @returns {Uint8Array} Concatenated bytes.
+     */
+    static #readFullSectors(view, sectorIds, sectorByteLength) {
+        const bytes = new Uint8Array(sectorIds.length * sectorByteLength)
+        const source = new Uint8Array(view.buffer)
+        sectorIds.forEach((sectorId, index) => {
+            const offset = HEADER_BYTE_LENGTH + sectorId * sectorByteLength
+            bytes.set(
+                source.slice(offset, offset + sectorByteLength),
+                index * sectorByteLength
+            )
+        })
+        return bytes
+    }
+}
+
+Object.freeze(AltiumOleInputTailNormalizer.prototype)
+Object.freeze(AltiumOleInputTailNormalizer)

package/src/convergence/AltiumSchematicFidelityNormalizer.mjs

@@ -50,11 +50,18 @@ export class AltiumSchematicFidelityNormalizer {
             schematic.harnesses,
             records
         )
+        const symbolPrimitives =
+            AltiumSchematicFidelityNormalizer.#normalizeSymbolPrimitives(
+                schematic
+            )
 
         if (
             sheet === schematic.sheet &&
             texts === schematic.texts &&
-            harnesses === schematic.harnesses
+            harnesses === schematic.harnesses &&
+            symbolPrimitives.lines === schematic.lines &&
+            symbolPrimitives.rectangles === schematic.rectangles &&
+            symbolPrimitives.roundedRectangles === schematic.roundedRectangles
         ) {
             return documentModel
         }
@@ -63,6 +70,7 @@ export class AltiumSchematicFidelityNormalizer {
             ...documentModel,
             schematic: {
                 ...schematic,
+                ...symbolPrimitives,
                 sheet,
                 texts,
                 ...(harnesses ? { harnesses } : {})
@@ -70,6 +78,122 @@ export class AltiumSchematicFidelityNormalizer {
         }
     }
 
+    /**
+     * Themes geometry owned by pin-bearing symbol groups while retaining
+     * pinless decorative source-color strips.
+     * @param {Record<string, any>} schematic Native schematic model.
+     * @returns {{ lines: object[], rectangles: object[], roundedRectangles: object[] }} Normalized primitive collections.
+     */
+    static #normalizeSymbolPrimitives(schematic) {
+        const pinOwners = new Set(
+            (schematic.pins || [])
+                .map((pin) => String(pin?.ownerIndex || '').trim())
+                .filter(Boolean)
+        )
+
+        if (!pinOwners.size) {
+            return {
+                lines: schematic.lines || [],
+                rectangles: schematic.rectangles || [],
+                roundedRectangles: schematic.roundedRectangles || []
+            }
+        }
+
+        return {
+            lines: AltiumSchematicFidelityNormalizer.#mapChanged(
+                schematic.lines || [],
+                (line) =>
+                    pinOwners.has(String(line?.ownerIndex || '').trim())
+                        ? {
+                              ...line,
+                              color: 'var(--schematic-power-color)'
+                          }
+                        : line
+            ),
+            rectangles: AltiumSchematicFidelityNormalizer.#mapChanged(
+                schematic.rectangles || [],
+                (rectangle) =>
+                    AltiumSchematicFidelityNormalizer.#themeSymbolRectangle(
+                        rectangle,
+                        pinOwners
+                    )
+            ),
+            roundedRectangles: AltiumSchematicFidelityNormalizer.#mapChanged(
+                schematic.roundedRectangles || [],
+                (rectangle) =>
+                    AltiumSchematicFidelityNormalizer.#themeSymbolRectangle(
+                        rectangle,
+                        pinOwners
+                    )
+            )
+        }
+    }
+
+    /**
+     * Resolves one pin-bearing symbol rectangle to shared theme roles.
+     * @param {Record<string, any>} rectangle Rectangle primitive.
+     * @param {Set<string>} pinOwners Pin-bearing owner keys.
+     * @returns {Record<string, any>} Original or themed rectangle.
+     */
+    static #themeSymbolRectangle(rectangle, pinOwners) {
+        const owner = String(rectangle?.ownerIndex || '').trim()
+        if (!owner || !pinOwners.has(owner)) return rectangle
+
+        const isSolid = rectangle?.isSolid === true
+        const isContact =
+            isSolid &&
+            AltiumSchematicFidelityNormalizer.#isNarrowSymbolContact(rectangle)
+
+        return {
+            ...rectangle,
+            color: 'var(--schematic-power-color)',
+            ...(isSolid
+                ? {
+                      fill: isContact
+                          ? 'var(--schematic-power-color)'
+                          : 'var(--schematic-fill-color)',
+                      transparent: false
+                  }
+                : {})
+        }
+    }
+
+    /**
+     * Returns true when a solid symbol rectangle encodes a contact bar.
+     * @param {{ width?: number, height?: number }} rectangle Rectangle primitive.
+     * @returns {boolean} Whether the rectangle is a narrow contact.
+     */
+    static #isNarrowSymbolContact(rectangle) {
+        const width = Math.abs(Number(rectangle?.width || 0))
+        const height = Math.abs(Number(rectangle?.height || 0))
+        const shortSide = Math.min(width, height)
+        const longSide = Math.max(width, height)
+
+        return (
+            shortSide > 0 &&
+            shortSide <= 6 &&
+            longSide >= 12 &&
+            longSide >= shortSide * 2.5
+        )
+    }
+
+    /**
+     * Maps a collection while retaining its identity when no row changes.
+     * @param {object[]} values Source rows.
+     * @param {(value: object) => object} mapper Row mapper.
+     * @returns {object[]} Original or mapped collection.
+     */
+    static #mapChanged(values, mapper) {
+        let changed = false
+        const mapped = values.map((value) => {
+            const next = mapper(value)
+            changed ||= next !== value
+            return next
+        })
+
+        return changed ? mapped : values
+    }
+
     /**
      * Restores a proven embedded native frame from source sheet dimensions.
      * @param {Record<string, any>} schematic Native schematic model.

package/src/ui/SchematicHarnessRenderer.mjs

@@ -4,7 +4,6 @@
 
 import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
 import { SchematicTypography } from './SchematicTypography.mjs'
-import { SchematicColorResolver } from './SchematicColorResolver.mjs'
 
 const { createSvgText, escapeHtml, formatNumber, projectSchematicY } =
     SchematicSvgUtils
@@ -49,34 +48,101 @@ export class SchematicHarnessRenderer {
      * @returns {string}
      */
     static #buildSignalHarnessMarkup(signalHarness, sheetHeight) {
-        const points = (signalHarness.points || [])
-            .map(
-                (point) =>
-                    formatNumber(point.x) +
-                    ',' +
-                    formatNumber(projectSchematicY(sheetHeight, point.y))
+        const projectedPoints = (signalHarness.points || [])
+            .map((point) => ({
+                x: Number(point?.x),
+                y: projectSchematicY(sheetHeight, Number(point?.y))
+            }))
+            .filter(
+                (point) => Number.isFinite(point.x) && Number.isFinite(point.y)
             )
+        const points = projectedPoints
+            .map((point) => formatNumber(point.x) + ',' + formatNumber(point.y))
             .join(' ')
 
-        if (!points) return ''
+        if (projectedPoints.length < 2) return ''
+
+        const railWidth = Math.max(
+            (Number(signalHarness.lineWidth) || 1) * 4,
+            8
+        )
 
         return (
-            '<polyline class="schematic-signal-harness" points="' +
+            '<g class="schematic-signal-harness">' +
+            '<polyline class="schematic-signal-harness__outline" points="' +
             escapeHtml(points) +
-            '" fill="none" stroke="' +
-            escapeHtml(
-                SchematicColorResolver.resolveNonTextColor(
-                    signalHarness.color,
-                    '--schematic-default-ink-color',
-                    true
-                )
+            '" fill="none" stroke="var(--schematic-accent-ink-color)" stroke-opacity="0.28" stroke-width="' +
+            formatNumber(railWidth + 2) +
+            '" stroke-linecap="round" stroke-linejoin="round" />' +
+            '<polyline class="schematic-signal-harness__rail" points="' +
+            escapeHtml(points) +
+            '" fill="none" stroke="var(--schematic-pin-marker-fill)" stroke-width="' +
+            formatNumber(railWidth) +
+            '" stroke-linecap="round" stroke-linejoin="round" />' +
+            SchematicHarnessRenderer.#buildSignalHarnessMarks(
+                projectedPoints,
+                railWidth
             ) +
-            '" stroke-width="' +
-            formatNumber(Math.max(Number(signalHarness.lineWidth) || 1, 1)) +
-            '" stroke-linecap="round" stroke-linejoin="round" />'
+            '</g>'
         )
     }
 
+    /**
+     * Builds repeated diagonal marks along every projected harness segment.
+     * @param {{ x: number, y: number }[]} points Projected harness points.
+     * @param {number} railWidth Rendered harness width.
+     * @returns {string}
+     */
+    static #buildSignalHarnessMarks(points, railWidth) {
+        const marks = []
+        const spacing = Math.max(railWidth * 1.45, 10)
+
+        for (let index = 1; index < points.length; index += 1) {
+            const start = points[index - 1]
+            const end = points[index]
+            const deltaX = end.x - start.x
+            const deltaY = end.y - start.y
+            const length = Math.hypot(deltaX, deltaY)
+
+            if (!Number.isFinite(length) || length <= 0.001) continue
+
+            const tangentX = deltaX / length
+            const tangentY = deltaY / length
+            const normalX = -tangentY
+            const normalY = tangentX
+            const halfAlong = railWidth * 0.32
+            const halfNormal = railWidth * 0.42
+            const markCount = Math.min(
+                Math.max(Math.floor(length / spacing), 1),
+                4096
+            )
+
+            for (let markIndex = 0; markIndex < markCount; markIndex += 1) {
+                const distance = ((markIndex + 0.5) * length) / markCount
+                const centerX = start.x + tangentX * distance
+                const centerY = start.y + tangentY * distance
+                const x1 = centerX - tangentX * halfAlong - normalX * halfNormal
+                const y1 = centerY - tangentY * halfAlong - normalY * halfNormal
+                const x2 = centerX + tangentX * halfAlong + normalX * halfNormal
+                const y2 = centerY + tangentY * halfAlong + normalY * halfNormal
+
+                marks.push(
+                    '<line class="schematic-signal-harness__mark" x1="' +
+                        formatNumber(x1) +
+                        '" y1="' +
+                        formatNumber(y1) +
+                        '" x2="' +
+                        formatNumber(x2) +
+                        '" y2="' +
+                        formatNumber(y2) +
+                        '" stroke="var(--schematic-accent-ink-color)" stroke-opacity="0.32" stroke-width="1.4" stroke-linecap="round" />'
+                )
+            }
+        }
+
+        return marks.join('')
+    }
+
     /**
      * 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
@@ -85,25 +151,19 @@ export class SchematicHarnessRenderer {
      * @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 geometry = SchematicHarnessRenderer.#connectorGeometry(
+            connector,
+            sheetHeight
+        )
         const entryMarkup = (connector.entries || [])
             .map((entry) =>
                 SchematicHarnessRenderer.#buildEntryMarkup(
                     connector,
                     entry,
                     sheetHeight,
-                    textOptions,
-                    stroke
+                    textOptions
                 )
             )
             .join('')
@@ -117,20 +177,14 @@ export class SchematicHarnessRenderer {
 
         return (
             '<g class="schematic-harness-connector">' +
-            '<polygon points="' +
-            escapeHtml(
-                SchematicHarnessRenderer.#connectorPoints(
-                    connector,
-                    sheetHeight
-                )
-            ) +
-            '" fill="' +
-            escapeHtml(fill) +
-            '" stroke="' +
-            escapeHtml(stroke) +
-            '" stroke-width="' +
+            '<path class="schematic-harness-connector__body" d="' +
+            escapeHtml(geometry.bodyPath) +
+            '" fill="var(--schematic-pin-marker-fill)" stroke="none" />' +
+            '<path class="schematic-harness-connector__bracket" d="' +
+            escapeHtml(geometry.bracketPath) +
+            '" fill="none" stroke="var(--schematic-accent-ink-color)" stroke-opacity="0.46" stroke-width="' +
             formatNumber(Math.max(Number(connector.lineWidth) || 1, 1)) +
-            '" stroke-linejoin="round" />' +
+            '" stroke-linecap="round" />' +
             entryMarkup +
             typeMarkup +
             '</g>'
@@ -138,68 +192,204 @@ export class SchematicHarnessRenderer {
     }
 
     /**
-     * Builds the concave connector outline from its primary connection side.
+     * Builds the filled connector region and open primary-side bracket.
      * @param {{ x: number, y: number, width: number, height: number, side?: 'left' | 'right' | 'top' | 'bottom', primaryConnectionPosition?: number }} connector
      * @param {number} sheetHeight
-     * @returns {string}
+     * @returns {{ bodyPath: string, bracketPath: string }}
      */
-    static #connectorPoints(connector, sheetHeight) {
+    static #connectorGeometry(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 top = projectSchematicY(sheetHeight, Number(connector.y) || 0)
+        const bottom = top + height
+        const left = x
+        const right = x + width
+        const side = connector.side || 'left'
+        const primaryExtent =
+            side === 'top' || side === 'bottom' ? width : height
         const primary = Math.min(
             Math.max(Number(connector.primaryConnectionPosition) || 0, 0),
-            connector.side === 'top' || connector.side === 'bottom'
-                ? width
-                : height
+            primaryExtent
         )
-        const side = connector.side || 'left'
-        let points
+        const primaryX = left + primary
+        const primaryY = top + primary
+        const xCurve = inset * 0.7
+        const yUpperCurve = Math.max((primaryY - top) * 0.45, 1)
+        const yLowerCurve = Math.max((bottom - primaryY) * 0.45, 1)
+        const xLeftCurve = Math.max((primaryX - left) * 0.45, 1)
+        const xRightCurve = Math.max((right - primaryX) * 0.45, 1)
 
         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 }
-            ]
+            const inner = right - inset
+            const forward =
+                'M ' +
+                formatNumber(inner) +
+                ' ' +
+                formatNumber(top) +
+                ' C ' +
+                formatNumber(inner + xCurve) +
+                ' ' +
+                formatNumber(top) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(primaryY - yUpperCurve) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(primaryY) +
+                ' C ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(primaryY + yLowerCurve) +
+                ' ' +
+                formatNumber(inner + xCurve) +
+                ' ' +
+                formatNumber(bottom) +
+                ' ' +
+                formatNumber(inner) +
+                ' ' +
+                formatNumber(bottom)
+            return {
+                bracketPath: forward,
+                bodyPath:
+                    forward +
+                    ' H ' +
+                    formatNumber(left) +
+                    ' V ' +
+                    formatNumber(top) +
+                    ' Z'
+            }
         }
 
-        return points
-            .map(
-                (point) =>
-                    formatNumber(point.x) +
-                    ',' +
-                    formatNumber(projectSchematicY(sheetHeight, point.y))
-            )
-            .join(' ')
+        if (side === 'top') {
+            const inner = top + inset
+            const forward =
+                'M ' +
+                formatNumber(left) +
+                ' ' +
+                formatNumber(inner) +
+                ' C ' +
+                formatNumber(left) +
+                ' ' +
+                formatNumber(inner - xCurve) +
+                ' ' +
+                formatNumber(primaryX - xLeftCurve) +
+                ' ' +
+                formatNumber(top) +
+                ' ' +
+                formatNumber(primaryX) +
+                ' ' +
+                formatNumber(top) +
+                ' C ' +
+                formatNumber(primaryX + xRightCurve) +
+                ' ' +
+                formatNumber(top) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(inner - xCurve) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(inner)
+            return {
+                bracketPath: forward,
+                bodyPath:
+                    forward +
+                    ' V ' +
+                    formatNumber(bottom) +
+                    ' H ' +
+                    formatNumber(left) +
+                    ' Z'
+            }
+        }
+
+        if (side === 'bottom') {
+            const inner = bottom - inset
+            const forward =
+                'M ' +
+                formatNumber(left) +
+                ' ' +
+                formatNumber(inner) +
+                ' C ' +
+                formatNumber(left) +
+                ' ' +
+                formatNumber(inner + xCurve) +
+                ' ' +
+                formatNumber(primaryX - xLeftCurve) +
+                ' ' +
+                formatNumber(bottom) +
+                ' ' +
+                formatNumber(primaryX) +
+                ' ' +
+                formatNumber(bottom) +
+                ' C ' +
+                formatNumber(primaryX + xRightCurve) +
+                ' ' +
+                formatNumber(bottom) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(inner + xCurve) +
+                ' ' +
+                formatNumber(right) +
+                ' ' +
+                formatNumber(inner)
+            return {
+                bracketPath: forward,
+                bodyPath:
+                    forward +
+                    ' V ' +
+                    formatNumber(top) +
+                    ' H ' +
+                    formatNumber(left) +
+                    ' Z'
+            }
+        }
+
+        const inner = left + inset
+        const forward =
+            'M ' +
+            formatNumber(inner) +
+            ' ' +
+            formatNumber(top) +
+            ' C ' +
+            formatNumber(inner - xCurve) +
+            ' ' +
+            formatNumber(top) +
+            ' ' +
+            formatNumber(left) +
+            ' ' +
+            formatNumber(primaryY - yUpperCurve) +
+            ' ' +
+            formatNumber(left) +
+            ' ' +
+            formatNumber(primaryY) +
+            ' C ' +
+            formatNumber(left) +
+            ' ' +
+            formatNumber(primaryY + yLowerCurve) +
+            ' ' +
+            formatNumber(inner - xCurve) +
+            ' ' +
+            formatNumber(bottom) +
+            ' ' +
+            formatNumber(inner) +
+            ' ' +
+            formatNumber(bottom)
+        return {
+            bracketPath: forward,
+            bodyPath:
+                forward +
+                ' H ' +
+                formatNumber(right) +
+                ' V ' +
+                formatNumber(top) +
+                ' Z'
+        }
     }
 
     /**
@@ -208,45 +398,27 @@ export class SchematicHarnessRenderer {
      * @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
-    ) {
+    static #buildEntryMarkup(connector, entry, sheetHeight, textOptions) {
         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) +
-            '" />' +
+            '<g class="schematic-harness-entry"><circle class="schematic-harness-entry-dot" cx="' +
+            formatNumber(placement.dotX) +
+            '" cy="' +
+            formatNumber(placement.dotY) +
+            '" r="1.5" fill="var(--schematic-default-ink-color)" />' +
             createSvgText(
                 'schematic-harness-entry-label',
                 placement.labelX,
                 placement.labelY,
                 entry.name || '',
-                labelColor,
+                'var(--schematic-default-ink-color)',
                 placement.anchor,
                 textOptions
             ) +
@@ -259,7 +431,7 @@ export class SchematicHarnessRenderer {
      * @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' }}
+     * @returns {{ dotX: number, dotY: number, labelX: number, labelY: number, anchor: 'start' | 'middle' | 'end' }}
      */
     static #entryPlacement(connector, entry, sheetHeight) {
         const x = Number(connector.x) || 0
@@ -273,25 +445,21 @@ export class SchematicHarnessRenderer {
         if (side === 'left') {
             const entryY = projectSchematicY(sheetHeight, y - distance)
             return {
-                x1: x,
-                y1: entryY,
-                x2: x - 10,
-                y2: entryY,
-                labelX: x - 14,
+                dotX: x,
+                dotY: entryY,
+                labelX: x + 8,
                 labelY: entryY + baselineLift,
-                anchor: 'end'
+                anchor: 'start'
             }
         }
         if (side === 'top') {
             const entryX = x + distance
             const entryY = projectSchematicY(sheetHeight, y)
             return {
-                x1: entryX,
-                y1: entryY,
-                x2: entryX,
-                y2: entryY - 10,
+                dotX: entryX,
+                dotY: entryY,
                 labelX: entryX,
-                labelY: entryY - 13,
+                labelY: entryY + 12,
                 anchor: 'middle'
             }
         }
@@ -299,25 +467,21 @@ export class SchematicHarnessRenderer {
             const entryX = x + distance
             const entryY = projectSchematicY(sheetHeight, y - height)
             return {
-                x1: entryX,
-                y1: entryY,
-                x2: entryX,
-                y2: entryY + 10,
+                dotX: entryX,
+                dotY: entryY,
                 labelX: entryX,
-                labelY: entryY + 19,
+                labelY: entryY - 5,
                 anchor: 'middle'
             }
         }
 
         const entryY = projectSchematicY(sheetHeight, y - distance)
         return {
-            x1: x + width,
-            y1: entryY,
-            x2: x + width + 10,
-            y2: entryY,
-            labelX: x + width + 14,
+            dotX: x + width,
+            dotY: entryY,
+            labelX: x + width - 8,
             labelY: entryY + baselineLift,
-            anchor: 'start'
+            anchor: 'end'
         }
     }
 
@@ -334,11 +498,7 @@ export class SchematicHarnessRenderer {
             typeLabel.x,
             projectSchematicY(sheetHeight, typeLabel.y),
             typeLabel.text || '',
-            SchematicColorResolver.resolveColor(
-                typeLabel.color,
-                '--schematic-default-ink-color',
-                true
-            ),
+            'var(--schematic-default-ink-color)',
             'start',
             textOptions
         )