altium-toolkit 1.1.3 → 1.1.22

package/docs/api.md

@@ -111,6 +111,43 @@ helpers. `PcbStatisticsBuilder` emits board QA summaries used by `.PcbDoc`
 models. `SchematicProjectParameterResolver` resolves dot-prefixed and
 equals-prefixed schematic special strings for parser and SVG integrations.
 
+## Library Exporters
+
+```js
+import {
+    SourceComponentClient,
+    SourceComponentBundleNormalizer,
+    SourceBundleExporter,
+    AltiumSchLibExporter,
+    AltiumPcbLibExporter,
+    AltiumLibraryBatchExporter
+} from 'altium-toolkit/parser'
+```
+
+The exporter surface is local-first and host-controlled:
+
+- `SourceComponentClient` performs component search, component fetch, model
+  asset fetch, retry, and response validation through an injected `fetcher`.
+  It does not use global `fetch` implicitly.
+- `SourceComponentBundleNormalizer.normalize(raw)` converts provider-specific
+  component responses into a deterministic bundle with `symbol`, `footprint`,
+  `models`, `metadata`, `sourceJson`, and diagnostics fields.
+- `SourceBundleExporter.export(bundle)` emits deterministic raw source bundle
+  entries: `manifest.json`, `source/source.json`, and optional `models/*`
+  assets.
+- `AltiumSchLibExporter.export(bundles)` and
+  `AltiumPcbLibExporter.export(bundles)` write compact OLE-backed `.SchLib`
+  and `.PcbLib` byte arrays. The `.PcbLib` writer includes generated library
+  streams plus STEP/WRL model payload streams when the normalized bundle
+  contains model assets.
+- `AltiumLibraryBatchExporter` orchestrates id lists, search-and-export,
+  per-component source/SchLib/PcbLib outputs, merged library outputs,
+  append/skip manifests, progress events, continue-on-error diagnostics, and
+  checkpoint state.
+
+Hosts are responsible for choosing and configuring any outbound component
+source. Tests use repo-owned fake responses only.
+
 ## Netlist Query
 
 ```js

package/docs/model-format.md

@@ -34,6 +34,24 @@ Circuit JSON array. `JSON.stringify(result)` serializes only the Circuit JSON
 elements, including custom `altium_toolkit_*` sidecar elements; compatibility
 fields are intentionally omitted from serialized JSON.
 
+## Source Export Bundle
+
+`SourceComponentBundleNormalizer` produces the exporter input contract used by
+the source bundle, `.SchLib`, and `.PcbLib` writers:
+
+- `id` and `name`: stable component identity
+- `metadata`: provider metadata copied into deterministic plain-object form
+- `symbol`: schematic symbol name, pins, primitives, and raw source object
+- `footprint`: PCB footprint name, primitive families, and raw source object
+- `models`: model id, file name, format, bytes/text, and optional source URL
+- `sourceJson`: the original raw response retained for reproducible exports
+- `diagnostics`: warnings for incomplete source data
+
+`SourceBundleExporter.export()` serializes the original source response and a
+manifest that lists included model assets. It does not fetch network resources;
+callers provide already-normalized model bytes or use `SourceComponentClient`
+before exporting.
+
 ## Renderer Compatibility Fields
 
 For compatibility, `AltiumParser.parseArrayBuffer()` attaches the previous

package/docs/schemas/altium_toolkit/normalized_model_a1.schema.json

@@ -1548,7 +1548,7 @@
                 "displayName",
                 "includeInBom",
                 "includeInNetlist",
-                "includeInPnp"
+                "includeInPlacement"
             ],
             "properties": {
                 "value": {
@@ -1566,7 +1566,7 @@
                 "includeInNetlist": {
                     "type": "boolean"
                 },
-                "includeInPnp": {
+                "includeInPlacement": {
                     "type": "boolean"
                 }
             },

package/docs/testing.md

@@ -6,6 +6,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Testing
 
+Exporter tests use only synthetic component responses and generated OLE
+streams. Do not add native customer files or provider-derived raw fixtures.
+When exercising source lookup, inject a fake fetcher/client and assert emitted
+entries, progress events, checkpoints, diagnostics, and OLE round trips.
+
 Run the complete suite:
 
 ```bash

package/package.json

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

package/spec/library-scope.md

@@ -31,6 +31,9 @@ rendering primitives.
 - Optional renderer CSS
 - Versioned normalized model schema identifiers and machine-readable schema
   contracts
+- Source component client, source bundle exporter, generated `.SchLib` and
+  `.PcbLib` byte exporters, and batch export orchestration with progress,
+  checkpoint, append-skip, merged output, and retry-friendly client hooks
 
 ## Out Of Scope
 
@@ -40,6 +43,8 @@ rendering primitives.
 - Three.js runtime, OrbitControls, canvas mounting, and picking
 - STEP mesh loading and browser script injection
 - Model ZIP export UI and download orchestration
+- Choosing a hosted component-source provider for applications; hosts inject
+  fetch and endpoint configuration explicitly
 - Server, deployment, and app metadata endpoints
 - Native document authoring, round-trip writing, GUI automation, and compiled
   multi-sheet project netlist generation

package/src/core/altium/AltiumLibraryBatchExporter.mjs

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { AltiumPcbLibExporter } from './AltiumPcbLibExporter.mjs'
+import { AltiumSchLibExporter } from './AltiumSchLibExporter.mjs'
+import { SourceBundleExporter } from './SourceBundleExporter.mjs'
+
+/**
+ * Orchestrates source lookup and local library export.
+ */
+export class AltiumLibraryBatchExporter {
+    #client
+
+    /**
+     * @param {{ client?: { fetchComponentBundle?: Function, searchComponents?: Function } }} [options] Batch options.
+     */
+    constructor(options = {}) {
+        this.#client = options.client || null
+    }
+
+    /**
+     * Searches components and exports the matching ids.
+     * @param {string} query Search query.
+     * @param {object} [options] Export options.
+     * @returns {Promise<object>}
+     */
+    async searchAndExport(query, options = {}) {
+        const rows = await this.#requireClient().searchComponents(
+            query,
+            options
+        )
+        return this.exportIds(
+            rows.map((row) => row.id).filter(Boolean),
+            options
+        )
+    }
+
+    /**
+     * Exports one list of provider ids.
+     * @param {string[]} ids Component ids.
+     * @param {{ appendManifest?: { completedIds?: string[] }, includeSourceBundle?: boolean, includeSchLib?: boolean, includePcbLib?: boolean, merged?: boolean, continueOnError?: boolean, onProgress?: Function }} [options] Export options.
+     * @returns {Promise<{ entries: object[], bundles: object[], diagnostics: object[], checkpoint: { completedIds: string[] } }>}
+     */
+    async exportIds(ids, options = {}) {
+        const completedIds = [
+            ...new Set(options.appendManifest?.completedIds || [])
+        ]
+        const completedSet = new Set(completedIds)
+        const entries = []
+        const bundles = []
+        const diagnostics = []
+
+        for (const id of ids
+            .map((value) => String(value || ''))
+            .filter(Boolean)) {
+            if (completedSet.has(id)) {
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'skipped'
+                })
+                continue
+            }
+
+            try {
+                const bundle =
+                    await this.#requireClient().fetchComponentBundle(id)
+                bundles.push(bundle)
+                entries.push(
+                    ...AltiumLibraryBatchExporter.#buildPerComponentEntries(
+                        id,
+                        bundle,
+                        options
+                    )
+                )
+                completedSet.add(id)
+                completedIds.push(id)
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'exported'
+                })
+            } catch (error) {
+                diagnostics.push({
+                    id,
+                    severity: 'error',
+                    message: String(error?.message || error)
+                })
+                AltiumLibraryBatchExporter.#emitProgress(options, {
+                    id,
+                    status: 'failed'
+                })
+                if (!options.continueOnError) {
+                    throw error
+                }
+            }
+        }
+
+        if (options.merged && bundles.length) {
+            entries.push(
+                ...AltiumLibraryBatchExporter.#buildMergedEntries(bundles)
+            )
+        }
+
+        return {
+            entries,
+            bundles,
+            diagnostics,
+            checkpoint: { completedIds }
+        }
+    }
+
+    /**
+     * Builds per-component export entries.
+     * @param {string} id Component id.
+     * @param {object} bundle Normalized bundle.
+     * @param {object} options Export options.
+     * @returns {object[]}
+     */
+    static #buildPerComponentEntries(id, bundle, options) {
+        const prefix = AltiumLibraryBatchExporter.#safePathSegment(id) + '/'
+        const entries = []
+
+        if (options.includeSourceBundle) {
+            entries.push(
+                ...SourceBundleExporter.export(bundle).entries.map((entry) => ({
+                    ...entry,
+                    path: prefix + entry.path
+                }))
+            )
+        }
+
+        if (options.includeSchLib) {
+            entries.push({
+                path: prefix + 'library.SchLib',
+                bytes: AltiumSchLibExporter.export([bundle]),
+                contentType: 'application/octet-stream'
+            })
+        }
+
+        if (options.includePcbLib) {
+            entries.push({
+                path: prefix + 'library.PcbLib',
+                bytes: AltiumPcbLibExporter.export([bundle]),
+                contentType: 'application/octet-stream'
+            })
+        }
+
+        return entries
+    }
+
+    /**
+     * Builds merged library output entries.
+     * @param {object[]} bundles Normalized bundles.
+     * @returns {object[]}
+     */
+    static #buildMergedEntries(bundles) {
+        return [
+            {
+                path: 'merged/library.SchLib',
+                bytes: AltiumSchLibExporter.export(bundles),
+                contentType: 'application/octet-stream'
+            },
+            {
+                path: 'merged/library.PcbLib',
+                bytes: AltiumPcbLibExporter.export(bundles),
+                contentType: 'application/octet-stream'
+            }
+        ]
+    }
+
+    /**
+     * Emits progress.
+     * @param {object} options Export options.
+     * @param {object} event Progress event.
+     * @returns {void}
+     */
+    static #emitProgress(options, event) {
+        if (typeof options.onProgress === 'function') {
+            options.onProgress(event)
+        }
+    }
+
+    /**
+     * Sanitizes one path segment.
+     * @param {string} value Raw value.
+     * @returns {string}
+     */
+    static #safePathSegment(value) {
+        return String(value || 'component').replace(
+            /[\\/:\u0000-\u001f]/gu,
+            '_'
+        )
+    }
+
+    /**
+     * Returns the configured client or throws.
+     * @returns {{ fetchComponentBundle?: Function, searchComponents?: Function }}
+     */
+    #requireClient() {
+        if (!this.#client) {
+            throw new Error('AltiumLibraryBatchExporter client is required.')
+        }
+
+        return this.#client
+    }
+}

package/src/core/altium/AltiumLibraryRecordBuilder.mjs

@@ -0,0 +1,293 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic textual and byte records for generated Altium libraries.
+ */
+export class AltiumLibraryRecordBuilder {
+    /**
+     * Builds a schematic component record.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {string}
+     */
+    static buildSchematicComponentRecord(bundle) {
+        return AltiumLibraryRecordBuilder.#pipeRecord({
+            RECORD: 'Component',
+            Name: bundle.symbol.name,
+            SourceId: bundle.id,
+            DisplayName: bundle.name,
+            PinCount: String(bundle.symbol.pins.length),
+            PrimitiveCount: String(bundle.symbol.primitives.length)
+        })
+    }
+
+    /**
+     * Builds a PCB footprint record.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {string}
+     */
+    static buildPcbFootprintRecord(bundle) {
+        return AltiumLibraryRecordBuilder.#pipeRecord({
+            RECORD: 'Footprint',
+            Name: bundle.footprint.name,
+            SourceId: bundle.id,
+            DisplayName: bundle.name,
+            PadCount: String(bundle.footprint.pads.length),
+            TrackCount: String(bundle.footprint.tracks.length),
+            ModelCount: String(bundle.models.length)
+        })
+    }
+
+    /**
+     * Builds a PcbLib Library/Data stream.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildPcbLibraryData(bundles) {
+        const countBytes = AltiumLibraryRecordBuilder.createCountHeader(
+            bundles.length
+        )
+
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createProperties({
+                HEADER: 'PCB 6.0 Binary Library File',
+                WEIGHT: '0',
+                GENERATEDBY: 'ECAD Forge'
+            }),
+            countBytes,
+            ...bundles.map((bundle) =>
+                AltiumLibraryRecordBuilder.createStringBlock(
+                    bundle.footprint.name
+                )
+            )
+        ])
+    }
+
+    /**
+     * Builds a PcbLib component parameters table.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildComponentParamsToc(bundles) {
+        return AltiumLibraryRecordBuilder.concatBytes(
+            bundles.map((bundle) =>
+                AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+                    AltiumLibraryRecordBuilder.#pipeRecord({
+                        Name: bundle.footprint.name,
+                        'Pad Count': String(bundle.footprint.pads.length),
+                        Height: String(bundle.metadata.height || ''),
+                        Description: String(bundle.metadata.description || '')
+                    }) + '\r\n\u0000'
+                )
+            )
+        )
+    }
+
+    /**
+     * Builds a SectionKeys stream.
+     * @param {object[]} bundles Normalized component bundles.
+     * @returns {Uint8Array}
+     */
+    static buildSectionKeys(bundles) {
+        const entries = bundles.map((bundle) => ({
+            fullName: bundle.footprint.name,
+            storageName: AltiumLibraryRecordBuilder.sanitizeStorageName(
+                bundle.footprint.name
+            )
+        }))
+
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createCountHeader(entries.length),
+            ...entries.flatMap((entry) => [
+                AltiumLibraryRecordBuilder.createStringBlock(entry.fullName),
+                AltiumLibraryRecordBuilder.createStringBlock(entry.storageName)
+            ])
+        ])
+    }
+
+    /**
+     * Builds a footprint Data stream.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {Uint8Array}
+     */
+    static buildFootprintData(bundle) {
+        return AltiumLibraryRecordBuilder.concatBytes([
+            AltiumLibraryRecordBuilder.createStringBlock(bundle.footprint.name)
+        ])
+    }
+
+    /**
+     * Builds a footprint Parameters stream.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {Uint8Array}
+     */
+    static buildFootprintParameters(bundle) {
+        return AltiumLibraryRecordBuilder.createProperties({
+            PATTERN: bundle.footprint.name,
+            DESCRIPTION: String(bundle.metadata.description || ''),
+            HEIGHT: String(bundle.metadata.height || ''),
+            ITEMGUID: AltiumLibraryRecordBuilder.#guidFromText(bundle.id)
+        })
+    }
+
+    /**
+     * Builds model metadata entries.
+     * @param {{ model: object, id: string, checksum: number }[]} models Model rows.
+     * @returns {Uint8Array}
+     */
+    static buildModelsData(models) {
+        return AltiumLibraryRecordBuilder.concatBytes(
+            models.map((row) =>
+                AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+                    AltiumLibraryRecordBuilder.#pipeRecord({
+                        ID: row.id,
+                        NAME: row.model.name,
+                        CHECKSUM: String(row.checksum),
+                        FORMAT: row.model.format
+                    }) + '\u0000'
+                )
+            )
+        )
+    }
+
+    /**
+     * Creates a little-endian count header.
+     * @param {number} count Count value.
+     * @returns {Uint8Array}
+     */
+    static createCountHeader(count) {
+        const bytes = new Uint8Array(4)
+        new DataView(bytes.buffer).setUint32(0, Number(count || 0), true)
+        return bytes
+    }
+
+    /**
+     * Creates a PcbLib property stream.
+     * @param {Record<string, string>} properties Properties.
+     * @returns {Uint8Array}
+     */
+    static createProperties(properties) {
+        return AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
+            AltiumLibraryRecordBuilder.#pipeRecord(properties) + '\u0000'
+        )
+    }
+
+    /**
+     * Creates a Pascal-style string block.
+     * @param {string} text Text value.
+     * @returns {Uint8Array}
+     */
+    static createStringBlock(text) {
+        const encoded = new TextEncoder().encode(String(text || ''))
+        const bytes = new Uint8Array(4 + 1 + encoded.byteLength)
+        const view = new DataView(bytes.buffer)
+
+        view.setUint32(0, 1 + encoded.byteLength, true)
+        bytes[4] = encoded.byteLength
+        bytes.set(encoded, 5)
+
+        return bytes
+    }
+
+    /**
+     * Creates a length-prefixed ASCII/UTF-8 byte block.
+     * @param {string} text Text body.
+     * @returns {Uint8Array}
+     */
+    static createLengthPrefixedAscii(text) {
+        const encoded = new TextEncoder().encode(String(text || ''))
+        const bytes = new Uint8Array(4 + encoded.byteLength)
+
+        new DataView(bytes.buffer).setUint32(0, encoded.byteLength, true)
+        bytes.set(encoded, 4)
+
+        return bytes
+    }
+
+    /**
+     * Concatenates byte chunks.
+     * @param {Uint8Array[]} chunks Byte chunks.
+     * @returns {Uint8Array}
+     */
+    static concatBytes(chunks) {
+        const byteLength = chunks.reduce(
+            (sum, chunk) => sum + chunk.byteLength,
+            0
+        )
+        const bytes = new Uint8Array(byteLength)
+        let offset = 0
+
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset)
+            offset += chunk.byteLength
+        }
+
+        return bytes
+    }
+
+    /**
+     * Sanitizes one OLE storage name.
+     * @param {string} name Storage name.
+     * @returns {string}
+     */
+    static sanitizeStorageName(name) {
+        return String(name || 'Component')
+            .replace(/[\\/:\u0000-\u001f]/gu, '_')
+            .slice(0, 31)
+    }
+
+    /**
+     * Computes a simple deterministic checksum for generated model metadata.
+     * @param {Uint8Array} bytes Model bytes.
+     * @returns {number}
+     */
+    static checksumBytes(bytes) {
+        return [...bytes].reduce(
+            (checksum, value) => (checksum + value) >>> 0,
+            0
+        )
+    }
+
+    /**
+     * Builds one pipe-delimited record.
+     * @param {Record<string, string>} fields Record fields.
+     * @returns {string}
+     */
+    static #pipeRecord(fields) {
+        return (
+            '|' +
+            Object.entries(fields)
+                .filter(([, value]) => String(value ?? '') !== '')
+                .map(([key, value]) => key + '=' + String(value))
+                .join('|')
+        )
+    }
+
+    /**
+     * Builds a deterministic GUID-like id from text.
+     * @param {string} text Source text.
+     * @returns {string}
+     */
+    static #guidFromText(text) {
+        const hex = [...new TextEncoder().encode(String(text || ''))]
+            .map((value) => value.toString(16).padStart(2, '0'))
+            .join('')
+            .padEnd(32, '0')
+            .slice(0, 32)
+
+        return (
+            '{' +
+            hex.slice(0, 8) +
+            '-' +
+            hex.slice(8, 12) +
+            '-' +
+            hex.slice(12, 16) +
+            '-' +
+            hex.slice(16, 20) +
+            '-' +
+            hex.slice(20) +
+            '}'
+        )
+    }
+}

package/src/core/altium/AltiumParser.mjs

@@ -238,8 +238,11 @@ export class AltiumParser {
         const rectangleRecords = drawableRecords.filter(
             (record) =>
                 SchematicPrimitiveParser.isRectangleRecord(record.fields) &&
-                AltiumParser.#hasCoordinatePair(record.fields, 'Location') &&
-                AltiumParser.#hasCoordinatePair(record.fields, 'Corner')
+                ((AltiumParser.#hasCoordinatePair(record.fields, 'Location') &&
+                    AltiumParser.#hasCoordinatePair(record.fields, 'Corner')) ||
+                    SchematicPrimitiveParser.isPointListedRectangleRecord(
+                        record.fields
+                    ))
         )
         const roundedRectangleRecords = drawableRecords.filter(
             (record) =>