altium-toolkit 0.1.23 → 1.0.1

package/README.md

@@ -27,10 +27,11 @@ browser or Node-based tools.
   basic text metrics
 - Preserve raw PCB primitive records through a read-only record registry so
   unsupported or partially decoded stream data remains inspectable
-- Emit versioned normalized model roots with a machine-readable JSON Schema
-  contract
+- Emit Circuit JSON arrays from parser roots, with non-serialized
+  renderer-compatibility fields for existing consumers
 - Render schematic SVG, PCB SVG, and grouped BOM HTML
-- Build non-interactive PCB 3D scene-description data for host applications
+- Build non-interactive PCB 3D scene-description data for host applications,
+  including refined board outlines and silkscreen drill cutouts
 - Render a static 3D board summary
 - Run entirely with local input data; no network calls are made by the parser
 

package/docs/api.md

@@ -14,6 +14,7 @@ scene-description classes from one entrypoint.
 Specialized entrypoints are also available:
 
 - `altium-toolkit/parser`
+- `altium-toolkit/netlist-query`
 - `altium-toolkit/renderers`
 - `altium-toolkit/scene3d`
 - `altium-toolkit/workers/altium-parser.worker.mjs`
@@ -24,15 +25,16 @@ Specialized entrypoints are also available:
 ```js
 import { AltiumParser } from 'altium-toolkit/parser'
 
-const documentModel = AltiumParser.parseArrayBuffer(fileName, arrayBuffer)
+const circuitJson = AltiumParser.parseArrayBuffer(fileName, arrayBuffer)
 ```
 
 `fileName` is used to infer schematic, PCB document, PCB footprint-library, or
 PCB project parsing from the extension. The parser accepts native `.SchDoc`,
-`.PcbDoc`, `.PcbLib`, and `.PrjPcb` bytes as an `ArrayBuffer` and returns the
-normalized model described in [Model Format](model-format.md). Every parser
-root includes a top-level `schema` id for the emitted normalized model
-contract.
+`.PcbDoc`, `.PcbLib`, and `.PrjPcb` bytes as an `ArrayBuffer` and returns a
+Circuit JSON element array. The returned array carries non-serialized
+renderer-compatibility fields such as `kind`, `fileType`, `schematic`, `pcb`,
+`pcbLibrary`, `project`, `summary`, `diagnostics`, and `bom` so existing
+renderers can consume parser output directly during the migration.
 
 PCB parsing reads the main primitive streams together with sidecar streams such
 as `PrimitiveParameters/Data` and `WideStrings6/Data`. Component parameters are
@@ -41,13 +43,18 @@ resolve their display string through the wide-string table before the
 normalized component list and BOM are built.
 
 ```js
-import { NormalizedModelSchema } from 'altium-toolkit/parser'
+import { CircuitJsonModelSchema } from 'altium-toolkit/parser'
 
-if (documentModel.schema !== NormalizedModelSchema.CURRENT_SCHEMA_ID) {
-    throw new Error('Unsupported normalized model schema')
+if (!CircuitJsonModelSchema.isModel(circuitJson)) {
+    throw new Error('Unsupported Circuit JSON model')
 }
 ```
 
+Use `AltiumParser.parseArrayBufferToRendererModel(fileName, arrayBuffer)` when
+an integration still needs the legacy renderer model object. The
+`CircuitJsonModelAdapter` export also exposes `fromRendererModel()`,
+`toRendererModel()`, and `isCircuitJson()` for explicit conversions.
+
 Specialized parser helpers are exported for lower-level integrations, including
 `PcbBoardRegionSemanticsParser`, `PcbComponentPrimitiveIndexer`,
 `PcbEmbeddedFontExtractor`, `PcbFontMetricsParser`, `PcbPadStackParser`,
@@ -63,6 +70,35 @@ to normalized models. `PcbRawRecordRegistry` exposes immutable primitive stream
 descriptors and the raw-record preservation helpers used by the PcbDoc/PcbLib
 extractors.
 
+## Netlist Query
+
+```js
+import { LoadedDesignNetlistService } from 'altium-toolkit/netlist-query'
+
+const service = new LoadedDesignNetlistService({
+    getDocuments: () => [
+        {
+            id: 'active-sheet',
+            active: true,
+            documentModel
+        }
+    ]
+})
+
+const nets = service.searchNets({ pattern: 'i2c' })
+```
+
+The `netlist-query` entrypoint exposes browser-safe helpers for loaded document
+inspection: `LoadedDesignNetlistService`, `QueryNetlistBuilder`,
+`CircuitTraversal`, `ComponentGrouping`, `MPN_MISSING_NOTE`, and
+`RegexPattern`.
+
+The service accepts host-provided loaded document entries and returns plain
+JSON-compatible query results. It can list designs, components, and nets; search
+components by reference designator, MPN, or description; query one component's
+pin connections; and trace extended connectivity from a net or `REFDES.PIN`.
+Normal user-query failures return `{ error: string }`.
+
 ## Renderers
 
 ```js
@@ -100,6 +136,9 @@ import {
 
 - `PcbScene3dBuilder.build(documentModel, options)` returns procedural board,
   placement, copper, silkscreen, and external-model scene-description data.
+  It includes refined board-region outlines when a recovered outline is a
+  rasterized stair-step fallback, and each silkscreen side exposes
+  `drillCutouts` plus fill holes for drilled pads and vias.
 - `PcbScene3dModelRegistry` resolves embedded or session model candidates for
   component placements.
 - `PcbScene3dScenePreparator.prepare(documentModel, options)` prepares the same

package/docs/model-format.md

@@ -6,8 +6,30 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Model Format
 
-The normalized model is intentionally stable with the ECAD Forge parser model.
-The parser returns one object per parsed native document.
+The public parser returns one Circuit JSON element array per parsed native
+document. Circuit JSON is the serialized model contract. The returned array
+also carries non-serialized renderer-compatibility fields that preserve the
+previous ECAD Forge parser model for renderers and migration code.
+
+## Circuit JSON Fields
+
+Every parser result is an array of elements with a `type` field. The adapter
+emits Circuit JSON elements for source project metadata, source components,
+ports, nets, schematic symbols, schematic lines, schematic text, PCB boards,
+PCB components, PCB pads, PCB traces, and PCB vias where those structures are
+available in the source document.
+
+Use `CircuitJsonModelSchema.isModel(result)` to validate that a value is a
+Circuit JSON array. `JSON.stringify(result)` serializes only the Circuit JSON
+elements; compatibility fields are intentionally omitted from serialized JSON.
+
+## Renderer Compatibility Fields
+
+For compatibility, `AltiumParser.parseArrayBuffer()` attaches the previous
+renderer model fields directly to the Circuit JSON array. Integrations that need
+the object form can call
+`AltiumParser.parseArrayBufferToRendererModel(fileName, arrayBuffer)` or
+`CircuitJsonModelAdapter.toRendererModel(circuitJson)`.
 
 ## Common Fields
 
@@ -21,11 +43,13 @@ The parser returns one object per parsed native document.
 
 ## Schema Contracts
 
-The current root model contract is published as a JSON Schema at
+The legacy renderer compatibility contract is published as a JSON Schema at
 [`docs/schemas/altium_toolkit/normalized_model_a1.schema.json`](schemas/altium_toolkit/normalized_model_a1.schema.json).
-Parser roots expose the same id through the top-level `schema` field, and
-library consumers can compare it with
-`NormalizedModelSchema.CURRENT_SCHEMA_ID`.
+Compatibility fields expose the same id through the top-level `schema` field,
+and consumers can compare it with `NormalizedModelSchema.CURRENT_SCHEMA_ID`.
+The serialized parser return value follows the upstream
+[`tscircuit/circuit-json`](https://github.com/tscircuit/circuit-json) element
+array convention.
 
 ## Schematic Fields
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "0.1.23",
+    "version": "1.0.1",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",
@@ -23,6 +23,7 @@
     "exports": {
         ".": "./src/index.mjs",
         "./parser": "./src/parser.mjs",
+        "./netlist-query": "./src/netlist-query.mjs",
         "./renderers": "./src/renderers.mjs",
         "./scene3d": "./src/scene3d.mjs",
         "./workers/altium-parser.worker.mjs": "./src/workers/altium-parser.worker.mjs",

package/spec/library-scope.md

@@ -16,7 +16,8 @@ rendering primitives.
 - Schematic SVG rendering
 - PCB SVG rendering
 - BOM HTML rendering
-- PCB 3D scene-description data
+- PCB 3D scene-description data, including board-region outline refinement and
+  silkscreen drill cutout contours
 - Embedded PCB/PcbLib font extraction and basic text metrics for deterministic
   SVG rendering
 - Read-only PCB primitive record registry metadata and base64 raw-record

package/src/core/altium/AltiumParser.mjs

@@ -27,6 +27,7 @@ import { SchematicImageParser } from './SchematicImageParser.mjs'
 import { SchematicNetlistBuilder } from './SchematicNetlistBuilder.mjs'
 import { SchematicComponentTextResolver } from './SchematicComponentTextResolver.mjs'
 import { SchematicStreamExtractor } from './SchematicStreamExtractor.mjs'
+import { CircuitJsonModelAdapter } from '../circuit-json/CircuitJsonModelAdapter.mjs'
 const {
     countMatchingKeys,
     getDisplayText,
@@ -53,16 +54,28 @@ const {
 } = SchematicPinParser
 
 /**
- * Parses native Altium files into normalized viewer models.
+ * Parses native Altium files into Circuit JSON element arrays.
  */
 export class AltiumParser {
     /**
-     * Parses a native Altium buffer into a normalized viewer model.
+     * Parses a native Altium buffer into a Circuit JSON element array.
      * @param {string} fileName
      * @param {ArrayBuffer} arrayBuffer
-     * @returns {{ schema: string, kind: 'schematic' | 'pcb' | 'pcb-library' | 'project', fileType: 'SchDoc' | 'PcbDoc' | 'PcbLib' | 'PrjPcb', fileName: string, summary: Record<string, number | string>, diagnostics: { severity: 'info' | 'warning', message: string }[], schematic?: Record<string, unknown>, pcb?: Record<string, unknown>, pcbLibrary?: Record<string, unknown>, project?: Record<string, unknown>, bom: { designators: string[], quantity: number, pattern: string, source: string, value: string }[] }}
+     * @returns {object[]}
      */
     static parseArrayBuffer(fileName, arrayBuffer) {
+        return CircuitJsonModelAdapter.fromRendererModel(
+            AltiumParser.parseArrayBufferToRendererModel(fileName, arrayBuffer)
+        )
+    }
+
+    /**
+     * Parses a native Altium buffer into the renderer compatibility model.
+     * @param {string} fileName
+     * @param {ArrayBuffer} arrayBuffer
+     * @returns {{ schema: string, kind: 'schematic' | 'pcb' | 'pcb-library' | 'project', fileType: 'SchDoc' | 'PcbDoc' | 'PcbLib' | 'PrjPcb', fileName: string, summary: Record<string, number | string>, diagnostics: { severity: 'info' | 'warning', message: string }[], schematic?: Record<string, unknown>, pcb?: Record<string, unknown>, pcbLibrary?: Record<string, unknown>, project?: Record<string, unknown>, bom: { designators: string[], quantity: number, pattern: string, source: string, value: string }[] }}
+     */
+    static parseArrayBufferToRendererModel(fileName, arrayBuffer) {
         const records = AsciiRecordParser.parse(arrayBuffer)
         const fileType = AltiumParser.#sniffFileType(fileName, records)
         if (fileType === 'SchDoc') {
@@ -118,7 +131,7 @@ export class AltiumParser {
      * @param {string} fileName
      * @param {{ raw: string, fields: Record<string, string | string[]> }[]} records
      * @param {ArrayBuffer} arrayBuffer
-     * @returns {ReturnType<typeof AltiumParser.parseArrayBuffer>}
+     * @returns {ReturnType<typeof AltiumParser.parseArrayBufferToRendererModel>}
      */
     static #parseSchematic(fileName, records, arrayBuffer) {
         const componentRecords = records.filter(