circuitjson-toolkit 1.0.10 → 1.0.16

package/AGENTS.md

@@ -34,9 +34,11 @@
 ## Library Scope
 
 - Include CircuitJSON element-array validation, parsing, indexing, unit helpers,
-  and small summary helpers.
-- Do not include renderer code, Three.js code, ECAD parser logic, UI wiring, or
-  source-format-specific compatibility adapters.
+  deterministic renderer-neutral primitive helpers, deterministic SVG renderers,
+  and small summary/export helpers.
+- Do not include Three.js code, ECAD parser logic, UI wiring, host app state,
+  DOM event orchestration, download UI, or source-format-specific compatibility
+  adapters.
 
 ## Testing Guidelines
 

package/docs/model-format.md

@@ -63,6 +63,21 @@ Indexed element IDs are stored with a type prefix, such as
 `pcb_board:board_1`, so different element classes can reuse local IDs without
 colliding.
 
+PCB courtyard artwork rows use the normal `type_id` identifier convention. The
+validator accepts generic `pcb_courtyard` rows plus shape-specific variants such
+as `pcb_courtyard_rect`, `pcb_courtyard_circle`, `pcb_courtyard_outline`,
+`pcb_courtyard_path`, and `pcb_courtyard_line`.
+
+## Group Indexing
+
+`CircuitJsonIndexer` builds `groupsById` and `elementsByGroupId` from direct
+group fields such as `source_group_id`, `pcb_group_id`,
+`schematic_group_id`, `group_id`, and `group_ids`. It also treats member-style
+fields such as `member_source_group_ids`, `member_pcb_group_ids`,
+`member_schematic_group_ids`, and `member_group_ids` as group memberships, so
+source nets and other non-group elements can participate in group indexes
+without duplicating direct group fields.
+
 ## Units
 
 CircuitJSON PCB coordinates and dimensions are millimeter-based. The toolkit

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.0.10",
+    "version": "1.0.16",
     "description": "Dependency-free CircuitJSON parsing, validation, indexing, and utility helpers",
     "keywords": [
         "circuitjson",
@@ -28,7 +28,8 @@
     "main": "./src/index.mjs",
     "exports": {
         ".": "./src/index.mjs",
-        "./parser": "./src/parser.mjs"
+        "./parser": "./src/parser.mjs",
+        "./renderers": "./src/renderers.mjs"
     },
     "files": [
         "src",

package/src/core/CircuitJsonBomBuilder.mjs

@@ -1,3 +1,5 @@
+import { CircuitJsonSourceMetadata } from './CircuitJsonSourceMetadata.mjs'
+
 /**
  * Builds app-compatible BOM rows from source component elements.
  */
@@ -14,16 +16,24 @@ export class CircuitJsonBomBuilder {
             const designator = CircuitJsonBomBuilder.#designator(component)
             if (!designator) continue
 
-            const key = CircuitJsonBomBuilder.#groupKey(component)
+            const metadata =
+                CircuitJsonSourceMetadata.normalizeSourceComponent(component)
+            const key = CircuitJsonBomBuilder.#groupKey(component, metadata)
             if (!groups.has(key)) {
                 groups.set(key, {
                     designators: [],
                     quantity: 0,
                     value: CircuitJsonBomBuilder.#value(component),
-                    pattern: CircuitJsonBomBuilder.#pattern(component),
+                    pattern: CircuitJsonBomBuilder.#pattern(
+                        component,
+                        metadata
+                    ),
                     source: CircuitJsonBomBuilder.#source(component),
-                    supplierPartNumber:
-                        CircuitJsonBomBuilder.#supplierPartNumber(component)
+                    supplierPartNumber: metadata.supplierPartNumber,
+                    supplierPartNumbers: metadata.supplierPartNumbers,
+                    sourceFtype: metadata.sourceFtype,
+                    componentType: metadata.componentType,
+                    componentIcon: metadata.componentIcon
                 })
             }
             const row = groups.get(key)
@@ -57,14 +67,16 @@ export class CircuitJsonBomBuilder {
     /**
      * Builds a stable grouping key from BOM-facing fields.
      * @param {object} component Source component.
+     * @param {object} metadata Normalized source metadata.
      * @returns {string}
      */
-    static #groupKey(component) {
+    static #groupKey(component, metadata) {
         return [
             CircuitJsonBomBuilder.#value(component),
-            CircuitJsonBomBuilder.#pattern(component),
+            CircuitJsonBomBuilder.#pattern(component, metadata),
             CircuitJsonBomBuilder.#source(component),
-            CircuitJsonBomBuilder.#supplierPartNumber(component)
+            metadata.supplierPartNumber,
+            metadata.sourceFtype
         ].join('\u001f')
     }
 
@@ -88,14 +100,15 @@ export class CircuitJsonBomBuilder {
     /**
      * Resolves a footprint/package pattern label.
      * @param {object} component Source component.
+     * @param {object} metadata Normalized source metadata.
      * @returns {string}
      */
-    static #pattern(component) {
+    static #pattern(component, metadata) {
         return String(
             component.footprint ??
                 component.package ??
                 component.package_name ??
-                component.ftype ??
+                metadata.sourceFtype ??
                 ''
         ).trim()
     }
@@ -115,22 +128,6 @@ export class CircuitJsonBomBuilder {
         ).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.

package/src/core/CircuitJsonElementValidator.mjs

@@ -16,7 +16,9 @@ const KNOWN_ELEMENT_TYPES = new Set([
     'pcb_copper_text',
     'pcb_courtyard',
     'pcb_courtyard_circle',
+    'pcb_courtyard_line',
     'pcb_courtyard_outline',
+    'pcb_courtyard_path',
     'pcb_courtyard_overlap_error',
     'pcb_courtyard_pill',
     'pcb_courtyard_polygon',
@@ -111,7 +113,6 @@ const KNOWN_ELEMENT_TYPES = new Set([
     'source_failed_to_create_component_error',
     'source_group',
     'source_i2c_misconfigured_error',
-    'source_interconnect',
     'source_invalid_component_property_error',
     'source_manually_placed_via',
     'source_missing_manufacturer_part_number_warning',
@@ -143,6 +144,7 @@ const ID_FIELD_EXCEPTIONS = new Set([
 ])
 
 const SOURCE_COMPONENT_FTYPES = new Set([
+    'interconnect',
     'simple_ammeter',
     'simple_battery',
     'simple_capacitor',
@@ -172,16 +174,9 @@ const SOURCE_COMPONENT_FTYPES = new Set([
     'simple_voltage_source'
 ])
 
-const LAYERS = new Set([
-    'top',
-    'bottom',
-    'inner1',
-    'inner2',
-    'inner3',
-    'inner4',
-    'inner5',
-    'inner6'
-])
+const LAYERS = new Set(
+    'top bottom inner1 inner2 inner3 inner4 inner5 inner6'.split(' ')
+)
 
 const SMT_PAD_SHAPES = new Set([
     'circle',
@@ -189,9 +184,88 @@ const SMT_PAD_SHAPES = new Set([
     'rotated_rect',
     'rotated_pill',
     'pill',
-    'polygon'
+    'polygon',
+    'rounded_rect'
+])
+
+const PCB_HOLE_SHAPES = new Set([
+    'circle',
+    'circle_or_square',
+    'oval',
+    'pill',
+    'rect',
+    'rotated_pill',
+    'round'
 ])
 
+const PCB_PLATED_HOLE_SHAPES = new Set([
+    'circle',
+    'circular_hole_with_rect_pad',
+    'hole_with_polygon_pad',
+    'oval',
+    'pill',
+    'pill_hole_with_rect_pad',
+    'rotated_pill_hole_with_rect_pad'
+])
+
+const PCB_PLATED_HOLE_HOLE_SHAPES = new Set([
+    'circle',
+    'oval',
+    'pill',
+    'rotated_pill'
+])
+
+const PCB_SOLDER_PASTE_SHAPES = new Set([
+    'circle',
+    'oval',
+    'pill',
+    'rect',
+    'rotated_rect'
+])
+
+const PCB_BOARD_SHAPES = new Set(['polygon', 'rect'])
+
+const PCB_CUTOUT_SHAPES = new Set(['circle', 'path', 'polygon', 'rect'])
+
+const PCB_COPPER_POUR_SHAPES = new Set(['brep', 'polygon', 'rect'])
+
+const SIMULATION_SOURCE_KINDS = new Set(['ac', 'dc'])
+
+const SIMULATION_WAVE_SHAPES = new Set(
+    'sawtooth sinewave square triangle'.split(' ')
+)
+
+const SIMULATION_EXPERIMENT_METHODS = new Set(['gear', 'trap'])
+
+const VARIANT_SETS = {
+    sourceComponentFtypes: SOURCE_COMPONENT_FTYPES,
+    pcbBoardShapes: PCB_BOARD_SHAPES,
+    pcbSmtPadShapes: SMT_PAD_SHAPES,
+    pcbHoleShapes: PCB_HOLE_SHAPES,
+    pcbPlatedHoleShapes: PCB_PLATED_HOLE_SHAPES,
+    pcbPlatedHoleHoleShapes: PCB_PLATED_HOLE_HOLE_SHAPES,
+    pcbSolderPasteShapes: PCB_SOLDER_PASTE_SHAPES,
+    pcbCutoutShapes: PCB_CUTOUT_SHAPES,
+    pcbCopperPourShapes: PCB_COPPER_POUR_SHAPES,
+    simulationSourceKinds: SIMULATION_SOURCE_KINDS,
+    simulationWaveShapes: SIMULATION_WAVE_SHAPES,
+    simulationExperimentMethods: SIMULATION_EXPERIMENT_METHODS
+}
+
+const SORTED_VARIANT_SET_NAMES = Object.keys(VARIANT_SETS).sort()
+
+/**
+ * @typedef {{ set: string, value: string }} CircuitJsonVariantDiff
+ */
+
+/**
+ * @typedef {{ elementTypes: string[], idFieldExceptions: string[], variantSets: Record<string, string[]> }} CircuitJsonSchemaSnapshot
+ */
+
+/**
+ * @typedef {{ matches: boolean, missingElementTypes: string[], unexpectedElementTypes: string[], missingIdFieldExceptions: string[], unexpectedIdFieldExceptions: string[], missingVariants: CircuitJsonVariantDiff[], unexpectedVariants: CircuitJsonVariantDiff[] }} CircuitJsonSchemaSnapshotComparison
+ */
+
 /**
  * Validates serialized CircuitJSON element objects without external runtime
  * dependencies.
@@ -255,10 +329,35 @@ export class CircuitJsonElementValidator {
         return [...ID_FIELD_EXCEPTIONS]
     }
 
+    /**
+     * Returns schema metadata suitable for drift snapshots.
+     * @returns {CircuitJsonSchemaSnapshot}
+     */
+    static schemaSnapshot() {
+        return {
+            elementTypes: CircuitJsonElementValidator.knownElementTypes(),
+            idFieldExceptions: CircuitJsonElementValidator.idFieldExceptions(),
+            variantSets: CircuitJsonElementValidator.variantSets()
+        }
+    }
+
+    /**
+     * Returns known variant discriminants from the active schema metadata.
+     * @returns {Record<string, string[]>}
+     */
+    static variantSets() {
+        return Object.fromEntries(
+            SORTED_VARIANT_SET_NAMES.map((name) => [
+                name,
+                [...VARIANT_SETS[name]].sort()
+            ])
+        )
+    }
+
     /**
      * Compares current schema metadata against a saved snapshot.
-     * @param {{ elementTypes?: string[], idFieldExceptions?: string[] }} snapshot Schema snapshot.
-     * @returns {{ matches: boolean, missingElementTypes: string[], unexpectedElementTypes: string[], missingIdFieldExceptions: string[], unexpectedIdFieldExceptions: string[] }}
+     * @param {{ elementTypes?: string[], idFieldExceptions?: string[], variantSets?: Record<string, string[]> }} snapshot Schema snapshot.
+     * @returns {CircuitJsonSchemaSnapshotComparison}
      */
     static compareSchemaSnapshot(snapshot = {}) {
         const elementComparison = CircuitJsonElementValidator.#compareSets(
@@ -269,17 +368,25 @@ export class CircuitJsonElementValidator {
             new Set(snapshot.idFieldExceptions || []),
             ID_FIELD_EXCEPTIONS
         )
+        const variantComparison =
+            CircuitJsonElementValidator.#compareVariantSets(
+                snapshot.variantSets || {}
+            )
 
         return {
             matches:
                 elementComparison.missing.length === 0 &&
                 elementComparison.unexpected.length === 0 &&
                 exceptionComparison.missing.length === 0 &&
-                exceptionComparison.unexpected.length === 0,
+                exceptionComparison.unexpected.length === 0 &&
+                variantComparison.missing.length === 0 &&
+                variantComparison.unexpected.length === 0,
             missingElementTypes: elementComparison.missing,
             unexpectedElementTypes: elementComparison.unexpected,
             missingIdFieldExceptions: exceptionComparison.missing,
-            unexpectedIdFieldExceptions: exceptionComparison.unexpected
+            unexpectedIdFieldExceptions: exceptionComparison.unexpected,
+            missingVariants: variantComparison.missing,
+            unexpectedVariants: variantComparison.unexpected
         }
     }
 
@@ -342,6 +449,14 @@ export class CircuitJsonElementValidator {
 
         if (type === 'pcb_smtpad') {
             CircuitJsonElementValidator.#validatePcbSmtPad(element, errors)
+            return
+        }
+
+        if (type === 'simulation_oscilloscope_trace') {
+            CircuitJsonElementValidator.#validateSimulationOscilloscopeTrace(
+                element,
+                errors
+            )
         }
     }
 
@@ -566,6 +681,55 @@ export class CircuitJsonElementValidator {
         }
     }
 
+    /**
+     * Validates oscilloscope trace reference and unit constraints.
+     * @param {Record<string, unknown>} element Element.
+     * @param {string[]} errors Error sink.
+     * @returns {void}
+     */
+    static #validateSimulationOscilloscopeTrace(element, errors) {
+        const voltageReferences = [
+            element.simulation_transient_voltage_graph_id,
+            element.simulation_voltage_probe_id
+        ].filter((value) =>
+            CircuitJsonElementValidator.#isNonEmptyString(value)
+        ).length
+        const currentReferences = [
+            element.simulation_transient_current_graph_id,
+            element.simulation_current_probe_id
+        ].filter((value) =>
+            CircuitJsonElementValidator.#isNonEmptyString(value)
+        ).length
+
+        if (voltageReferences + currentReferences !== 1) {
+            errors.push(
+                'simulation_oscilloscope_trace must reference exactly one graph or probe.'
+            )
+        }
+        if (voltageReferences > 0 && Object.hasOwn(element, 'amps_per_div')) {
+            errors.push(
+                'voltage oscilloscope traces must use volts_per_div, not amps_per_div.'
+            )
+        }
+        if (currentReferences > 0 && Object.hasOwn(element, 'volts_per_div')) {
+            errors.push(
+                'current oscilloscope traces must use amps_per_div, not volts_per_div.'
+            )
+        }
+        CircuitJsonElementValidator.#optionalPositiveNumber(
+            element,
+            'simulation_oscilloscope_trace',
+            'volts_per_div',
+            errors
+        )
+        CircuitJsonElementValidator.#optionalPositiveNumber(
+            element,
+            'simulation_oscilloscope_trace',
+            'amps_per_div',
+            errors
+        )
+    }
+
     /**
      * Requires a non-empty string field.
      * @param {Record<string, unknown>} element Element.
@@ -666,6 +830,24 @@ export class CircuitJsonElementValidator {
         }
     }
 
+    /**
+     * Validates an optional positive finite number field.
+     * @param {Record<string, unknown>} element Element.
+     * @param {string} type Element type.
+     * @param {string} field Field name.
+     * @param {string[]} errors Error sink.
+     * @returns {void}
+     */
+    static #optionalPositiveNumber(element, type, field, errors) {
+        if (!Object.hasOwn(element, field)) {
+            return
+        }
+        const value = Number(element[field])
+        if (!Number.isFinite(value) || value <= 0) {
+            errors.push(type + ' ' + field + ' must be a positive number.')
+        }
+    }
+
     /**
      * Requires a finite point object field.
      * @param {Record<string, unknown>} element Element.
@@ -770,4 +952,39 @@ export class CircuitJsonElementValidator {
                 .sort((left, right) => left.localeCompare(right))
         }
     }
+
+    /**
+     * Compares expected and actual variant metadata sets.
+     * @param {Record<string, string[]>} snapshotSets Snapshot variant sets.
+     * @returns {{ missing: CircuitJsonVariantDiff[], unexpected: CircuitJsonVariantDiff[] }}
+     */
+    static #compareVariantSets(snapshotSets) {
+        const missing = []
+        const unexpected = []
+        const setNames = new Set([
+            ...SORTED_VARIANT_SET_NAMES,
+            ...Object.keys(snapshotSets || {})
+        ])
+
+        for (const setName of [...setNames].sort()) {
+            const comparison = CircuitJsonElementValidator.#compareSets(
+                new Set((snapshotSets?.[setName] || []).map(String)),
+                new Set(VARIANT_SETS[setName] || [])
+            )
+            missing.push(
+                ...comparison.missing.map((value) => ({
+                    set: setName,
+                    value
+                }))
+            )
+            unexpected.push(
+                ...comparison.unexpected.map((value) => ({
+                    set: setName,
+                    value
+                }))
+            )
+        }
+
+        return { missing, unexpected }
+    }
 }