circuitjson-toolkit 1.0.2 → 1.0.10

package/README.md

@@ -33,10 +33,12 @@ package as a normal npm dependency.
 - Build lookup indexes by element type and stable CircuitJSON identifiers
 - Resolve source component and PCB component maps for viewer, QA, export, or
   reporting integrations
-- Preserve unknown element types instead of imposing renderer-specific
-  semantics
+- Reject unknown element types and invalid core element fields before consumers
+  render or query the model
 - Convert CircuitJSON millimeter dimensions and points into mils for render
   adapters that use PCB imperial units internally
+- Run dependency-free SPICE transient examples or normalize injected simulator
+  results into complete CircuitJSON simulation experiment element sets
 - Provide root and parser-focused ESM entrypoints
 - Run in browser and Node ESM environments
 - Run entirely with local input data; no network calls are made by the parser
@@ -106,6 +108,22 @@ const centerMil = CircuitJsonUnits.pointMmToMil(board.center)
 const widthMil = CircuitJsonUnits.mmToMil(board.width)
 ```
 
+Run a local SPICE transient example and receive CircuitJSON experiment output:
+
+```js
+import { SpiceSimulationService } from 'circuitjson-toolkit'
+
+const result = await SpiceSimulationService.simulate(`
+Vmain out 0 DC 3.3
+.PRINT TRAN V(out)
+.tran 1ms 2ms
+.END
+`)
+
+console.log(result.simulationCircuitJson)
+console.log(result.graphSummary)
+```
+
 Pass CircuitJSON to the 3D renderer as a separate step:
 
 ```js
@@ -137,6 +155,7 @@ This package owns reusable CircuitJSON utility behavior only:
 - validation and diagnostics for element-array inputs;
 - indexing and lookup maps for common CircuitJSON IDs;
 - small unit conversion helpers for downstream renderer adapters.
+- local SPICE transient graph helpers that return CircuitJSON elements.
 
 It does not include native Altium or KiCad parsing, schematic/PCB SVG
 rendering, Three.js rendering, browser UI controls, network fetching, or

package/docs/api.md

@@ -31,15 +31,21 @@ Parses UTF-8 CircuitJSON bytes from an `ArrayBuffer` or `Uint8Array`.
 
 ### `CircuitJsonDocument.isElement(value)`
 
-Returns true when `value` is an object with a non-empty string `type` field.
+Returns true when `value` is an object with a known non-empty string `type`
+field and passes element-specific validation.
 
 ### `CircuitJsonDocument.isModel(value)`
 
-Returns true when `value` is an array and every item is a CircuitJSON element.
+Returns true when `value` is an array and every item is a valid CircuitJSON
+element.
+
+### `CircuitJsonDocument.validateModel(value)`
+
+Returns validation error messages for a candidate CircuitJSON element array.
 
 ### `CircuitJsonDocument.assertModel(value)`
 
-Throws unless `value` is a CircuitJSON element array.
+Throws unless `value` is a valid CircuitJSON element array.
 
 ### `CircuitJsonDocument.attachMetadata(circuitJson, metadata?)`
 
@@ -74,6 +80,44 @@ the fallback, defaulting to `0`.
 
 Converts `{ x, y }` millimeter points to `{ x, y }` mil points.
 
+## SPICE Simulation
+
+### `SpiceCompatibilityPreprocessor.rewrite(spiceString)`
+
+Rewrites narrow, supported SPICE compatibility syntax before simulation. The
+current preprocessor handles resistor `TC=` pairs and boolean caret operators
+inside compatible `VALUE` expression blocks.
+
+### `SpiceSimulationService.simulate(spiceString)`
+
+Runs a local deterministic transient example and returns:
+
+- `simulationResultCircuitJson`: CircuitJSON transient voltage/current graph
+  elements.
+- `simulationCircuitJson`: a complete CircuitJSON element set containing the
+  `simulation_experiment` element with `experiment_type:
+'spice_transient_analysis'` followed by its graph elements.
+- `graphSummary`: a deterministic summary of graph ids, names, point counts,
+  time bounds, and min/max values for renderer tests and UI previews.
+- `diagnostics`: non-fatal simulation diagnostics.
+
+The service also accepts an injected engine through `new
+SpiceSimulationService({ engine })`. The engine must provide a `simulate`
+method that accepts a preprocessed SPICE netlist string and returns real-valued
+rows with `time`, `voltage`, and `current` data. Returned rows are resampled to
+the `.tran` time grid when transient step and stop parameters are available.
+Probe metadata comments may use `circuitjson_voltage_probe`,
+`simulation_voltage_probe`, `circuitjson_current_probe`, or
+`simulation_current_probe` markers to preserve graph ids, names, source nodes,
+and source trace/component references.
+External `.lib` and `.include` directives, PWL REPEAT source syntax, selected
+PSPICE compatibility patterns, and requested `.PRINT TRAN` vectors that cannot
+be matched to simulator output are reported as warnings for callers that need a
+full simulator path.
+Malformed probe metadata comments are also reported as warnings. Invalid JSON
+uses `spice_probe_metadata_invalid_json`; parsed comments missing required
+string fields use `spice_probe_metadata_invalid_shape`.
+
 ## Entrypoints
 
 The root entrypoint exports all utilities:
@@ -83,7 +127,9 @@ import {
     CircuitJsonDocument,
     CircuitJsonIndexer,
     CircuitJsonParser,
-    CircuitJsonUnits
+    CircuitJsonUnits,
+    SpiceCompatibilityPreprocessor,
+    SpiceSimulationService
 } from 'circuitjson-toolkit'
 ```
 

package/docs/model-format.md

@@ -11,6 +11,7 @@ The expected top-level value is an array:
     {
         "type": "pcb_board",
         "pcb_board_id": "board_1",
+        "center": { "x": 0, "y": 0 },
         "width": 50,
         "height": 30,
         "thickness": 1.6
@@ -18,9 +19,11 @@ The expected top-level value is an array:
 ]
 ```
 
-Every element must be an object with a non-empty string `type` field. The
-toolkit intentionally does not require every possible CircuitJSON field because
-hosts may use partial files, future element types, or renderer-specific subsets.
+Every element must be an object with a known non-empty string `type` field and
+the required fields for that element. The validator also checks the standard
+identifier convention for known element types, plus strict core fields for
+boards, source components, source ports, schematic components, PCB components,
+and SMT pads.
 
 ## Metadata
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.0.2",
+    "version": "1.0.10",
     "description": "Dependency-free CircuitJSON parsing, validation, indexing, and utility helpers",
     "keywords": [
         "circuitjson",

package/spec/library-scope.md

@@ -11,6 +11,9 @@ CircuitJSON element arrays.
 - Lookup indexes by element type and stable IDs
 - Source and PCB component lookup maps
 - Millimeter-to-mil conversion helpers
+- Local SPICE transient graph helpers that produce complete CircuitJSON
+  simulation experiment element sets
+- Deterministic SPICE graph summaries and non-fatal local syntax diagnostics
 - Small documentation and tests for toolkit behavior
 
 ## Excluded
@@ -18,7 +21,7 @@ CircuitJSON element arrays.
 - Three.js or browser DOM rendering
 - PCB 3D runtime behavior
 - ECAD source parser logic
-- Altium, KiCad, or other source-format compatibility adapters
+- Native ECAD source-format compatibility adapters
 - Network fetching or remote asset loading
 
 Renderer fixes belong in renderer packages. Source-format fixes belong in the

package/src/core/CircuitJsonBomBuilder.mjs

@@ -0,0 +1,146 @@
+/**
+ * Builds app-compatible BOM rows from source component elements.
+ */
+export class CircuitJsonBomBuilder {
+    /**
+     * Builds grouped BOM rows from a CircuitJSON element array.
+     * @param {object[]} circuitJson CircuitJSON model.
+     * @returns {object[]}
+     */
+    static build(circuitJson) {
+        const groups = new Map()
+        for (const component of circuitJson || []) {
+            if (component?.type !== 'source_component') continue
+            const designator = CircuitJsonBomBuilder.#designator(component)
+            if (!designator) continue
+
+            const key = CircuitJsonBomBuilder.#groupKey(component)
+            if (!groups.has(key)) {
+                groups.set(key, {
+                    designators: [],
+                    quantity: 0,
+                    value: CircuitJsonBomBuilder.#value(component),
+                    pattern: CircuitJsonBomBuilder.#pattern(component),
+                    source: CircuitJsonBomBuilder.#source(component),
+                    supplierPartNumber:
+                        CircuitJsonBomBuilder.#supplierPartNumber(component)
+                })
+            }
+            const row = groups.get(key)
+            row.designators.push(designator)
+            row.quantity = row.designators.length
+        }
+
+        return [...groups.values()].map((row) => ({
+            ...row,
+            designators: row.designators.sort(
+                CircuitJsonBomBuilder.#compareDesignators
+            )
+        }))
+    }
+
+    /**
+     * Resolves the display designator for one source component.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #designator(component) {
+        return String(
+            component.name ||
+                component.reference ||
+                component.designator ||
+                component.source_component_id ||
+                ''
+        ).trim()
+    }
+
+    /**
+     * Builds a stable grouping key from BOM-facing fields.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #groupKey(component) {
+        return [
+            CircuitJsonBomBuilder.#value(component),
+            CircuitJsonBomBuilder.#pattern(component),
+            CircuitJsonBomBuilder.#source(component),
+            CircuitJsonBomBuilder.#supplierPartNumber(component)
+        ].join('\u001f')
+    }
+
+    /**
+     * Resolves a BOM value from common source component fields.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #value(component) {
+        return String(
+            component.value ??
+                component.resistance ??
+                component.capacitance ??
+                component.inductance ??
+                component.frequency ??
+                component.voltage ??
+                ''
+        ).trim()
+    }
+
+    /**
+     * Resolves a footprint/package pattern label.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #pattern(component) {
+        return String(
+            component.footprint ??
+                component.package ??
+                component.package_name ??
+                component.ftype ??
+                ''
+        ).trim()
+    }
+
+    /**
+     * Resolves manufacturer or catalog source text.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #source(component) {
+        return String(
+            component.manufacturer_part_number ??
+                component.mpn ??
+                component.part_number ??
+                component.supplier_part_number ??
+                ''
+        ).trim()
+    }
+
+    /**
+     * Resolves a supplier part number.
+     * @param {object} component Source component.
+     * @returns {string}
+     */
+    static #supplierPartNumber(component) {
+        if (component.supplier_part_number) {
+            return String(component.supplier_part_number).trim()
+        }
+        const numbers = component.supplier_part_numbers
+        if (!numbers || typeof numbers !== 'object' || Array.isArray(numbers)) {
+            return ''
+        }
+        return String(Object.values(numbers).find(Boolean) || '').trim()
+    }
+
+    /**
+     * Compares designators using natural ordering.
+     * @param {string} left Left designator.
+     * @param {string} right Right designator.
+     * @returns {number}
+     */
+    static #compareDesignators(left, right) {
+        return String(left).localeCompare(String(right), undefined, {
+            numeric: true,
+            sensitivity: 'base'
+        })
+    }
+}

package/src/core/CircuitJsonDocument.mjs

@@ -1,3 +1,5 @@
+import { CircuitJsonElementValidator } from './CircuitJsonElementValidator.mjs'
+
 /**
  * Validates serialized CircuitJSON element arrays.
  */
@@ -8,12 +10,7 @@ export class CircuitJsonDocument {
      * @returns {boolean}
      */
     static isElement(value) {
-        return (
-            Boolean(value) &&
-            typeof value === 'object' &&
-            typeof value.type === 'string' &&
-            value.type.trim().length > 0
-        )
+        return CircuitJsonElementValidator.validateElement(value).length === 0
     }
 
     /**
@@ -22,10 +19,16 @@ export class CircuitJsonDocument {
      * @returns {boolean}
      */
     static isModel(value) {
-        return (
-            Array.isArray(value) &&
-            value.every((element) => CircuitJsonDocument.isElement(element))
-        )
+        return CircuitJsonElementValidator.validateModel(value).length === 0
+    }
+
+    /**
+     * Returns validation errors for a candidate CircuitJSON element array.
+     * @param {unknown} value Candidate model.
+     * @returns {string[]}
+     */
+    static validateModel(value) {
+        return CircuitJsonElementValidator.validateModel(value)
     }
 
     /**
@@ -34,8 +37,9 @@ export class CircuitJsonDocument {
      * @returns {void}
      */
     static assertModel(value) {
-        if (!CircuitJsonDocument.isModel(value)) {
-            throw new TypeError('Expected a CircuitJSON element array.')
+        const errors = CircuitJsonDocument.validateModel(value)
+        if (errors.length) {
+            throw new TypeError(errors[0])
         }
     }
 
@@ -43,7 +47,7 @@ export class CircuitJsonDocument {
      * Attaches non-serialized metadata to a CircuitJSON array.
      * @template {object[]} T
      * @param {T} circuitJson CircuitJSON model.
-     * @param {{ fileName?: string, fileType?: string, kind?: string }} [metadata]
+     * @param {{ fileName?: string, fileType?: string, kind?: string, diagnostics?: object[], bom?: object[], supportMatrix?: object, manufacturing?: object }} [metadata]
      * @returns {T}
      */
     static attachMetadata(circuitJson, metadata = {}) {
@@ -72,6 +76,35 @@ export class CircuitJsonDocument {
                 enumerable: true,
                 value: 'circuitjson',
                 writable: true
+            },
+            diagnostics: {
+                configurable: true,
+                enumerable: true,
+                value: Array.isArray(metadata.diagnostics)
+                    ? metadata.diagnostics
+                    : [],
+                writable: true
+            },
+            bom: {
+                configurable: true,
+                enumerable: true,
+                value: Array.isArray(metadata.bom) ? metadata.bom : [],
+                writable: true
+            },
+            supportMatrix: {
+                configurable: true,
+                enumerable: true,
+                value: metadata.supportMatrix || null,
+                writable: true
+            },
+            manufacturing: {
+                configurable: true,
+                enumerable: true,
+                value: metadata.manufacturing || {
+                    pickAndPlaceRows: [],
+                    routingDsn: ''
+                },
+                writable: true
             }
         })