altium-toolkit 1.1.2 → 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.2",
+    "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/AltiumLayoutParser.mjs

@@ -267,7 +267,7 @@ export class AltiumLayoutParser {
      * @param {{ width: number, height: number, marginWidth: number, paperSize?: string }} sheet
      * @param {{ fields: Record<string, string | string[]> }[]} textRecords
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} lines
-     * @param {{ x: number, y: number }[]} texts
+     * @param {{ x: number, y: number, cornerX?: number, cornerY?: number }[]} texts
      * @param {{ x: number, y: number }[]} components
      * @param {{ x: number, y: number }[]} pins
      * @param {{ x: number, y: number, width: number, height: number }[]} rectangles
@@ -303,12 +303,47 @@ export class AltiumLayoutParser {
         }
 
         const margin = Math.max(Number(sheet?.marginWidth || 20), 20)
+        const nativeTemplateSheet =
+            AltiumLayoutParser.#resolveNativeStandardTemplateSheetSize(
+                sheet,
+                bounds,
+                margin
+            )
+        if (nativeTemplateSheet) {
+            return {
+                ...sheet,
+                ...nativeTemplateSheet
+            }
+        }
+
+        if (
+            AltiumLayoutParser.#shouldPreserveNativeStandardTemplateSize(
+                sheet,
+                bounds,
+                margin
+            )
+        ) {
+            return sheet
+        }
+
         const footerBounds = AltiumLayoutParser.#collectSchematicFooterBounds(
             textRecords,
             Number(sheet?.width || 0)
         )
-        const requiredWidth =
-            Math.max(bounds.maxX, footerBounds?.maxX || 0) + margin * 2
+        const footerLineBounds =
+            AltiumLayoutParser.#collectSchematicFooterLineBounds(
+                lines,
+                sheet,
+                margin
+            )
+        const requiredWidthResult =
+            AltiumLayoutParser.#resolveSchematicRequiredWidth(
+                sheet,
+                Math.max(bounds.maxX, footerBounds?.maxX || 0),
+                footerLineBounds?.maxX || 0,
+                margin
+            )
+        const requiredWidth = requiredWidthResult.width
         const requiredHeight =
             Math.max(bounds.maxY, footerBounds?.maxY || 0) + margin * 2
 
@@ -322,10 +357,12 @@ export class AltiumLayoutParser {
             return sheet
         }
 
-        const standardSheet = AltiumLayoutParser.#resolveStandardSheetSize(
-            requiredWidth,
-            requiredHeight
-        )
+        const standardSheet = requiredWidthResult.usesNativeFrameEdge
+            ? null
+            : AltiumLayoutParser.#resolveStandardSheetSize(
+                  requiredWidth,
+                  requiredHeight
+              )
 
         if (standardSheet) {
             return {
@@ -344,11 +381,12 @@ export class AltiumLayoutParser {
             sheet.height,
             requiredHeight
         )
-        const resolvedStandardSheet =
-            AltiumLayoutParser.#resolveStandardSheetSize(
-                resolvedWidth,
-                resolvedHeight
-            )
+        const resolvedStandardSheet = requiredWidthResult.usesNativeFrameEdge
+            ? null
+            : AltiumLayoutParser.#resolveStandardSheetSize(
+                  resolvedWidth,
+                  resolvedHeight
+              )
 
         if (resolvedStandardSheet) {
             return {
@@ -367,6 +405,126 @@ export class AltiumLayoutParser {
         }
     }
 
+    /**
+     * Resolves the standard template page named by Altium standard sheet
+     * records, preserving landscape or portrait orientation from the stored
+     * custom dimensions.
+     * @param {Record<string, string | string[]> | undefined} fields Sheet fields.
+     * @param {number} fallbackWidth Stored custom width.
+     * @param {number} fallbackHeight Stored custom height.
+     * @returns {{ width: number, height: number, paperSize: string, sourceWidth?: number, sourceHeight?: number } | null}
+     */
+    static resolveSchematicTemplatePageSize(
+        fields,
+        fallbackWidth,
+        fallbackHeight
+    ) {
+        if (parseNumericField(fields, 'SheetStyle') !== 1) {
+            return null
+        }
+
+        const templateFileName = getField(fields, 'TemplateFileName')
+        const match = String(templateFileName || '').match(
+            /(?:^|[^a-z0-9])A([0-5])(?:[^a-z0-9]|$)/iu
+        )
+
+        if (!match) {
+            return null
+        }
+
+        const paperSize = 'A' + match[1]
+        const portraitSheet = ISO_A_PORTRAIT_SHEETS.find(
+            (sheet) => sheet.label === paperSize
+        )
+
+        if (!portraitSheet) {
+            return null
+        }
+
+        const normalizedFallbackWidth = Number(fallbackWidth || 0)
+        const normalizedFallbackHeight = Number(fallbackHeight || 0)
+        const portraitTemplate =
+            parseNumericField(fields, 'WorkspaceOrientation') === 1 ||
+            /portrait/iu.test(String(templateFileName || ''))
+
+        if (
+            portraitTemplate &&
+            normalizedFallbackWidth > normalizedFallbackHeight &&
+            normalizedFallbackHeight > 0
+        ) {
+            return {
+                width: normalizedFallbackHeight,
+                height: normalizedFallbackWidth,
+                sourceWidth: normalizedFallbackHeight,
+                sourceHeight: normalizedFallbackWidth,
+                paperSize
+            }
+        }
+
+        const landscape = normalizedFallbackWidth >= normalizedFallbackHeight
+
+        return {
+            width: landscape ? portraitSheet.height : portraitSheet.width,
+            height: landscape ? portraitSheet.width : portraitSheet.height,
+            paperSize
+        }
+    }
+
+    /**
+     * Resolves the page width required by recovered schematic geometry.
+     * Native template linework can use the declared custom width as the inner
+     * frame edge; adding both margins would create an artificial right gutter.
+     * @param {{ width?: number, borderOn?: boolean, titleBlockOn?: boolean, sheetStyle?: number }} sheet
+     * @param {number} maxX
+     * @param {number} footerLineMaxX
+     * @param {number} margin
+     * @returns {{ width: number, usesNativeFrameEdge: boolean }}
+     */
+    static #resolveSchematicRequiredWidth(sheet, maxX, footerLineMaxX, margin) {
+        const reachesNativeFrameEdge =
+            Number(sheet?.sheetStyle || 0) !== 1 &&
+            Boolean(sheet?.borderOn || sheet?.titleBlockOn) &&
+            footerLineMaxX > 0 &&
+            maxX <= footerLineMaxX + 0.01
+        const rightPadding = reachesNativeFrameEdge ? margin : margin * 2
+
+        return {
+            width: maxX + rightPadding,
+            usesNativeFrameEdge: reachesNativeFrameEdge
+        }
+    }
+
+    /**
+     * Collects owned lower-page linework that represents native title-block or
+     * footer chrome rather than schematic content.
+     * @param {{ x1: number, y1: number, x2: number, y2: number, ownerIndex?: string }[]} lines
+     * @param {{ width?: number }} sheet
+     * @param {number} margin
+     * @returns {{ maxX: number } | null}
+     */
+    static #collectSchematicFooterLineBounds(lines, sheet, margin) {
+        const footerLimit = Math.max(margin * 6, 120)
+        const sheetWidth = Math.max(Number(sheet?.width || 0), 0)
+        const footerStartX = sheetWidth > 0 ? sheetWidth * 0.5 : 0
+        const coordinates = []
+
+        for (const line of lines || []) {
+            if (!line?.ownerIndex) continue
+            if (Math.max(line.y1, line.y2) > footerLimit) continue
+            if (Math.max(line.x1, line.x2) < footerStartX) continue
+
+            coordinates.push(line.x1, line.x2)
+        }
+
+        if (!coordinates.length) {
+            return null
+        }
+
+        return {
+            maxX: Math.max(...coordinates)
+        }
+    }
+
     /**
      * Returns true when the parser should trust the authored custom sheet
      * dimensions instead of shrinking the page to visible content bounds.
@@ -403,11 +561,108 @@ export class AltiumLayoutParser {
         return false
     }
 
+    /**
+     * Returns true when a standard template has already resolved to its native
+     * template coordinate frame rather than a promoted ISO sheet envelope.
+     * @param {{ width?: number, height?: number, sourceWidth?: number, sourceHeight?: number, paperSize?: string, sheetStyle?: number }} sheet
+     * @param {{ maxX: number, maxY: number }} bounds
+     * @param {number} margin
+     * @returns {boolean}
+     */
+    static #shouldPreserveNativeStandardTemplateSize(sheet, bounds, margin) {
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        const sourceWidth = Number(sheet?.sourceWidth || 0)
+        const sourceHeight = Number(sheet?.sourceHeight || 0)
+
+        if (
+            Number(sheet?.sheetStyle || 0) !== 1 ||
+            !sheet?.paperSize ||
+            width <= 0 ||
+            height <= 0 ||
+            width !== sourceWidth ||
+            height !== sourceHeight
+        ) {
+            return false
+        }
+
+        return (
+            Number(bounds?.maxX || 0) <= width - margin + 0.01 &&
+            Number(bounds?.maxY || 0) <= height - margin + 0.01
+        )
+    }
+
+    /**
+     * Derives a native standard-template frame from embedded template graphics
+     * when those graphics overrun the stored custom dimensions but fit inside
+     * a smaller-than-ISO template envelope.
+     * @param {{ width?: number, height?: number, sourceWidth?: number, sourceHeight?: number, paperSize?: string, sheetStyle?: number }} sheet
+     * @param {{ maxX: number, maxY: number }} bounds
+     * @param {number} margin
+     * @returns {{ width: number, height: number, sourceWidth: number, sourceHeight: number } | null}
+     */
+    static #resolveNativeStandardTemplateSheetSize(sheet, bounds, margin) {
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        const sourceWidth = Number(sheet?.sourceWidth || 0)
+        const sourceHeight = Number(sheet?.sourceHeight || 0)
+
+        if (
+            Number(sheet?.sheetStyle || 0) !== 1 ||
+            !sheet?.paperSize ||
+            sourceWidth <= 0 ||
+            sourceHeight <= 0 ||
+            width <= sourceWidth ||
+            height <= sourceHeight
+        ) {
+            return null
+        }
+
+        const maxX = Number(bounds?.maxX || 0)
+        const maxY = Number(bounds?.maxY || 0)
+        if (maxX <= sourceWidth && maxY <= sourceHeight) {
+            return null
+        }
+
+        const nativeWidth = AltiumLayoutParser.#roundTemplateExtent(
+            maxX + margin
+        )
+        const nativeHeight = AltiumLayoutParser.#roundTemplateExtent(
+            maxY + margin
+        )
+
+        if (
+            nativeWidth <= sourceWidth ||
+            nativeHeight <= sourceHeight ||
+            nativeWidth >= width ||
+            nativeHeight >= height
+        ) {
+            return null
+        }
+
+        return {
+            width: nativeWidth,
+            height: nativeHeight,
+            sourceWidth: nativeWidth,
+            sourceHeight: nativeHeight
+        }
+    }
+
+    /**
+     * Rounds a recovered template frame edge to the next schematic grid
+     * interval.
+     * @param {number} value Raw extent.
+     * @returns {number}
+     */
+    static #roundTemplateExtent(value) {
+        return Math.ceil(Math.max(Number(value || 0), 0) / 10) * 10
+    }
+
     /**
      * Collects the visible coordinate envelope from recovered schematic
      * primitives.
      * @param {{ x1: number, y1: number, x2: number, y2: number }[]} lines
-     * @param {{ x: number, y: number }[]} texts
+     * @param {{ x: number, y: number, cornerX?: number, cornerY?: number }[]} texts
      * @param {{ x: number, y: number }[]} components
      * @param {{ x: number, y: number }[]} pins
      * @param {{ x: number, y: number, width: number, height: number }[]} rectangles
@@ -434,6 +689,13 @@ export class AltiumLayoutParser {
 
         for (const text of texts) {
             coordinates.push([text.x, text.y])
+
+            if (
+                Number.isFinite(Number(text.cornerX)) &&
+                Number.isFinite(Number(text.cornerY))
+            ) {
+                coordinates.push([Number(text.cornerX), Number(text.cornerY)])
+            }
         }
 
         for (const component of components) {

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
+    }
+}