altium-toolkit 1.2.1 → 1.4.0

package/README.md

@@ -32,6 +32,19 @@ Version 1.2.1 keeps Three.js as an example-only development dependency. The
 published parser and CircuitJSON services do not install a second, unused
 Three.js runtime into host applications.
 
+Version 1.3.0 updates the common runtime baseline to CircuitJSON Toolkit 1.2
+and adapts effectively invisible historical 32-bit BMP previews at the common
+convergence boundary. The public parser and renderer now show the existing
+missing-image placeholder for those unusable payloads without changing the
+frozen native parser or healthy embedded images. See the
+[1.3.0 release notes](docs/release-notes-v1.3.0.md).
+
+Version 1.4.0 adopts newly decoded CircuitJSON and native extension graphs at
+the shared validation boundary. Their ordinary nodes retain identity and are
+deeply frozen without a redundant defensive graph copy. Parser parameters,
+document envelopes, extension fields, and return shapes remain unchanged. See
+the [1.4.0 release notes](docs/release-notes-v1.4.0.md).
+
 Default `extensions: 'canonical'` keeps compact Altium summary metadata.
 Request the complete native read model with `extensions: 'full'`,
 `preserveRaw: true`, or `extensions: ['altium.native-model']`. Project batches
@@ -199,6 +212,8 @@ const legacyCircuitJson = AltiumParser.parseArrayBuffer(file.name, arrayBuffer)
 - [API](docs/api.md)
 - [Capabilities](docs/capabilities.md)
 - [Migration from 1.1.41](docs/migration.md)
+- [1.4.0 release notes](docs/release-notes-v1.4.0.md)
+- [1.3.0 release notes](docs/release-notes-v1.3.0.md)
 - [1.2.1 release notes](docs/release-notes-v1.2.1.md)
 - [1.2.0 release notes](docs/release-notes-v1.2.0.md)
 - [Model Format](docs/model-format.md)

package/docs/api.md

@@ -111,6 +111,13 @@ metadata. The complete recovered native read model remains available through
 `document.model` and do not require the full native extension.
 `extensions: 'none'` or `extensions: []` returns exactly `extensions: {}`.
 
+The convergence builder transfers its newly decoded ordinary CircuitJSON and
+native extension graphs into the shared owned-document validator. Eligible
+graph nodes retain identity and are deeply frozen in place, avoiding a second
+full defensive copy. This is an internal ownership optimization after source
+decoding: raw caller data remains untrusted, and every public parser parameter,
+validation rule, document field, and return shape is unchanged.
+
 Canonical `.SchDoc` models preserve native drawing order, ownership, geometry,
 and style as shared `schematic_rect`, `schematic_circle`, `schematic_arc`,
 `schematic_path`, `schematic_text`, `schematic_table`, and

package/docs/model-format.md

@@ -60,6 +60,16 @@ the object form can call
 `AltiumParser.parseArrayBufferToRendererModel(fileName, arrayBuffer)` or
 `CircuitJsonModelAdapter.toRendererModel(circuitJson)`.
 
+The common parser and schematic renderer expose a convergence-only view of
+historical embedded image rows. A parser-generated RGBA PNG recovered from a
+32-bit BMP is marked `diagnosticState: 'unusable-embedded-payload'` only when
+its decoded alpha coverage is strictly below one percent. Its placement,
+source MIME type, file name, and aspect metadata remain intact while drawable
+payload fields are cleared so the established missing-image placeholder is
+rendered. Native PNG, JPEG, GIF, SVG, and WebP payloads, malformed or unknown
+PNG encodings, and images at or above the threshold are not rewritten. The
+retained historical parser model itself remains unchanged.
+
 ## Common Fields
 
 - `schema`: normalized model schema id, currently

package/docs/plans/2026-07-13-missing-image-placeholder-implementation.md

@@ -0,0 +1,312 @@
+# Missing Schematic Image Placeholder Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Render the exact Altium missing-file message when a recovered 32-bit BMP preview is effectively invisible.
+
+**Architecture:** `SchematicImageParser` remains responsible for deciding whether recovered binary image data is drawable. It will measure 32-bit BMP alpha coverage and expose an unusable payload through the existing normalized image contract, allowing `SchematicImageRenderer` to reuse its established placeholder markup without binary inspection.
+
+**Tech Stack:** JavaScript ES modules, Node.js test runner through `npm test`, OLE schematic test factory, SVG string renderer.
+
+## Global Constraints
+
+- Classify only from image payload structure and visibility; never match file names, paths, projects, or source-derived phrases.
+- Alpha coverage below 1 percent is effectively invisible.
+- Wrapped native PNG, JPEG, GIF, SVG, and WebP payloads remain unchanged.
+- Preserve image placement, source path, embed flag, aspect ratio, and render order for unusable payloads.
+- Use only generated, obfuscated schematic data in tests.
+- Do not add a provided native `.SchDoc` file to the test suite.
+
+---
+
+### Task 1: Add the failing parser-to-renderer regression
+
+**Files:**
+
+- Modify: `tests/core/altium-parser/schematic-images.mjs`
+
+**Interfaces:**
+
+- Consumes: `AltiumParser.parseArrayBufferToRendererModel(fileName, arrayBuffer)` and `SchematicSvgRenderer.render(documentModel)`.
+- Produces: `createSparseAlphaBmpBytes()` and height support in `createBmpBytes(options)` for generated test payloads.
+
+- [ ] **Step 1: Import the schematic renderer**
+
+```js
+import { SchematicSvgRenderer } from '../../../src/ui/SchematicSvgRenderer.mjs'
+```
+
+- [ ] **Step 2: Add a generated sparse-alpha regression**
+
+```js
+test('parseAltiumArrayBuffer renders effectively invisible BMP previews as missing-image placeholders', () => {
+    const imageFileName = 'C:\\Forge\\Obfuscated\\Artwork\\ghost-badge.bmp'
+    const fileHeaderText =
+        '|HEADER=Schematic Document' +
+        '|RECORD=31|CustomX=160|CustomY=120|VisibleGridSize=10|SnapGridSize=5' +
+        '|BorderOn=F|TitleBlockOn=F|CustomMarginWidth=10|CustomXZones=6|CustomYZones=4' +
+        '|FontIdCount=1|Size1=10|FontName1=Times New Roman|Bold1=F|Rotation1=0' +
+        '|RECORD=30|IndexInSheet=2|Location.X=20|Location.Y=30|Corner.X=80|Corner.Y=70' +
+        '|EmbedImage=T|KeepAspect=T|FileName=' +
+        imageFileName
+    const arrayBuffer = SchematicImageOleFactory.createDocumentBuffer({
+        fileHeaderText,
+        imageFileName,
+        imageBytes: createSparseAlphaBmpBytes()
+    })
+    const documentModel = AltiumParser.parseArrayBufferToRendererModel(
+        'ghost-image.SchDoc',
+        arrayBuffer
+    )
+    const image = documentModel.schematic.images[0]
+    const markup = SchematicSvgRenderer.render(documentModel)
+
+    assert.equal(image.diagnosticState, 'unusable-embedded-payload')
+    assert.equal(image.mimeType, '')
+    assert.equal(image.dataBase64, '')
+    assert.match(
+        documentModel.diagnostics
+            .map((diagnostic) => diagnostic.message)
+            .join('\n'),
+        /effectively invisible/i
+    )
+    assert.match(markup, /Cannot open file/)
+    assert.match(markup, /C:\\Forge\\Obfuscated/)
+    assert.match(markup, /ghost-badge\.bmp/)
+    assert.match(markup, /\. File does not exist\./)
+    assert.doesNotMatch(markup, /class="schematic-embedded-image/)
+})
+```
+
+- [ ] **Step 3: Extend the BMP factory without adding fixture files**
+
+```js
+function createSparseAlphaBmpBytes() {
+    const width = 20
+    const height = 20
+    const pixels = new Array(width * height * 4).fill(0)
+    pixels.splice(0, 4, 0xff, 0xff, 0xff, 0xff)
+
+    return createBmpBytes({ bitsPerPixel: 32, width, height, pixels })
+}
+```
+
+Change the factory contract and height initialization to:
+
+```js
+/**
+ * @param {{ bitsPerPixel: 24 | 32, width?: number, height?: number, pixels: number[] }} options
+ */
+function createBmpBytes(options) {
+    const width = options.width || 1
+    const height = options.height || 1
+```
+
+- [ ] **Step 4: Run the focused regression and verify RED**
+
+Run:
+
+```bash
+npm test -- --test-name-pattern="effectively invisible BMP previews"
+```
+
+Expected: FAIL because the image currently has diagnostic state `embedded` and non-empty PNG data.
+
+---
+
+### Task 2: Classify effectively invisible previews in the parser
+
+**Files:**
+
+- Modify: `src/core/altium/SchematicImageParser.mjs`
+- Test: `tests/core/altium-parser/schematic-images.mjs`
+
+**Interfaces:**
+
+- Consumes: parsed BMP metadata `{ width, height, bitsPerPixel, pixelOffset, rowStride }`.
+- Produces: decoded payload field `effectivelyInvisible: boolean`, normalized diagnostic state `unusable-embedded-payload`, and a recoverable warning.
+
+- [ ] **Step 1: Add the structural coverage threshold**
+
+```js
+const MINIMUM_VISIBLE_ALPHA_COVERAGE = 0.01
+```
+
+- [ ] **Step 2: Return invisibility metadata from payload decoding**
+
+Update `#decodeEmbeddedImagePayload` so native payloads return
+`effectivelyInvisible: false`. For BMP previews, calculate coverage before PNG
+encoding:
+
+```js
+const alphaCoverage = SchematicImageParser.#bmpAlphaCoverage(bytes, bmpInfo)
+
+if (alphaCoverage !== null && alphaCoverage < MINIMUM_VISIBLE_ALPHA_COVERAGE) {
+    return {
+        bytes: new Uint8Array(),
+        mimeType: '',
+        sourceMimeType: sourceMimeType || 'image/bmp',
+        nativeClass: '',
+        hasAlpha: true,
+        effectivelyInvisible: true
+    }
+}
+
+if (alphaCoverage !== null && alphaCoverage < 1) {
+    const rgba = SchematicImageParser.#decodeBmpRgba(bytes, bmpInfo)
+    return {
+        bytes: SchematicImageParser.#encodePngRgba(
+            bmpInfo.width,
+            bmpInfo.height,
+            rgba
+        ),
+        mimeType: PNG_SCHEMA_MIME_TYPE,
+        sourceMimeType: sourceMimeType || 'image/bmp',
+        nativeClass: '',
+        hasAlpha: true,
+        effectivelyInvisible: false
+    }
+}
+```
+
+The unchanged raw-payload return also includes
+`effectivelyInvisible: false`.
+
+- [ ] **Step 3: Replace the boolean alpha scan with coverage measurement**
+
+```js
+static #bmpAlphaCoverage(bytes, bmpInfo) {
+    if (bmpInfo?.bitsPerPixel !== 32) return null
+
+    let alphaTotal = 0
+    for (let y = 0; y < bmpInfo.height; y += 1) {
+        const rowOffset = bmpInfo.pixelOffset + y * bmpInfo.rowStride
+        for (let x = 0; x < bmpInfo.width; x += 1) {
+            alphaTotal += bytes[rowOffset + x * 4 + 3]
+        }
+    }
+
+    return alphaTotal / (bmpInfo.width * bmpInfo.height * 255)
+}
+```
+
+Add complete JSDoc describing the nullable coverage result.
+
+- [ ] **Step 4: Normalize the unusable payload without dropping placement**
+
+In `#parseSchematicImageRecord`, branch on
+`decoded.effectivelyInvisible` before assigning drawable data:
+
+```js
+sourceMimeType = decoded.sourceMimeType
+nativeClass = decoded.nativeClass
+hasAlpha = decoded.hasAlpha
+
+if (decoded.effectivelyInvisible) {
+    diagnosticState = 'unusable-embedded-payload'
+    diagnostics.push({
+        severity: 'warning',
+        message:
+            'Embedded schematic image payload is effectively invisible for ' +
+            fileName +
+            '.'
+    })
+} else {
+    mimeType = decoded.mimeType
+    dataBase64 = SchematicImageParser.#encodeBase64(decoded.bytes)
+    diagnosticState = 'embedded'
+}
+```
+
+- [ ] **Step 5: Run the focused regression and verify GREEN**
+
+Run:
+
+```bash
+npm test -- --test-name-pattern="effectively invisible BMP previews"
+```
+
+Expected: PASS, including exact placeholder-message assertions.
+
+- [ ] **Step 6: Run the complete library verification**
+
+Run:
+
+```bash
+npm test
+npm run check:format
+```
+
+Expected: all tests pass and Prettier reports all matched files use its formatting.
+
+- [ ] **Step 7: Commit the parser fix and regression**
+
+```bash
+git add src/core/altium/SchematicImageParser.mjs tests/core/altium-parser/schematic-images.mjs
+git commit -m "fix: render unusable schematic images as placeholders"
+```
+
+---
+
+### Task 3: Verify the ECAD Forge integration
+
+**Files:**
+
+- Verify only: `/Users/afiedler/Documents/privat/Andrés_Werkstatt/ecadforge_app`
+
+**Interfaces:**
+
+- Consumes: local `altium-toolkit` package source and the ECAD Forge Altium demo URL.
+- Produces: library/app test evidence plus live DOM and screenshot evidence.
+
+- [ ] **Step 1: Install the local library into the app without changing manifests**
+
+Run from the ECAD Forge repository:
+
+```bash
+npm install --no-save --package-lock=false ../altium-toolkit
+```
+
+Expected: `package.json` and `package-lock.json` remain unchanged.
+
+- [ ] **Step 2: Run the app-owned tests**
+
+```bash
+npm test
+```
+
+Expected: all ECAD Forge tests pass.
+
+- [ ] **Step 3: Reopen the local demo and inspect observable markup**
+
+Open:
+
+```text
+http://localhost:3000/?demo=altium&view=schematic&document=NODEMCU_ESP12.SchDoc
+```
+
+Expected DOM evidence:
+
+```text
+.schematic-image-placeholder count: 1
+.schematic-image-placeholder-message text includes:
+Cannot open file
+C:\Forge\Obfuscated\Artwork\ghost-badge.bmp
+. File does not exist.
+.schematic-embedded-image count: 0
+```
+
+- [ ] **Step 4: Capture and inspect a screenshot**
+
+Expected: the missing-file message is visible in the authored title-block image
+bounds and the surrounding schematic/title-block geometry remains unchanged.
+
+- [ ] **Step 5: Confirm both worktrees contain only intended tracked changes**
+
+```bash
+git status --short
+git -C ../altium-toolkit status --short
+```
+
+Expected: ECAD Forge has no tracked changes; Altium Toolkit is clean after its
+implementation commit.

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

@@ -0,0 +1,30 @@
+# altium-toolkit 1.3.0
+
+Version 1.3.0 consumes the CircuitJSON Toolkit 1.2 shared contract and restores
+the established schematic placeholder for unusable embedded image previews.
+
+## Schematic image behavior
+
+- The common `Parser` and `SchematicSvgRenderer` adapt the exact historical
+  BMP-to-PNG representation when its decoded alpha coverage is strictly below
+  one percent. Those rows use `unusable-embedded-payload`, preserve placement
+  and source metadata, and render the existing missing-image placeholder.
+- The adapter is owned by the convergence layer. The frozen 1.1.41 native
+  parser and its extension API remain byte-identical and continue to expose the
+  original recovered payload.
+- Native wrapped PNG, JPEG, GIF, SVG, and WebP assets are unchanged. Malformed,
+  unknown, differently encoded, and exactly one-percent-visible PNG data is
+  also left untouched. Historical stored-zlib payloads must pass both the PNG
+  chunk CRC and the zlib Adler-32 checksum before adaptation.
+- Only affected image rows and their containing model branches are cloned.
+  Alpha coverage is cached by immutable image identity, and warnings are
+  deduplicated.
+
+## Shared runtime
+
+- `circuitjson-toolkit` now uses the `^1.2.0` runtime baseline, aligning Altium
+  documents with the validated PCB text, drilled-pad geometry, and metadata
+  consumed by the other source toolkits and the 3D viewer.
+- Existing root exports, package subpaths, parser parameters, document/project
+  envelopes, native extension APIs, and healthy image return shapes remain
+  available. The unusable-image state is an additive common-view behavior.

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

@@ -0,0 +1,37 @@
+# altium-toolkit 1.4.0
+
+Version 1.4.0 adopts parser-owned CircuitJSON and retained native extension
+graphs through the CircuitJSON Toolkit 1.4 ownership boundary. It removes a
+redundant defensive graph copy from successful document construction without
+weakening validation or immutability.
+
+## Owned convergence graphs
+
+- The Altium convergence builder uses
+  `DocumentResult.createValidatedOwned(fields, runtime?)` for graphs it has
+  just constructed and exclusively owns.
+- Ordinary CircuitJSON model and native extension nodes retain their identities
+  and are deeply frozen in place. Binary properties continue through the
+  shared defensive binary boundary.
+- Raw input remains untrusted and is decoded and validated normally. The owned
+  path is applied only after the format parser has produced a new standard
+  local graph.
+
+## API and compatibility
+
+- Parser input, options, progress, cancellation, worker, and project contracts
+  are unchanged.
+- Successful parsing returns the same `ecad-toolkit.document.v1` envelope with
+  the same `model`, `source`, `extensions`, `assets`, `diagnostics`, and
+  `statistics` fields.
+- Canonical, metadata, full native-model, and empty extension selections retain
+  their existing behavior and return shapes.
+- No class, method, parameter, package subpath, native extension, or renderer
+  behavior is removed or renamed.
+
+## Performance verification
+
+The shared ownership regressions verify retained identity, deep freeze,
+bounded extension sealing, mutation isolation, binary protection, and direct
+and worker result parity. The Altium parser and packed cross-toolkit suites
+continue to validate the public envelope and renderer contracts.

package/docs/testing.md

@@ -27,10 +27,13 @@ npm run check:format
 npm pack --dry-run
 ```
 
-The strict feature check creates an isolated packed install, installs the
-approved CircuitJSON 1.1.0 release candidate, verifies all historical native
-source and extension contracts, checks the exact package/subpath layout, and
-runs the shared observable toolkit contract against the packed package.
+The strict feature check creates an isolated packed install and packs the
+currently installed CircuitJSON dependency beside the Altium candidate. This
+keeps the isolated contract gate aligned with the dependency declared by the
+active release instead of a stale version-specific fixture. It verifies all
+historical native source and extension contracts, checks the exact
+package/subpath layout, and runs the shared observable toolkit contract against
+the packed package.
 
 The performance check is bound to the immutable 1.1.41 commit, source tree,
 and native-source manifest. It measures legacy and canonical projections of

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.2.1",
+    "version": "1.4.0",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",
@@ -67,7 +67,7 @@
         "check:features": "node scripts/check-feature-preservation.mjs"
     },
     "dependencies": {
-        "circuitjson-toolkit": "^1.1.0",
+        "circuitjson-toolkit": "^1.4.0",
         "fflate": "^0.8.2"
     },
     "devDependencies": {

package/spec/2026-07-13-missing-image-placeholder-design.md

@@ -0,0 +1,82 @@
+# Missing Schematic Image Placeholder Design
+
+## Problem
+
+An embedded schematic image record can resolve to a 32-bit BMP preview whose
+alpha channel makes nearly the entire payload invisible. The parser currently
+treats any mixture of transparent and visible pixels as meaningful alpha,
+converts the preview to PNG, and classifies it as an embedded image. The SVG
+renderer then emits an image node that appears blank instead of the missing-file
+message used for an unavailable image.
+
+## Scope
+
+The fix belongs in `altium-toolkit`, which owns Altium image parsing and
+schematic SVG rendering. It must apply to all recovered 32-bit BMP previews
+without matching source file names, paths, projects, or message content.
+
+Native wrapped PNG, JPEG, GIF, SVG, and WebP payloads remain unchanged. Healthy
+BMP previews with meaningful visible alpha coverage also remain embedded.
+
+## Design
+
+`SchematicImageParser` will measure the alpha coverage of an uncompressed
+32-bit BMP preview before converting it to PNG. Alpha coverage is the sum of
+the pixel alpha values divided by the maximum possible alpha sum for the image.
+
+A preview with alpha coverage below 1 percent is effectively invisible and is
+not a drawable embedded payload. The normalized image retains its placement,
+source file name, embed flag, aspect-ratio flag, and render order, but exposes
+empty `mimeType` and `dataBase64` values with diagnostic state
+`unusable-embedded-payload`. Parsing also emits a warning that the embedded
+payload is effectively invisible.
+
+The existing `SchematicImageRenderer` already renders images without usable
+payload data as placeholders. It will therefore produce the existing exact
+Altium-style message:
+
+1. `Cannot open file`
+2. The source path wrapped to the placeholder width
+3. `. File does not exist.`
+
+No renderer-specific binary inspection or source-specific phrase matching will
+be added.
+
+## Data Flow
+
+1. Resolve the embedded image bytes from an OLE stream or packed storage.
+2. Prefer a valid wrapped native image payload when present.
+3. For an uncompressed 32-bit BMP preview, calculate alpha coverage.
+4. Classify coverage below 1 percent as unusable; otherwise keep the current
+   BMP-to-PNG behavior.
+5. Render unusable payloads through the existing missing-image placeholder.
+
+## Error Handling
+
+An effectively invisible preview is a recoverable parse condition. The parser
+keeps the image record and adds a warning rather than throwing or dropping the
+placement. Missing payloads continue to use their current diagnostic state.
+
+## Testing
+
+Tests will use only generated, obfuscated schematic data:
+
+- A synthetic OLE schematic with a 32-bit BMP preview below 1 percent alpha
+  coverage must normalize to `unusable-embedded-payload` with empty payload
+  data and a warning.
+- Rendering that normalized image must contain the exact three-part message and
+  wrapped source path, with no embedded image node.
+- A synthetic 32-bit BMP with alpha coverage at or above 1 percent must remain
+  a PNG embedded image.
+- Existing `altium-toolkit` tests and the ECAD Forge application tests must
+  remain green.
+- The local ECAD Forge demo must show the placeholder message in the authored
+  image bounds.
+
+## Acceptance Criteria
+
+- Effectively invisible recovered BMP previews display the exact Altium-style
+  missing-file message.
+- Valid embedded images continue to render.
+- The behavior is derived only from payload structure and visibility.
+- No provided native schematic is added to the test suite.

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 { AltiumSchematicImageNormalizer } from './AltiumSchematicImageNormalizer.mjs'
 import { ParserInput } from './ParserInput.mjs'
 
 /**
@@ -20,9 +21,11 @@ export class AltiumDocumentBuilder {
      */
     static decode(normalized) {
         const buffer = ParserInput.arrayBuffer(normalized.input.data)
-        const native = AltiumParser.parseArrayBufferToRendererModel(
-            normalized.input.fileName,
-            buffer
+        const native = AltiumSchematicImageNormalizer.normalize(
+            AltiumParser.parseArrayBufferToRendererModel(
+                normalized.input.fileName,
+                buffer
+            )
         )
         const adapted = CircuitJsonModelAdapter.fromRendererModel(native)
         const projected = AltiumCircuitJsonProjection.project(adapted, native)
@@ -54,7 +57,7 @@ export class AltiumDocumentBuilder {
             normalized.options.retainSource === 'reference'
                 ? { sourceReference: normalized.sourceReference }
                 : {}
-        return DocumentResult.createValidated(
+        return DocumentResult.createValidatedOwned(
             {
                 model,
                 source: {

package/src/convergence/AltiumSchematicImageNormalizer.mjs

@@ -0,0 +1,404 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { unzlibSync } from 'fflate'
+
+const MAX_SCANLINE_BYTES = 64 * 1024 * 1024
+const MINIMUM_VISIBLE_ALPHA_COVERAGE = 0.01
+const PNG_SIGNATURE = Uint8Array.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a
+])
+
+/**
+ * Adapts historical native schematic-image payloads at the common API boundary.
+ */
+export class AltiumSchematicImageNormalizer {
+    static #alphaCoverageCache = new WeakMap()
+
+    /**
+     * Returns a structurally shared document view with unusable historical
+     * image payloads replaced by the existing missing-image state.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @returns {Record<string, any>} Original document or normalized view.
+     */
+    static normalize(documentModel) {
+        const images = documentModel?.schematic?.images
+        if (!Array.isArray(images) || !images.length) return documentModel
+
+        const diagnostics = Array.isArray(documentModel.diagnostics)
+            ? documentModel.diagnostics
+            : []
+        let normalizedImages = null
+        const warnings = []
+
+        for (let index = 0; index < images.length; index += 1) {
+            const image = images[index]
+            if (
+                !AltiumSchematicImageNormalizer.#isInvisibleLegacyImage(image)
+            ) {
+                continue
+            }
+
+            if (!normalizedImages) normalizedImages = images.slice()
+            normalizedImages[index] = {
+                ...image,
+                mimeType: '',
+                dataBase64: '',
+                diagnosticState: 'unusable-embedded-payload'
+            }
+
+            const warning =
+                'Embedded schematic image payload is effectively invisible for ' +
+                (String(image.fileName || '') || 'unnamed image') +
+                '.'
+            if (
+                !AltiumSchematicImageNormalizer.#hasWarning(
+                    diagnostics,
+                    warning
+                ) &&
+                !warnings.some((diagnostic) => diagnostic.message === warning)
+            ) {
+                warnings.push({ severity: 'warning', message: warning })
+            }
+        }
+
+        if (!normalizedImages) return documentModel
+
+        return {
+            ...documentModel,
+            schematic: {
+                ...documentModel.schematic,
+                images: normalizedImages
+            },
+            diagnostics: warnings.length
+                ? [...diagnostics, ...warnings]
+                : documentModel.diagnostics
+        }
+    }
+
+    /**
+     * Returns true only for the precise historical BMP-to-PNG representation
+     * whose decoded alpha coverage is below one percent.
+     * @param {Record<string, any>} image Native schematic-image row.
+     * @returns {boolean} Whether the payload should become a placeholder.
+     */
+    static #isInvisibleLegacyImage(image) {
+        if (
+            !image ||
+            typeof image !== 'object' ||
+            String(image.sourceMimeType || '').toLowerCase() !== 'image/bmp' ||
+            String(image.mimeType || '').toLowerCase() !== 'image/png' ||
+            image.hasAlpha !== true ||
+            String(image.nativeClass || '') !== '' ||
+            typeof image.dataBase64 !== 'string' ||
+            !image.dataBase64
+        ) {
+            return false
+        }
+
+        const alphaCoverage =
+            AltiumSchematicImageNormalizer.#historicalPngAlphaCoverage(image)
+        return (
+            alphaCoverage !== null &&
+            alphaCoverage < MINIMUM_VISIBLE_ALPHA_COVERAGE
+        )
+    }
+
+    /**
+     * Decodes a historical parser-generated PNG and measures normalized alpha.
+     * Unknown, malformed, or differently encoded PNG payloads are rejected.
+     * @param {Record<string, any>} image Native schematic-image row.
+     * @returns {number | null} Normalized alpha coverage or null.
+     */
+    static #historicalPngAlphaCoverage(image) {
+        const cached =
+            AltiumSchematicImageNormalizer.#alphaCoverageCache.get(image)
+        if (cached?.dataBase64 === image.dataBase64) return cached.coverage
+
+        const coverage =
+            AltiumSchematicImageNormalizer.#decodeHistoricalPngAlphaCoverage(
+                image.dataBase64
+            )
+        AltiumSchematicImageNormalizer.#alphaCoverageCache.set(image, {
+            dataBase64: image.dataBase64,
+            coverage
+        })
+        return coverage
+    }
+
+    /**
+     * Parses the exact minimal RGBA8 PNG structure emitted by the historical
+     * parser and computes its alpha coverage.
+     * @param {string} dataBase64 Base64-encoded PNG bytes.
+     * @returns {number | null} Normalized alpha coverage or null.
+     */
+    static #decodeHistoricalPngAlphaCoverage(dataBase64) {
+        const png = AltiumSchematicImageNormalizer.#decodeBase64(dataBase64)
+        if (!png || !AltiumSchematicImageNormalizer.#hasPngSignature(png)) {
+            return null
+        }
+
+        const parsed = AltiumSchematicImageNormalizer.#parseHistoricalPng(png)
+        if (!parsed) return null
+
+        const scanlineLength = parsed.width * 4 + 1
+        const expectedLength = scanlineLength * parsed.height
+        if (
+            !Number.isSafeInteger(expectedLength) ||
+            expectedLength <= 0 ||
+            expectedLength > MAX_SCANLINE_BYTES ||
+            !AltiumSchematicImageNormalizer.#isHistoricalStoredZlib(
+                parsed.idat,
+                expectedLength
+            )
+        ) {
+            return null
+        }
+
+        let raw
+        try {
+            raw = unzlibSync(parsed.idat, {
+                out: new Uint8Array(expectedLength)
+            })
+        } catch {
+            return null
+        }
+        if (
+            raw.length !== expectedLength ||
+            !AltiumSchematicImageNormalizer.#hasValidAdler32(parsed.idat, raw)
+        ) {
+            return null
+        }
+
+        let alphaTotal = 0
+        for (let y = 0; y < parsed.height; y += 1) {
+            const rowOffset = y * scanlineLength
+            if (raw[rowOffset] !== 0) return null
+            for (let x = 0; x < parsed.width; x += 1) {
+                alphaTotal += raw[rowOffset + 1 + x * 4 + 3]
+            }
+        }
+        return alphaTotal / (parsed.width * parsed.height * 255)
+    }
+
+    /**
+     * Parses an exact IHDR, IDAT, IEND PNG sequence and validates chunk CRCs.
+     * @param {Uint8Array} png PNG bytes.
+     * @returns {{ width: number, height: number, idat: Uint8Array } | null} Parsed PNG facts.
+     */
+    static #parseHistoricalPng(png) {
+        const chunks = []
+        let offset = PNG_SIGNATURE.length
+
+        while (offset + 12 <= png.length) {
+            const view = new DataView(
+                png.buffer,
+                png.byteOffset + offset,
+                png.length - offset
+            )
+            const length = view.getUint32(0, false)
+            const chunkEnd = offset + 12 + length
+            if (chunkEnd > png.length) return null
+
+            const typeBytes = png.subarray(offset + 4, offset + 8)
+            const type = String.fromCharCode(...typeBytes)
+            const data = png.subarray(offset + 8, offset + 8 + length)
+            const expectedCrc = new DataView(
+                png.buffer,
+                png.byteOffset + offset + 8 + length,
+                4
+            ).getUint32(0, false)
+            if (
+                AltiumSchematicImageNormalizer.#crc32(typeBytes, data) !==
+                expectedCrc
+            ) {
+                return null
+            }
+
+            chunks.push({ type, data })
+            offset = chunkEnd
+            if (type === 'IEND') break
+        }
+
+        if (
+            offset !== png.length ||
+            chunks.length !== 3 ||
+            chunks[0].type !== 'IHDR' ||
+            chunks[1].type !== 'IDAT' ||
+            chunks[2].type !== 'IEND' ||
+            chunks[0].data.length !== 13 ||
+            chunks[2].data.length !== 0
+        ) {
+            return null
+        }
+
+        const header = chunks[0].data
+        const headerView = new DataView(
+            header.buffer,
+            header.byteOffset,
+            header.byteLength
+        )
+        const width = headerView.getUint32(0, false)
+        const height = headerView.getUint32(4, false)
+        if (
+            width <= 0 ||
+            height <= 0 ||
+            header[8] !== 8 ||
+            header[9] !== 6 ||
+            header[10] !== 0 ||
+            header[11] !== 0 ||
+            header[12] !== 0
+        ) {
+            return null
+        }
+
+        return { width, height, idat: chunks[1].data }
+    }
+
+    /**
+     * Validates the zlib stored-block layout emitted by the historical parser
+     * before allocating or inflating its payload.
+     * @param {Uint8Array} zlib Zlib stream.
+     * @param {number} expectedLength Expected raw byte count.
+     * @returns {boolean} Whether the stream has the exact safe stored layout.
+     */
+    static #isHistoricalStoredZlib(zlib, expectedLength) {
+        if (zlib.length < 11 || zlib[0] !== 0x78 || zlib[1] !== 0x01) {
+            return false
+        }
+
+        const payloadEnd = zlib.length - 4
+        let offset = 2
+        let decodedLength = 0
+        let finalBlock = false
+
+        while (!finalBlock && offset + 5 <= payloadEnd) {
+            const header = zlib[offset]
+            if (header !== 0x00 && header !== 0x01) return false
+            finalBlock = header === 0x01
+
+            const length = zlib[offset + 1] | (zlib[offset + 2] << 8)
+            const complement = zlib[offset + 3] | (zlib[offset + 4] << 8)
+            if ((length ^ complement) !== 0xffff) return false
+
+            offset += 5
+            if (offset + length > payloadEnd) return false
+            decodedLength += length
+            if (decodedLength > expectedLength) return false
+            offset += length
+        }
+
+        return (
+            finalBlock &&
+            offset === payloadEnd &&
+            decodedLength === expectedLength
+        )
+    }
+
+    /**
+     * Validates decompressed bytes against the zlib stream's big-endian
+     * Adler-32 trailer.
+     * @param {Uint8Array} zlib Complete zlib stream.
+     * @param {Uint8Array} raw Decompressed bytes.
+     * @returns {boolean} Whether the checksum is valid.
+     */
+    static #hasValidAdler32(zlib, raw) {
+        if (!(zlib instanceof Uint8Array) || zlib.length < 4) return false
+        const trailerOffset = zlib.length - 4
+        const expected = new DataView(
+            zlib.buffer,
+            zlib.byteOffset + trailerOffset,
+            4
+        ).getUint32(0, false)
+        return AltiumSchematicImageNormalizer.#adler32(raw) === expected
+    }
+
+    /**
+     * Computes an Adler-32 checksum without external runtime dependencies.
+     * @param {Uint8Array} bytes Bytes to checksum.
+     * @returns {number} Unsigned Adler-32 value.
+     */
+    static #adler32(bytes) {
+        let a = 1
+        let b = 0
+        let offset = 0
+
+        while (offset < bytes.length) {
+            const end = Math.min(offset + 5552, bytes.length)
+            for (; offset < end; offset += 1) {
+                a += bytes[offset]
+                b += a
+            }
+            a %= 65521
+            b %= 65521
+        }
+
+        return ((b << 16) | a) >>> 0
+    }
+
+    /**
+     * Decodes base64 without depending on Node-only globals.
+     * @param {string} dataBase64 Base64 text.
+     * @returns {Uint8Array | null} Decoded bytes or null.
+     */
+    static #decodeBase64(dataBase64) {
+        if (dataBase64.length > Math.ceil((MAX_SCANLINE_BYTES * 4) / 3) + 128) {
+            return null
+        }
+        try {
+            const binary = globalThis.atob(dataBase64)
+            const bytes = new Uint8Array(binary.length)
+            for (let index = 0; index < binary.length; index += 1) {
+                bytes[index] = binary.charCodeAt(index)
+            }
+            return bytes
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Checks the fixed PNG signature.
+     * @param {Uint8Array} bytes Candidate bytes.
+     * @returns {boolean} Whether the signature matches.
+     */
+    static #hasPngSignature(bytes) {
+        if (bytes.length < PNG_SIGNATURE.length) return false
+        return PNG_SIGNATURE.every((byte, index) => bytes[index] === byte)
+    }
+
+    /**
+     * Computes a PNG chunk CRC over its type and data bytes.
+     * @param {Uint8Array} typeBytes Four-byte chunk type.
+     * @param {Uint8Array} data Chunk data.
+     * @returns {number} Unsigned CRC-32.
+     */
+    static #crc32(typeBytes, data) {
+        let crc = 0xffffffff
+        for (const bytes of [typeBytes, data]) {
+            for (const byte of bytes) {
+                crc ^= byte
+                for (let bit = 0; bit < 8; bit += 1) {
+                    crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0)
+                }
+            }
+        }
+        return (crc ^ 0xffffffff) >>> 0
+    }
+
+    /**
+     * Checks whether a warning already exists without changing diagnostic rows.
+     * @param {Record<string, any>[] | undefined} diagnostics Native diagnostics.
+     * @param {string} warning Warning text.
+     * @returns {boolean} Whether the warning already exists.
+     */
+    static #hasWarning(diagnostics, warning) {
+        return (
+            Array.isArray(diagnostics) &&
+            diagnostics.some((diagnostic) => diagnostic?.message === warning)
+        )
+    }
+}
+
+Object.freeze(AltiumSchematicImageNormalizer.prototype)
+Object.freeze(AltiumSchematicImageNormalizer)

package/src/convergence/SchematicSvgRenderer.mjs

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
 import { SchematicSvgRenderer as LegacySchematicSvgRenderer } from '../ui/SchematicSvgRenderer.mjs'
+import { AltiumSchematicImageNormalizer } from './AltiumSchematicImageNormalizer.mjs'
 
 /**
  * Renders native Altium schematic models through the preserved historical
@@ -17,8 +18,10 @@ export class SchematicSvgRenderer {
      * @returns {string} Rendered SVG panel markup.
      */
     static render(documentModel, options = {}) {
+        const normalized =
+            AltiumSchematicImageNormalizer.normalize(documentModel)
         return LegacySchematicSvgRenderer.render(
-            SchematicSvgRenderer.#visibilityAwareDocument(documentModel),
+            SchematicSvgRenderer.#visibilityAwareDocument(normalized),
             options
         )
     }