altium-toolkit 1.1.41 → 1.2.0

package/src/convergence/AltiumProjectDocumentResolver.mjs

@@ -0,0 +1,324 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { DocumentResult } from 'circuitjson-toolkit/parser'
+
+import { SchematicProjectParameterResolver } from '../core/altium/SchematicProjectParameterResolver.mjs'
+
+const SCHEMATIC_TITLE_BLOCK_FIELDS = [
+    'title',
+    'revision',
+    'documentNumber',
+    'sheetNumber',
+    'sheetTotal',
+    'date',
+    'drawnBy'
+]
+
+/**
+ * Resolves project-owned schematic strings inside canonical documents.
+ */
+export class AltiumProjectDocumentResolver {
+    /**
+     * Returns canonical documents with referenced schematic strings resolved.
+     * @param {{ projectEntry?: { name: string, input: { data: string | ArrayBuffer | Uint8Array } } | null }} classified Classified project entries.
+     * @param {object[]} documents Parsed canonical documents.
+     * @param {string | string[]} extensionSelection Public extension selection.
+     * @returns {object[]} Original or resolved canonical documents.
+     */
+    static resolve(classified, documents, extensionSelection) {
+        const context = AltiumProjectDocumentResolver.#context(
+            classified,
+            documents
+        )
+        const exposesProjectContext =
+            AltiumProjectDocumentResolver.#exposesProjectContext(
+                extensionSelection
+            )
+
+        let changed = false
+        const resolved = documents.map((document) => {
+            const next = context
+                ? AltiumProjectDocumentResolver.#document(
+                      document,
+                      context,
+                      exposesProjectContext
+                  )
+                : AltiumProjectDocumentResolver.#withProjectContextExposure(
+                      document,
+                      exposesProjectContext
+                  )
+            changed ||= next !== document
+            return next
+        })
+        return changed ? resolved : documents
+    }
+
+    /**
+     * Reads compact project facts from its canonical extension.
+     * @param {{ projectEntry?: { name: string, input: { data: string | ArrayBuffer | Uint8Array } } | null }} classified Classified project entries.
+     * @param {object[]} documents Parsed canonical documents.
+     * @returns {{ fileName: string, parameters: Record<string, any>, documents: string[] } | null} Project context.
+     */
+    static #context(classified, documents) {
+        const entry = classified?.projectEntry
+        if (!entry) return null
+        const projectDocument = documents.find(
+            (document) =>
+                document?.source?.fileType === 'prjpcb' &&
+                document.source.fileName === entry.name
+        )
+        const projectContext =
+            projectDocument?.extensions?.altium?.projectContext
+        if (!projectContext) return null
+        return {
+            fileName: entry.name,
+            parameters: projectContext.parameters || {},
+            documents: Array.isArray(projectContext.documents)
+                ? projectContext.documents
+                : []
+        }
+    }
+
+    /**
+     * Resolves one schematic document without mutating its proven model.
+     * @param {object} document Canonical document.
+     * @param {{ fileName: string, parameters: Record<string, any>, documents: string[] }} context Project context.
+     * @param {boolean} exposesProjectContext Whether compact context remains public.
+     * @returns {object} Original or rebuilt canonical document.
+     */
+    static #document(document, context, exposesProjectContext) {
+        if (String(document?.source?.fileType || '') !== 'schdoc') {
+            return AltiumProjectDocumentResolver.#withProjectContextExposure(
+                document,
+                exposesProjectContext
+            )
+        }
+        if (
+            context.documents.length &&
+            !AltiumProjectDocumentResolver.#mentions(
+                context.documents,
+                document.source.fileName
+            )
+        ) {
+            return AltiumProjectDocumentResolver.#withProjectContextExposure(
+                document,
+                exposesProjectContext
+            )
+        }
+        const parameters = {
+            ...context.parameters,
+            ...AltiumProjectDocumentResolver.#currentValues(),
+            ProjectName: AltiumProjectDocumentResolver.#baseName(
+                context.fileName
+            ),
+            DataSourceFileName: AltiumProjectDocumentResolver.#baseName(
+                context.fileName
+            ),
+            DocumentName: AltiumProjectDocumentResolver.#baseName(
+                document.source.fileName
+            ),
+            DocumentFullPathAndName: document.source.fileName
+        }
+        let resolutionCount = 0
+        const model = document.model.map((element) => {
+            if (element?.type !== 'schematic_text') return element
+            const resolved = SchematicProjectParameterResolver.resolveText(
+                element.text,
+                parameters
+            )
+            if (!resolved || resolved.resolvedText === element.text) {
+                return element
+            }
+            resolutionCount += 1
+            return { ...element, text: resolved.resolvedText }
+        })
+        const hidesProjectContext =
+            !exposesProjectContext &&
+            Boolean(document?.extensions?.altium?.projectContext)
+        const native = hidesProjectContext
+            ? undefined
+            : document?.extensions?.altium?.native
+        const resolvedNative =
+            AltiumProjectDocumentResolver.#resolvedNativeDocument(
+                native,
+                parameters
+            )
+        const extensions = hidesProjectContext
+            ? {}
+            : resolvedNative === native
+              ? document.extensions
+              : {
+                    altium: {
+                        ...document.extensions.altium,
+                        native: resolvedNative
+                    }
+                }
+        if (
+            !resolutionCount &&
+            resolvedNative === native &&
+            extensions === document.extensions
+        ) {
+            return document
+        }
+        return AltiumProjectDocumentResolver.#rebuild(document, {
+            model,
+            extensions,
+            statistics:
+                resolutionCount || resolvedNative !== native
+                    ? {
+                          ...document.statistics,
+                          resolvedProjectParameterCount: resolutionCount
+                      }
+                    : document.statistics
+        })
+    }
+
+    /**
+     * Resolves retained native schematic text and title-block fields through the
+     * same project parameter set used by the canonical CircuitJSON model.
+     * @param {object | null | undefined} native Retained native renderer model.
+     * @param {Record<string, any>} parameters Resolved project parameters.
+     * @returns {object | null | undefined} Original or resolved native model.
+     */
+    static #resolvedNativeDocument(native, parameters) {
+        if (!native?.schematic) return native
+        const resolved = SchematicProjectParameterResolver.applyToDocumentModel(
+            native,
+            parameters,
+            { replaceText: true }
+        )
+        const sourceTexts = Array.isArray(native.schematic.texts)
+            ? native.schematic.texts
+            : []
+        const resolvedTexts = Array.isArray(resolved.schematic.texts)
+            ? resolved.schematic.texts
+            : []
+        const textChanged = sourceTexts.some(
+            (text, index) => text?.text !== resolvedTexts[index]?.text
+        )
+        const sourceTitleBlock = native.schematic.sheet?.titleBlock || {}
+        const resolvedTitleBlock = resolved.schematic.sheet?.titleBlock || {}
+        const titleBlockChanged = SCHEMATIC_TITLE_BLOCK_FIELDS.some(
+            (field) => sourceTitleBlock[field] !== resolvedTitleBlock[field]
+        )
+        if (!textChanged && !titleBlockChanged) return native
+        return { ...resolved, projectParameters: parameters }
+    }
+
+    /**
+     * Applies compact project-context exposure without rebuilding documents that
+     * already match the public selection.
+     * @param {object} document Canonical document.
+     * @param {boolean} exposesProjectContext Whether compact context remains public.
+     * @returns {object} Original or rebuilt project document.
+     */
+    static #withProjectContextExposure(document, exposesProjectContext) {
+        if (
+            exposesProjectContext ||
+            !document?.extensions?.altium?.projectContext
+        ) {
+            return document
+        }
+        return AltiumProjectDocumentResolver.#rebuild(document, {
+            extensions: {}
+        })
+    }
+
+    /**
+     * Returns true when public selection includes compact project context.
+     * @param {string | string[]} selection Extension selection.
+     * @returns {boolean} Whether project facts remain public.
+     */
+    static #exposesProjectContext(selection) {
+        if (!Array.isArray(selection)) return selection !== 'none'
+        return (
+            selection.includes('altium.project-context') ||
+            selection.includes('altium.native-model')
+        )
+    }
+
+    /**
+     * Rebuilds one canonical document through the validating shared boundary.
+     * @param {object} document Existing canonical document.
+     * @param {{ model?: object[], extensions?: object, statistics?: object }} fields Replacements.
+     * @returns {object} Proven immutable document.
+     */
+    static #rebuild(document, fields) {
+        return DocumentResult.createValidated(
+            {
+                id: document.id,
+                model: fields.model || document.model,
+                source: document.source,
+                extensions:
+                    fields.extensions === undefined
+                        ? document.extensions
+                        : fields.extensions,
+                assets: document.assets,
+                diagnostics: document.diagnostics,
+                statistics: fields.statistics || document.statistics
+            },
+            AltiumProjectDocumentResolver.#runtime(document)
+        )
+    }
+
+    /**
+     * Preserves an explicit source reference when the parser retained one.
+     * @param {object} document Canonical document.
+     * @returns {{ sourceReference?: object }} Runtime-only fields.
+     */
+    static #runtime(document) {
+        const descriptor = Object.getOwnPropertyDescriptor(
+            document,
+            'sourceReference'
+        )
+        return descriptor && Object.hasOwn(descriptor, 'value')
+            ? { sourceReference: descriptor.value }
+            : {}
+    }
+
+    /**
+     * Builds current-value special strings used by Altium templates.
+     * @returns {{ CurrentDate: string, CurrentTime: string }} Current values.
+     */
+    static #currentValues() {
+        const now = new Date()
+        return {
+            CurrentDate: now.toLocaleDateString('en-US'),
+            CurrentTime: now.toLocaleTimeString('en-US')
+        }
+    }
+
+    /**
+     * Returns the final normalized path segment.
+     * @param {unknown} value Path value.
+     * @returns {string} Basename.
+     */
+    static #baseName(value) {
+        const path = String(value || '').replaceAll('\\', '/')
+        return path.split('/').pop() || path
+    }
+
+    /**
+     * Returns true when project paths own one schematic source path.
+     * @param {string[]} projectPaths Normalized project document paths.
+     * @param {string} fileName Canonical source path.
+     * @returns {boolean} Whether the project references the schematic.
+     */
+    static #mentions(projectPaths, fileName) {
+        const source = String(fileName || '').replaceAll('\\', '/')
+        const sourceBaseName = AltiumProjectDocumentResolver.#baseName(source)
+        return projectPaths.some((value) => {
+            const path = String(value || '').replaceAll('\\', '/')
+            return (
+                path === source ||
+                source.endsWith('/' + path) ||
+                path.endsWith('/' + source) ||
+                AltiumProjectDocumentResolver.#baseName(path) === sourceBaseName
+            )
+        })
+    }
+}
+
+Object.freeze(AltiumProjectDocumentResolver.prototype)
+Object.freeze(AltiumProjectDocumentResolver)

package/src/convergence/AltiumSchematicCoordinateProjection.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const POINT_FIELDS = [
+    'anchor_position',
+    'center',
+    'end',
+    'mid',
+    'position',
+    'start'
+]
+const POINT_LIST_FIELDS = ['junctions', 'outline', 'points']
+
+/**
+ * Converts Altium's bottom-origin schematic geometry to canonical SVG space.
+ */
+export class AltiumSchematicCoordinateProjection {
+    /**
+     * Reflects only schematic geometry through the authored sheet height.
+     * @param {object[]} model CircuitJSON model rows.
+     * @param {unknown} sheetHeight Native rendered sheet height.
+     * @returns {object[]} Projected model rows.
+     */
+    static project(model, sheetHeight) {
+        const height = Number(sheetHeight)
+        if (!Number.isFinite(height) || height <= 0) return [...model]
+        return model.map((element) =>
+            String(element?.type || '').startsWith('schematic_') &&
+            element.type !== 'schematic_sheet'
+                ? AltiumSchematicCoordinateProjection.#element(element, height)
+                : element
+        )
+    }
+
+    /**
+     * Reflects every common point-bearing field on one schematic row.
+     * @param {Record<string, any>} element CircuitJSON element.
+     * @param {number} height Sheet height.
+     * @returns {Record<string, any>} Reflected element.
+     */
+    static #element(element, height) {
+        const projected = { ...element }
+        for (const field of POINT_FIELDS) {
+            if (element[field] !== undefined) {
+                projected[field] = AltiumSchematicCoordinateProjection.#point(
+                    element[field],
+                    height
+                )
+            }
+        }
+        for (const field of POINT_LIST_FIELDS) {
+            if (Array.isArray(element[field])) {
+                projected[field] = element[field].map((point) =>
+                    AltiumSchematicCoordinateProjection.#point(point, height)
+                )
+            }
+        }
+        for (const field of ['y', 'y1', 'y2']) {
+            const value = Number(element[field])
+            if (Number.isFinite(value)) projected[field] = height - value
+        }
+        if (Array.isArray(element.edges)) {
+            projected.edges = element.edges.map((edge) => ({
+                ...edge,
+                ...(edge?.from
+                    ? {
+                          from: AltiumSchematicCoordinateProjection.#point(
+                              edge.from,
+                              height
+                          )
+                      }
+                    : {}),
+                ...(edge?.to
+                    ? {
+                          to: AltiumSchematicCoordinateProjection.#point(
+                              edge.to,
+                              height
+                          )
+                      }
+                    : {})
+            }))
+        }
+        if (element.type === 'schematic_arc') {
+            for (const field of ['start_angle_degrees', 'end_angle_degrees']) {
+                if (
+                    Object.hasOwn(element, field) &&
+                    Number.isFinite(Number(element[field]))
+                ) {
+                    projected[field] =
+                        AltiumSchematicCoordinateProjection.#angle(
+                            element[field]
+                        )
+                }
+            }
+            if (element.direction === 'clockwise') {
+                projected.direction = 'counterclockwise'
+            } else if (element.direction === 'counterclockwise') {
+                projected.direction = 'clockwise'
+            }
+        }
+        return projected
+    }
+
+    /**
+     * Reflects an angle while keeping canonical zero positive.
+     * @param {unknown} value Angle candidate.
+     * @returns {number} Reflected angle.
+     */
+    static #angle(value) {
+        const angle = Number(value || 0)
+        return angle ? -angle : 0
+    }
+
+    /**
+     * Reflects one point without dropping its relation metadata.
+     * @param {unknown} value Point candidate.
+     * @param {number} height Sheet height.
+     * @returns {unknown} Reflected point or the original value.
+     */
+    static #point(value, height) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return value
+        }
+        const y = Number(value.y)
+        return Number.isFinite(y) ? { ...value, y: height - y } : value
+    }
+}
+
+Object.freeze(AltiumSchematicCoordinateProjection.prototype)
+Object.freeze(AltiumSchematicCoordinateProjection)

package/src/convergence/AltiumWorkerClient.mjs

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserWorkerClient } from 'circuitjson-toolkit/parser'
+
+let client = null
+
+/**
+ * Owns the source-format worker client while reusing the shared protocol.
+ */
+export class AltiumWorkerClient {
+    /** @returns {boolean} Whether a browser-compatible Worker is available. */
+    static isAvailable() {
+        try {
+            return typeof globalThis.Worker === 'function'
+        } catch {
+            return false
+        }
+    }
+
+    /**
+     * Parses one request through the shared worker protocol.
+     * @param {Record<string, any>} input Parser input.
+     * @param {Record<string, any>} options Common parser options.
+     * @returns {Promise<Record<string, any>>} Canonical document.
+     */
+    static async parse(input, options) {
+        return await AltiumWorkerClient.#client().parse(input, options)
+    }
+
+    /**
+     * Parses through the worker while distinguishing local construction
+     * unavailability from parser, protocol, and runtime failures.
+     * @param {Record<string, any>} input Parser input.
+     * @param {Record<string, any>} options Common parser options.
+     * @returns {Promise<{ ok: true, value: object } | { ok: false, error: unknown, unavailable: boolean }>} Attempt result.
+     */
+    static async parseAttempt(input, options) {
+        return await AltiumWorkerClient.#client().parseAttempt(input, options)
+    }
+
+    /**
+     * Loads one project through the shared worker protocol.
+     * @param {Record<string, any>[]} entries Project entries.
+     * @param {Record<string, any>} options Common loader options.
+     * @returns {Promise<Record<string, any>>} Canonical project.
+     */
+    static async loadProject(entries, options) {
+        return await AltiumWorkerClient.#client().loadProject(entries, options)
+    }
+
+    /**
+     * Loads through the worker while preserving operation failures.
+     * @param {Record<string, any>[]} entries Project entries.
+     * @param {Record<string, any>} options Common loader options.
+     * @returns {Promise<{ ok: true, value: object } | { ok: false, error: unknown, unavailable: boolean }>} Attempt result.
+     */
+    static async loadProjectAttempt(entries, options) {
+        return await AltiumWorkerClient.#client().loadProjectAttempt(
+            entries,
+            options
+        )
+    }
+
+    /** Disposes the current source worker client. */
+    static dispose() {
+        client?.dispose()
+        client = null
+    }
+
+    /**
+     * Returns the lazy source worker client.
+     * @returns {ParserWorkerClient} Shared-protocol client.
+     */
+    static #client() {
+        if (!client) {
+            client = new ParserWorkerClient({
+                createWorker: () => {
+                    const WorkerConstructor = globalThis.Worker
+                    return Reflect.construct(WorkerConstructor, [
+                        new URL(
+                            '../workers/parser.worker.mjs',
+                            import.meta.url
+                        ),
+                        { type: 'module' }
+                    ])
+                }
+            })
+        }
+        return client
+    }
+}
+
+Object.freeze(AltiumWorkerClient.prototype)
+Object.freeze(AltiumWorkerClient)