circuitjson-toolkit 1.0.16 → 1.1.0

package/src/extensions.mjs

@@ -0,0 +1,37 @@
+export { CircuitJsonBomBuilder } from './core/CircuitJsonBomBuilder.mjs'
+export { CircuitJsonElementValidator } from './core/CircuitJsonElementValidator.mjs'
+export { CircuitJsonManufacturingBuilder } from './core/CircuitJsonManufacturingBuilder.mjs'
+export { CircuitJsonManufacturingDownloadBuilder } from './core/CircuitJsonManufacturingDownloadBuilder.mjs'
+export { CircuitJsonParser } from './core/CircuitJsonParser.mjs'
+export { CircuitJsonPcbClearanceDiagnostics } from './core/CircuitJsonPcbClearanceDiagnostics.mjs'
+export { CircuitJsonPcbCopperGeometry } from './core/CircuitJsonPcbCopperGeometry.mjs'
+export { CircuitJsonPcbDrawingStyle } from './core/CircuitJsonPcbDrawingStyle.mjs'
+export { CircuitJsonPcbHolePrimitiveModel } from './core/CircuitJsonPcbHolePrimitiveModel.mjs'
+export { CircuitJsonPcbNetMetadata } from './core/CircuitJsonPcbNetMetadata.mjs'
+export { CircuitJsonPcbPadPrimitiveModel } from './core/CircuitJsonPcbPadPrimitiveModel.mjs'
+export { CircuitJsonPcbPrimitiveArtwork } from './core/CircuitJsonPcbPrimitiveArtwork.mjs'
+export { CircuitJsonPcbPrimitiveBuilder } from './core/CircuitJsonPcbPrimitiveBuilder.mjs'
+export { CircuitJsonPcbPrimitiveFields } from './core/CircuitJsonPcbPrimitiveFields.mjs'
+export { CircuitJsonPcbPrimitiveGeometry } from './core/CircuitJsonPcbPrimitiveGeometry.mjs'
+export { CircuitJsonPcbPrimitiveGroups } from './core/CircuitJsonPcbPrimitiveGroups.mjs'
+export { CircuitJsonPcbPrimitiveIndex } from './core/CircuitJsonPcbPrimitiveIndex.mjs'
+export { CircuitJsonPcbPrimitiveOverlays } from './core/CircuitJsonPcbPrimitiveOverlays.mjs'
+export { CircuitJsonPcbTraceLengthModel } from './core/CircuitJsonPcbTraceLengthModel.mjs'
+export { CircuitJsonPcbZonePrimitiveBuilder } from './core/CircuitJsonPcbZonePrimitiveBuilder.mjs'
+export { CircuitJsonSourceMetadata } from './core/CircuitJsonSourceMetadata.mjs'
+export { CircuitJsonSupportMatrixBuilder } from './core/CircuitJsonSupportMatrixBuilder.mjs'
+export { PcbBoundsSelectionModel } from './core/PcbBoundsSelectionModel.mjs'
+export { PcbCandidateSelectionModel } from './core/PcbCandidateSelectionModel.mjs'
+export { PcbDiagnosticFocusModel } from './core/PcbDiagnosticFocusModel.mjs'
+export { PcbInteractionPrimitiveModel } from './core/PcbInteractionPrimitiveModel.mjs'
+export { SelectedPartCircuitJsonExportAdapter } from './core/SelectedPartCircuitJsonExportAdapter.mjs'
+export { SpiceCompatibilityPreprocessor } from './core/spice/SpiceCompatibilityPreprocessor.mjs'
+export { SpiceSimulationService } from './core/spice/SpiceSimulationService.mjs'
+export { CircuitJsonPcbPrimitiveAttributeRenderer } from './ui/CircuitJsonPcbPrimitiveAttributeRenderer.mjs'
+export { CircuitJsonPcbSvgRenderer } from './ui/CircuitJsonPcbSvgRenderer.mjs'
+export { CircuitJsonPcbViaSvgRenderer } from './ui/CircuitJsonPcbViaSvgRenderer.mjs'
+export { CircuitJsonSchematicSvgArcPath } from './ui/CircuitJsonSchematicSvgArcPath.mjs'
+export { CircuitJsonSchematicSvgPortMetadata } from './ui/CircuitJsonSchematicSvgPortMetadata.mjs'
+export { CircuitJsonSchematicSvgPrimitiveAttributes } from './ui/CircuitJsonSchematicSvgPrimitiveAttributes.mjs'
+export { CircuitJsonSchematicSvgRenderer } from './ui/CircuitJsonSchematicSvgRenderer.mjs'
+export { CircuitJsonSchematicTableSvgRenderer } from './ui/CircuitJsonSchematicTableSvgRenderer.mjs'

package/src/index.mjs

@@ -1,12 +1,17 @@
 export { CircuitJsonDocument } from './core/CircuitJsonDocument.mjs'
-export { CircuitJsonBomBuilder } from './core/CircuitJsonBomBuilder.mjs'
-export { CircuitJsonElementValidator } from './core/CircuitJsonElementValidator.mjs'
 export { CircuitJsonIndexer } from './core/CircuitJsonIndexer.mjs'
-export { CircuitJsonManufacturingBuilder } from './core/CircuitJsonManufacturingBuilder.mjs'
-export { CircuitJsonParser } from './core/CircuitJsonParser.mjs'
-export { CircuitJsonSourceMetadata } from './core/CircuitJsonSourceMetadata.mjs'
-export { CircuitJsonSupportMatrixBuilder } from './core/CircuitJsonSupportMatrixBuilder.mjs'
 export { CircuitJsonUnits } from './core/CircuitJsonUnits.mjs'
-export { SpiceCompatibilityPreprocessor } from './core/spice/SpiceCompatibilityPreprocessor.mjs'
-export { SpiceSimulationService } from './core/spice/SpiceSimulationService.mjs'
-export * from './renderers.mjs'
+export { Parser } from './core/Parser.mjs'
+export { ProjectLoader } from './core/ProjectLoader.mjs'
+export { CircuitJsonDocumentContext } from './core/context/CircuitJsonDocumentContext.mjs'
+export { PcbInteractionIndex } from './core/PcbInteractionIndex.mjs'
+export { ManufacturingService } from './core/ManufacturingService.mjs'
+export { SimulationService } from './core/SimulationService.mjs'
+export { ToolkitCapabilities } from './core/ToolkitCapabilities.mjs'
+export { ToolkitError } from './core/contracts/ToolkitError.mjs'
+export { QueryService } from './core/query/QueryService.mjs'
+export { PcbScene3dBuilder } from './core/scene3d/PcbScene3dBuilder.mjs'
+export { PcbScene3dPreparator } from './core/scene3d/PcbScene3dPreparator.mjs'
+export { BomTableRenderer } from './ui/BomTableRenderer.mjs'
+export { PcbSvgRenderer } from './ui/PcbSvgRenderer.mjs'
+export { SchematicSvgRenderer } from './ui/SchematicSvgRenderer.mjs'

package/src/interaction.mjs

@@ -0,0 +1,2 @@
+export { PcbInteractionIndex } from './core/PcbInteractionIndex.mjs'
+export { PcbSpatialIndex } from './core/context/PcbSpatialIndex.mjs'

package/src/manufacturing.mjs

@@ -0,0 +1 @@
+export { ManufacturingService } from './core/ManufacturingService.mjs'

package/src/parser.mjs

@@ -1,2 +1,12 @@
-export { CircuitJsonDocument } from './core/CircuitJsonDocument.mjs'
-export { CircuitJsonParser } from './core/CircuitJsonParser.mjs'
+export { Parser } from './core/Parser.mjs'
+export { CircuitJsonDocumentContext } from './core/context/CircuitJsonDocumentContext.mjs'
+export { DocumentResult } from './core/contracts/DocumentResult.mjs'
+export { ToolkitAsset } from './core/contracts/ToolkitAsset.mjs'
+export { ToolkitDiagnostic } from './core/contracts/ToolkitDiagnostic.mjs'
+export { ToolkitError } from './core/contracts/ToolkitError.mjs'
+export { ToolkitProgress } from './core/contracts/ToolkitProgress.mjs'
+export { ParserWorkerClient } from './core/worker/ParserWorkerClient.mjs'
+export {
+    TOOLKIT_WORKER_PROTOCOL,
+    ToolkitWorkerProtocol
+} from './core/worker/ToolkitWorkerProtocol.mjs'

package/src/project.mjs

@@ -0,0 +1,5 @@
+export { ArchiveEntryPath } from './core/ArchiveEntryPath.mjs'
+export { ArchiveLimits } from './core/ArchiveLimits.mjs'
+export { ProjectLoader } from './core/ProjectLoader.mjs'
+export { ZipArchiveInspector } from './core/ZipArchiveInspector.mjs'
+export { ProjectResult } from './core/contracts/ProjectResult.mjs'

package/src/query.mjs

@@ -0,0 +1 @@
+export { QueryService } from './core/query/QueryService.mjs'

package/src/renderers.mjs

@@ -1,29 +1,3 @@
-export { CircuitJsonManufacturingDownloadBuilder } from './core/CircuitJsonManufacturingDownloadBuilder.mjs'
-export { CircuitJsonPcbClearanceDiagnostics } from './core/CircuitJsonPcbClearanceDiagnostics.mjs'
-export { CircuitJsonPcbCopperGeometry } from './core/CircuitJsonPcbCopperGeometry.mjs'
-export { CircuitJsonPcbDrawingStyle } from './core/CircuitJsonPcbDrawingStyle.mjs'
-export { CircuitJsonPcbHolePrimitiveModel } from './core/CircuitJsonPcbHolePrimitiveModel.mjs'
-export { CircuitJsonPcbNetMetadata } from './core/CircuitJsonPcbNetMetadata.mjs'
-export { CircuitJsonPcbPadPrimitiveModel } from './core/CircuitJsonPcbPadPrimitiveModel.mjs'
-export { CircuitJsonPcbPrimitiveArtwork } from './core/CircuitJsonPcbPrimitiveArtwork.mjs'
-export { CircuitJsonPcbPrimitiveBuilder } from './core/CircuitJsonPcbPrimitiveBuilder.mjs'
-export { CircuitJsonPcbPrimitiveFields } from './core/CircuitJsonPcbPrimitiveFields.mjs'
-export { CircuitJsonPcbPrimitiveGeometry } from './core/CircuitJsonPcbPrimitiveGeometry.mjs'
-export { CircuitJsonPcbPrimitiveGroups } from './core/CircuitJsonPcbPrimitiveGroups.mjs'
-export { CircuitJsonPcbPrimitiveIndex } from './core/CircuitJsonPcbPrimitiveIndex.mjs'
-export { CircuitJsonPcbPrimitiveOverlays } from './core/CircuitJsonPcbPrimitiveOverlays.mjs'
-export { CircuitJsonPcbTraceLengthModel } from './core/CircuitJsonPcbTraceLengthModel.mjs'
-export { CircuitJsonPcbZonePrimitiveBuilder } from './core/CircuitJsonPcbZonePrimitiveBuilder.mjs'
-export { PcbBoundsSelectionModel } from './core/PcbBoundsSelectionModel.mjs'
-export { PcbCandidateSelectionModel } from './core/PcbCandidateSelectionModel.mjs'
-export { PcbDiagnosticFocusModel } from './core/PcbDiagnosticFocusModel.mjs'
-export { PcbInteractionPrimitiveModel } from './core/PcbInteractionPrimitiveModel.mjs'
-export { SelectedPartCircuitJsonExportAdapter } from './core/SelectedPartCircuitJsonExportAdapter.mjs'
-export { CircuitJsonPcbPrimitiveAttributeRenderer } from './ui/CircuitJsonPcbPrimitiveAttributeRenderer.mjs'
-export { CircuitJsonPcbSvgRenderer } from './ui/CircuitJsonPcbSvgRenderer.mjs'
-export { CircuitJsonPcbViaSvgRenderer } from './ui/CircuitJsonPcbViaSvgRenderer.mjs'
-export { CircuitJsonSchematicSvgArcPath } from './ui/CircuitJsonSchematicSvgArcPath.mjs'
-export { CircuitJsonSchematicSvgPortMetadata } from './ui/CircuitJsonSchematicSvgPortMetadata.mjs'
-export { CircuitJsonSchematicSvgPrimitiveAttributes } from './ui/CircuitJsonSchematicSvgPrimitiveAttributes.mjs'
-export { CircuitJsonSchematicSvgRenderer } from './ui/CircuitJsonSchematicSvgRenderer.mjs'
-export { CircuitJsonSchematicTableSvgRenderer } from './ui/CircuitJsonSchematicTableSvgRenderer.mjs'
+export { BomTableRenderer } from './ui/BomTableRenderer.mjs'
+export { PcbSvgRenderer } from './ui/PcbSvgRenderer.mjs'
+export { SchematicSvgRenderer } from './ui/SchematicSvgRenderer.mjs'

package/src/scene3d.mjs

@@ -0,0 +1,3 @@
+export { PcbScene3dBuilder } from './core/scene3d/PcbScene3dBuilder.mjs'
+export { PcbScene3dPreparator } from './core/scene3d/PcbScene3dPreparator.mjs'
+export { SceneAssetResolver } from './core/scene3d/SceneAssetResolver.mjs'

package/src/simulation.mjs

@@ -0,0 +1 @@
+export { SimulationService } from './core/SimulationService.mjs'

package/src/styles/renderers.css

@@ -0,0 +1,24 @@
+.pcb-svg,
+.schematic-svg {
+    display: block;
+    width: 100%;
+    max-width: 100%;
+    height: auto;
+}
+
+.pcb-svg text,
+.schematic-svg text {
+    font-family: ui-sans-serif, system-ui, sans-serif;
+}
+
+.bom-table {
+    width: 100%;
+    border-collapse: collapse;
+}
+
+.bom-table th,
+.bom-table td {
+    padding: 0.35rem 0.5rem;
+    border: 1px solid currentColor;
+    text-align: left;
+}

package/src/testing/ToolkitContractFixtures.mjs

@@ -0,0 +1,124 @@
+const CANONICAL_CLASS_NAMES = Object.freeze([
+    'Parser',
+    'ProjectLoader',
+    'CircuitJsonDocumentContext',
+    'PcbSvgRenderer',
+    'SchematicSvgRenderer',
+    'BomTableRenderer',
+    'PcbInteractionIndex',
+    'QueryService',
+    'ManufacturingService',
+    'SimulationService',
+    'PcbScene3dBuilder',
+    'PcbScene3dPreparator',
+    'ToolkitCapabilities',
+    'ToolkitError'
+])
+
+/**
+ * Supplies small source-independent and source-format contract fixtures.
+ */
+export class ToolkitContractFixtures {
+    /** @returns {string[]} Exact canonical root class names. */
+    static get canonicalClassNames() {
+        return [...CANONICAL_CLASS_NAMES]
+    }
+
+    /** @returns {object[]} Minimal valid CircuitJSON document. */
+    static circuitJsonDocument() {
+        return []
+    }
+
+    /** @returns {Record<string, any>} CircuitJSON contract fixture. */
+    static circuitJson() {
+        return ToolkitContractFixtures.#fixture(
+            'circuitjson',
+            'contract.json',
+            JSON.stringify(ToolkitContractFixtures.circuitJsonDocument())
+        )
+    }
+
+    /** @returns {Record<string, any>} Gerber contract fixture. */
+    static gerber() {
+        const source = [
+            'G04 ECAD toolkit contract fixture*',
+            '%FSLAX24Y24*%',
+            '%MOMM*%',
+            '%ADD10C,1.000*%',
+            'D10*',
+            'X000000Y000000D03*',
+            'M02*'
+        ].join('\n')
+        return ToolkitContractFixtures.#fixture(
+            'gerber',
+            'contract.gbr',
+            source
+        )
+    }
+
+    /** @returns {Record<string, any>} Altium text-project fixture. */
+    static altium() {
+        const source = [
+            '[Design]',
+            'Version=1.0',
+            'CurrentVariant=',
+            '',
+            '[Document1]',
+            'DocumentPath=contract.PcbDoc',
+            'DocumentUniqueId=CONTRACT'
+        ].join('\r\n')
+        return ToolkitContractFixtures.#fixture(
+            'altium',
+            'contract.PrjPcb',
+            source
+        )
+    }
+
+    /** @returns {Record<string, any>} KiCad PCB contract fixture. */
+    static kicad() {
+        const source = [
+            '(kicad_pcb',
+            '  (version 20240108)',
+            '  (generator pcbnew)',
+            '  (general (thickness 1.6))',
+            '  (paper "A4")',
+            '  (layers',
+            '    (0 "F.Cu" signal)',
+            '    (31 "B.Cu" signal)',
+            '    (44 "Edge.Cuts" user)',
+            '  )',
+            '  (setup (pad_to_mask_clearance 0))',
+            ')'
+        ].join('\n')
+        return ToolkitContractFixtures.#fixture(
+            'kicad',
+            'contract.kicad_pcb',
+            source
+        )
+    }
+
+    /**
+     * Builds one complete generic fixture record.
+     * @param {string} format Source format.
+     * @param {string} fileName Source file name.
+     * @param {string} data Source data.
+     * @returns {Record<string, any>} Contract fixture.
+     */
+    static #fixture(format, fileName, data) {
+        return {
+            schema: 'ecad-toolkit.contract-fixture.v1',
+            format,
+            parserInput: { fileName, data },
+            unsupportedInput: {
+                fileName: `unsupported-${format}.txt`,
+                data: 'not an ECAD document'
+            },
+            projectEntries: [{ name: fileName, data }],
+            renderOptions: {
+                pcb: { side: 'top', fidelity: 'canonical' },
+                pcbBottom: { side: 'bottom', fidelity: 'canonical' },
+                schematic: { fidelity: 'canonical' }
+            }
+        }
+    }
+}

package/src/testing/ToolkitLoopbackWorker.mjs

@@ -0,0 +1,174 @@
+import { ToolkitWorkerProtocol } from '../core/worker/ToolkitWorkerProtocol.mjs'
+
+/**
+ * Provides a real protocol loopback for packed cross-toolkit conformance tests.
+ */
+export class ToolkitLoopbackWorker {
+    #clientListeners = new Map()
+    #installation
+    #observations
+    #serverListeners = new Map()
+    #terminated = false
+
+    /**
+     * Creates one worker-like protocol endpoint for a canonical toolkit.
+     * @param {Record<string, any>} toolkit Toolkit namespace.
+     * @param {{ parse: number, loadProject: number }} observations Request counts.
+     */
+    constructor(toolkit, observations) {
+        this.#observations = observations
+        const scope = {
+            addEventListener: (type, listener) =>
+                this.#add(this.#serverListeners, type, listener),
+            removeEventListener: (type, listener) =>
+                this.#remove(this.#serverListeners, type, listener),
+            postMessage: (message, transfer = []) =>
+                this.#postToClient(message, transfer),
+            reportError: (error) => this.#reportError(error)
+        }
+        this.#installation = ToolkitWorkerProtocol.install(scope, {
+            parse: async (payload, runtime) => {
+                observations.parse += 1
+                return await toolkit.Parser.parseAsync(payload.input, {
+                    ...(payload.options || {}),
+                    worker: false,
+                    signal: runtime.signal,
+                    onProgress: runtime.onProgress
+                })
+            },
+            loadProject: async (payload, runtime) => {
+                observations.loadProject += 1
+                return await toolkit.ProjectLoader.loadAsync(payload.entries, {
+                    ...(payload.options || {}),
+                    worker: false,
+                    signal: runtime.signal,
+                    onProgress: runtime.onProgress
+                })
+            }
+        })
+    }
+
+    /**
+     * Creates a Worker constructor bound to one toolkit namespace.
+     * @param {Record<string, any>} toolkit Toolkit namespace.
+     * @param {{ parse: number, loadProject: number }} observations Request counts.
+     * @returns {typeof ToolkitLoopbackWorker} Bound worker constructor.
+     */
+    static constructorFor(toolkit, observations) {
+        return class BoundToolkitLoopbackWorker extends ToolkitLoopbackWorker {
+            /** Creates a worker bound to the enclosing toolkit. */
+            constructor() {
+                super(toolkit, observations)
+            }
+        }
+    }
+
+    /**
+     * Adds one client-side worker event listener.
+     * @param {string} type Event type.
+     * @param {Function} listener Event listener.
+     * @returns {void}
+     */
+    addEventListener(type, listener) {
+        this.#add(this.#clientListeners, type, listener)
+    }
+
+    /**
+     * Removes one client-side worker event listener.
+     * @param {string} type Event type.
+     * @param {Function} listener Event listener.
+     * @returns {void}
+     */
+    removeEventListener(type, listener) {
+        this.#remove(this.#clientListeners, type, listener)
+    }
+
+    /**
+     * Posts one client request through a clone boundary to the protocol server.
+     * @param {unknown} message Protocol message.
+     * @param {Transferable[]} [transfer] Explicit transfer list.
+     * @returns {void}
+     */
+    postMessage(message, transfer = []) {
+        if (this.#terminated) throw new Error('Loopback worker is terminated.')
+        const cloned = structuredClone(message, { transfer })
+        queueMicrotask(() =>
+            this.#emit(this.#serverListeners, 'message', cloned)
+        )
+    }
+
+    /** Stops the loopback worker and active protocol operations. */
+    terminate() {
+        if (this.#terminated) return
+        this.#terminated = true
+        this.#installation.dispose()
+        this.#clientListeners.clear()
+        this.#serverListeners.clear()
+    }
+
+    /**
+     * Adds one listener to an event registry.
+     * @param {Map<string, Set<Function>>} registry Event registry.
+     * @param {string} type Event type.
+     * @param {Function} listener Event listener.
+     * @returns {void}
+     */
+    #add(registry, type, listener) {
+        if (typeof listener !== 'function') return
+        if (!registry.has(type)) registry.set(type, new Set())
+        registry.get(type).add(listener)
+    }
+
+    /**
+     * Removes one listener from an event registry.
+     * @param {Map<string, Set<Function>>} registry Event registry.
+     * @param {string} type Event type.
+     * @param {Function} listener Event listener.
+     * @returns {void}
+     */
+    #remove(registry, type, listener) {
+        registry.get(type)?.delete(listener)
+    }
+
+    /**
+     * Emits one plain worker-like event.
+     * @param {Map<string, Set<Function>>} registry Event registry.
+     * @param {string} type Event type.
+     * @param {unknown} data Event data.
+     * @returns {void}
+     */
+    #emit(registry, type, data) {
+        if (this.#terminated) return
+        for (const listener of registry.get(type) || []) {
+            listener({ data })
+        }
+    }
+
+    /**
+     * Posts one protocol response through a clone boundary to the client.
+     * @param {unknown} message Protocol response.
+     * @param {Transferable[]} transfer Transfer list.
+     * @returns {void}
+     */
+    #postToClient(message, transfer) {
+        if (this.#terminated) return
+        const cloned = structuredClone(message, { transfer })
+        queueMicrotask(() =>
+            this.#emit(this.#clientListeners, 'message', cloned)
+        )
+    }
+
+    /**
+     * Emits one worker error event to the client.
+     * @param {unknown} error Worker failure.
+     * @returns {void}
+     */
+    #reportError(error) {
+        if (this.#terminated) return
+        queueMicrotask(() => {
+            for (const listener of this.#clientListeners.get('error') || []) {
+                listener({ error, message: String(error?.message || error) })
+            }
+        })
+    }
+}