circuitjson-toolkit 1.0.17 → 1.1.0

package/NOTICE.md

@@ -28,3 +28,34 @@ For applications with an "About", "Licenses", or "Legal Notices" screen,
 include a reasonable reference to this project and its original author there.
 
 Package-manager dependencies retain their own licenses.
+
+## Canonical ECAD toolkit convergence
+
+Version 1.1.0 defines the common parser, project, renderer, interaction, query,
+manufacturing, simulation, data-only 3D scene, capability, error, and worker
+contracts used by CircuitJSON Toolkit, Gerber Toolkit, Altium Toolkit, and
+KiCad Toolkit.
+
+Source-format packages retain their own native decoders, fidelity engines,
+assets, reports, and license terms. Shared behavior generalized here operates
+on standards-only CircuitJSON and does not copy source-format parser models or
+renderer graphs. `docs/provenance.md` records consulted behavior and adapted
+ownership boundaries.
+
+The `circuit-json` schema package is used only for development-time schema
+verification. It is not a runtime dependency or bundled production edge.
+
+## Query behavior references
+
+The shared CircuitJSON query contract was independently implemented after
+reviewing the byte-identical netlist-query behavior in these projects:
+
+- Altium Toolkit (`https://github.com/SunboX/altium-toolkit`), source commit
+  `e8a8cd551ad103cd0cf96bb5b5f5b816874ed72b`;
+- KiCad Toolkit (`https://github.com/SunboX/kicad-toolkit`), source commit
+  `02e38fe0b961a09d2ff25462b9b00207326743d2`.
+
+Those consulted files are Copyright (C) 2026 André Fiedler and licensed
+`GPL-3.0-or-later`. CircuitJSON Toolkit does not copy their source text or
+package-native model logic; `docs/provenance.md` records the per-module
+behavior-only reuse decisions.

package/README.md

@@ -6,169 +6,321 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # CircuitJSON Toolkit
 
-CircuitJSON Toolkit is an ESM JavaScript library for parsing, validating,
-indexing, and inspecting serialized CircuitJSON element arrays.
+CircuitJSON Toolkit is the dependency-free common runtime for the ECAD toolkit
+family. It provides the same parser, project, rendering, interaction, query,
+manufacturing, simulation, 3D scene, capability, error, and worker contracts
+used by `gerber-toolkit`, `altium-toolkit`, and `kicad-toolkit`.
+
+CircuitJSON is the shared immutable model. Source-format packages keep their
+native decoders and fidelity data in explicit extension namespaces while
+common services operate on `DocumentResult.model` or a reused
+`CircuitJsonDocumentContext`.
+
+The package is browser- and Node-compatible, local-first, and has no runtime
+dependencies. It does not import Three.js, the DOM, filesystem APIs, or network
+clients.
+
+## Breaking API convergence
+
+Version 1.1.0 intentionally changes names, parameters, return shapes, and
+package subpaths to match the Gerber, Altium, and KiCad toolkits. The root is an
+exact 17-class surface: 14 common classes plus three deprecated viewer
+compatibility classes. Previous CircuitJSON-specific utilities were not
+deleted: 37 source-neutral compatibility exports moved to
+`circuitjson-toolkit/extensions`.
+
+See the [migration guide](docs/migration.md) and its generated
+[root](docs/migration/root.md), [parser](docs/migration/parser.md),
+[renderer](docs/migration/renderers.md), and
+[behavior](docs/migration/behaviors.md) appendices for all 1,207 preserved
+1.0.17 features. The
+[1.1.0 release notes](docs/release-notes-v1.1.0.md) provide the concise change
+summary.
+
+Before 1.1.0:
 
-The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
-is used as the shared CircuitJSON runtime utility layer between ECAD parsers,
-viewer adapters, and browser-based import flows. Its parser-style API,
-metadata conventions, and local-first behavior are designed to line up with
-packages such as `altium-toolkit` and `kicad-toolkit`, while remaining
-independent of any source ECAD format.
+```js
+import { CircuitJsonParser } from 'circuitjson-toolkit'
 
-This package is intentionally separate from
-[`pcb-scene3d-viewer`](https://www.npmjs.com/package/pcb-scene3d-viewer).
-`circuitjson-toolkit` owns CircuitJSON parsing, validation, indexing, and unit
-helpers. `pcb-scene3d-viewer` owns Three.js runtime rendering and consumes this
-package as a normal npm dependency.
+const model = CircuitJsonParser.parseText(text, {
+    fileName: 'board.json'
+})
+```
+
+After 1.1.0:
+
+```js
+import { Parser } from 'circuitjson-toolkit'
+
+const document = Parser.parse({
+    fileName: 'board.json',
+    data: text
+})
+const model = document.model
+```
 
 ## Features
 
-- Parse standalone CircuitJSON `.json` text from strings, `ArrayBuffer`, or
-  `Uint8Array` input
-- Validate serialized CircuitJSON element arrays with a small, stable document
-  API
-- Attach parser-style metadata such as `fileName`, `fileType`, `kind`, and
-  `sourceFormat`, matching the conventions used by the ECAD toolkit packages
-- Build lookup indexes by element type and stable CircuitJSON identifiers
-- Resolve source component and PCB component maps for viewer, QA, export, or
-  reporting integrations
-- 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
-- Stay dependency-free at runtime
+- Exact `Parser` and `ProjectLoader` contracts with typed envelopes and errors
+- Immutable CircuitJSON validation proofs and request-scoped reusable indexes
+- Copy-on-write normalization of supported legacy CircuitJSON aliases through
+  `CircuitJsonDocument.normalizeModel()`
+- Deterministic PCB, schematic, and BOM renderers
+- Asset-backed `schematic_image` rows and hierarchical
+  `schematic_sheet_symbol` rows with shared bounds and SVG behavior
+- Reusable exact PCB interaction and spatial indexes
+- Query, manufacturing, and injected simulation services
+- Data-only, millimeter-based, right-handed Z-up PCB 3D scenes
+- Descriptor-safe `ToolkitAsset` measurement and preparation with zero-copy
+  metadata mode, one-copy full mode, and shared ECAD model/image media-type
+  inference
+- Explicit asynchronous scene-asset preparation without implicit I/O
+- Strict `ecad-toolkit.worker.v1` parsing/project protocol with progress,
+  cancellation, and controlled buffer transfer
+- One-pass ownership for selected source extensions, with a separate 128 MiB /
+  2,000,000-item bound and exact direct/worker result parity
+- Machine-readable capability inventory and packed downstream conformance
+  harness
+- Explicit `/extensions` surface retaining every previous specialized API
+- Local-only behavior and no runtime package dependencies
 
 ## Install
 
-The package is published on npm as
-[`circuitjson-toolkit`](https://www.npmjs.com/package/circuitjson-toolkit).
-
 ```bash
 npm install circuitjson-toolkit
 ```
 
-## Usage
+Node.js 20 or newer is required.
 
-Parse a standalone CircuitJSON file or string:
+## Parse and reuse a context
 
 ```js
 import {
-    CircuitJsonDocument,
-    CircuitJsonIndexer,
-    CircuitJsonParser
+    CircuitJsonDocumentContext,
+    Parser,
+    PcbInteractionIndex,
+    PcbSvgRenderer,
+    QueryService
 } from 'circuitjson-toolkit'
 
-const circuitJson = CircuitJsonParser.parseText(fileText)
-CircuitJsonDocument.assertModel(circuitJson)
-
-const index = CircuitJsonIndexer.index(circuitJson)
-console.log(index.elementsByType.get('pcb_board'))
-```
-
-The parser also accepts bytes, mirroring the parser style used by the source
-ECAD toolkits:
-
-```js
-import { CircuitJsonParser } from 'circuitjson-toolkit'
+const document = Parser.parse({
+    fileName: 'board.json',
+    data: fileText
+})
 
-const documentModel = CircuitJsonParser.parseBytes(arrayBuffer, {
-    fileName: file.name
+const context = CircuitJsonDocumentContext.prepare(document, {
+    indexes: ['elements', 'relations', 'connectivity', 'spatial']
 })
-```
 
-Parser-focused imports are available through the `parser` subpath:
+const svg = PcbSvgRenderer.render(context, { side: 'top' })
+const hits = PcbInteractionIndex.create(context).hitTest({ x: 10, y: 5 })
+const components = QueryService.create(context).query({
+    select: 'components'
+})
 
-```js
-import { CircuitJsonParser } from 'circuitjson-toolkit/parser'
+console.log(document.model, svg, hits, components.items)
 ```
 
-Build an index for renderer or reporting integrations:
+`Parser.parse()` returns the exact clone-safe `ecad-toolkit.document.v1`
+envelope:
 
 ```js
-import { CircuitJsonIndexer } from 'circuitjson-toolkit'
-
-const index = CircuitJsonIndexer.index(documentModel)
-const board = index.elementsByType.get('pcb_board')?.[0]
-const components = index.elementsByType.get('pcb_component') || []
-const source = index.sourceComponentById.get('source_component_1')
+{
+    schema: 'ecad-toolkit.document.v1',
+    id: 'document-...',
+    modelSchema: { name: 'circuit-json', version: '0.0.446' },
+    model: [],
+    source: { format: 'circuitjson', fileName: 'board.json', fileType: 'circuitjson' },
+    extensions: {},
+    assets: [],
+    diagnostics: [],
+    statistics: {}
+}
 ```
 
-Convert CircuitJSON millimeter coordinates for renderer adapters:
+## Project and asynchronous parsing
 
 ```js
-import { CircuitJsonUnits } from 'circuitjson-toolkit'
-
-const centerMil = CircuitJsonUnits.pointMmToMil(board.center)
-const widthMil = CircuitJsonUnits.mmToMil(board.width)
+import { Parser, ProjectLoader } from 'circuitjson-toolkit'
+
+const project = ProjectLoader.load(
+    [
+        {
+            name: 'board.json',
+            data: boardText,
+            assets: [{ name: 'body.step', data: bodyBytes }]
+        },
+        { name: 'schematic.json', data: schematicText }
+    ],
+    { decodeAssets: 'metadata' }
+)
+
+const controller = new AbortController()
+const document = await Parser.parseAsync(
+    { fileName: 'board.json', data: boardBytes },
+    {
+        worker: 'auto',
+        transferInput: false,
+        signal: controller.signal,
+        onProgress: ({ stage, detail }) => console.log(stage, detail)
+    }
+)
+
+console.log(project.documents, document.model)
 ```
 
-Run a local SPICE transient example and receive CircuitJSON experiment output:
+Attached asset bytes count toward both `maxEntryBytes` and `maxTotalBytes` in
+direct and worker project loading, even when `decodeAssets: 'none'` omits them
+from the result.
+
+Direct and worker calls return equivalent serialized results. Caller input is
+never detached unless `transferInput: true` is explicit. `worker: 'auto'`
+falls back to direct execution only when worker construction is unavailable;
+explicit worker and runtime failures remain visible.
+
+Selected source-native extensions are captured once into an immutable owned
+snapshot. Their separate 128 MiB payload and 2,000,000-item ceilings permit
+realistic renderer/model graphs without weakening the worker protocol's 250 MB
+total-result ceiling; an over-limit extension fails visibly instead of being
+silently truncated. Binary extension values remain byte-backed and return
+defensive copies instead of expanding into JavaScript number arrays.
+When extensions are disabled, native documents and projects return the exact
+empty map `{}`. Bounded ZIP consumers can preflight local/central filenames and
+CRC32/size metadata with
+`ZipArchiveInspector.inspect()` and validate inflated bytes with
+`verifyExtractedBytes()`. Compression limits use member payload sizes, so ZIP
+comments or other container padding cannot dilute the measured expansion ratio.
+
+The shared PCB hole primitive preserves circular, pill/oval, rectangular, and
+square legal variants. Square holes normalize to equal-width rectangular
+apertures instead of circular fallbacks.
+
+`retainSource: 'reference'` is available for direct parser calls that need the
+exact caller input identity. It adds a non-enumerable `sourceReference`, does
+not freeze the caller object, and is omitted from serialized results. Explicit
+worker execution rejects this identity-only mode; automatic execution stays
+direct.
+
+## Render, inspect, export, simulate, and build scenes
 
 ```js
-import { SpiceSimulationService } from 'circuitjson-toolkit'
+import {
+    BomTableRenderer,
+    ManufacturingService,
+    PcbScene3dBuilder,
+    PcbScene3dPreparator,
+    SchematicSvgRenderer,
+    SimulationService
+} from 'circuitjson-toolkit'
 
-const result = await SpiceSimulationService.simulate(`
-Vmain out 0 DC 3.3
-.PRINT TRAN V(out)
-.tran 1ms 2ms
-.END
-`)
+const schematicSvg = SchematicSvgRenderer.render(document)
+const bomHtml = BomTableRenderer.render(document)
+const manufacturing = ManufacturingService.inspect(document)
+const simulation = SimulationService.build(document)
+const canonicalScene = PcbScene3dBuilder.build(document)
 
-console.log(result.simulationCircuitJson)
-console.log(result.graphSummary)
+const preparedScene = await PcbScene3dPreparator.prepare(document, {
+    fidelity: 'native',
+    resolveAsset: async (request, { signal }) =>
+        await hostAssetStore.resolve(request, { signal })
+})
 ```
 
-Pass CircuitJSON to the 3D renderer as a separate step:
+3D results use the `ecad-toolkit.scene3d.v1` data contract. Runtime rendering
+belongs to packages such as
+[`pcb-scene3d-viewer`](https://www.npmjs.com/package/pcb-scene3d-viewer).
 
-```js
-import { CircuitJsonParser } from 'circuitjson-toolkit'
-import { PcbScene3dController } from 'pcb-scene3d-viewer'
+## Retained extension APIs
 
-const circuitJson = CircuitJsonParser.parseText(fileText, {
-    fileName: 'board.circuitjson'
-})
+Previous specialized exports remain available explicitly:
 
-const controller = new PcbScene3dController(viewportNode, circuitJson)
+```js
+import {
+    CircuitJsonParser,
+    CircuitJsonPcbSvgRenderer,
+    SpiceSimulationService
+} from 'circuitjson-toolkit/extensions'
 ```
 
-`circuitjson-toolkit` does not render, fetch, or load external model assets.
-That behavior belongs in host applications or renderer packages.
+New integrations should use canonical classes. `/extensions` exists for
+deliberate migrations, not as a second common API. Its exact 37 exports are
+source-neutral and can be shared or derived by all four toolkits.
+
+The temporary root compatibility class also exposes
+`CircuitJsonDocument.normalizeModel(model, { owned })`. It projects supported
+pre-union table, PCB path, pad-clearance, courtyard, and artwork aliases onto
+the pinned CircuitJSON union. The default copy-on-write mode returns the exact
+input when it is already canonical; `{ owned: true }` is reserved for
+toolkit-owned mutable projections and may update them in place. Renderers and
+viewers can therefore share the same normalization boundary instead of keeping
+application adapters.
+
+The compatibility renderer also provides
+`CircuitJsonPcbSvgRenderer.renderSides(model, sides)` so callers migrating
+multi-side output can prepare legacy primitives once.
+
+`CircuitJsonPcbHolePrimitiveModel` is the shared geometry boundary for drilled
+PCB elements. Polygon-plated pads derive rotation-local width and height from
+`pad_outline`, while pill drill width, height, diameter, and rotation remain
+available to viewers and manufacturing consumers without source adapters.
+
+Direct asynchronous parsing and project loading own exact binary view windows
+and selected assets before the first progress callback. Worker-received inputs
+reuse their structured-clone ownership marker, avoiding a redundant receiver
+copy while keeping sync, direct async, and worker results mutation-isolated.
+
+## Package entrypoints
+
+- `circuitjson-toolkit`
+- `circuitjson-toolkit/parser`
+- `circuitjson-toolkit/project`
+- `circuitjson-toolkit/renderers`
+- `circuitjson-toolkit/interaction`
+- `circuitjson-toolkit/query`
+- `circuitjson-toolkit/manufacturing`
+- `circuitjson-toolkit/simulation`
+- `circuitjson-toolkit/scene3d`
+- `circuitjson-toolkit/capabilities`
+- `circuitjson-toolkit/extensions`
+- `circuitjson-toolkit/testing`
+- `circuitjson-toolkit/workers/parser.worker.mjs`
+- `circuitjson-toolkit/styles/renderers.css`
 
 ## Documentation
 
-- [API](docs/api.md)
-- [Model Format](docs/model-format.md)
-- [Testing](docs/testing.md)
-- [Scope](spec/library-scope.md)
-
-## Package Scope
+- [API reference](docs/api.md)
+- [Capability inventory](docs/capabilities.md)
+- [Migration from 1.0.17](docs/migration.md)
+- [Model and envelope format](docs/model-format.md)
+- [Testing and downstream conformance](docs/testing.md)
+- [1.1.0 release notes](docs/release-notes-v1.1.0.md)
+- [Library scope](spec/library-scope.md)
 
-This package owns reusable CircuitJSON utility behavior only:
+## Package scope
 
-- parser-style document ingestion for serialized CircuitJSON;
-- 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.
+This package owns common, data-only operations derived from CircuitJSON. Native
+Gerber, Altium, and KiCad decoding remains in the source toolkit. Native-only
+facts remain in `document.extensions[format]`; common services do not duplicate
+or rename native renderer graphs.
 
-It does not include native Altium or KiCad parsing, schematic/PCB SVG
-rendering, Three.js rendering, browser UI controls, network fetching, or
-format-specific scene-description builders.
+The package does not own Three.js runtime rendering, browser UI controls,
+implicit filesystem access, implicit network access, or source-format-specific
+decoders.
 
 ## Test
 
 ```bash
 npm test
+npm run check:format
+npm run sync:schema -- --check
+npm run check:features -- --strict
+npm run benchmark -- --compare benchmarks/baseline-v1.0.17.json
+npm run check:packed-entrypoints
+npm run check:browser-dependencies
 ```
 
-The test suite uses small fake CircuitJSON samples only. Do not add customer,
-vendor, or source project documents to this repository.
+Tests use small synthetic CircuitJSON and source-format fixtures only. Do not
+add customer, vendor, or source project documents.
 
 ## License
 
@@ -197,6 +349,14 @@ Commercial licensing contact: https://github.com/SunboX
 See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md). That file is a licensing
 notice, not a commercial license grant.
 
+### Downstream toolkit dependency
+
+Gerber Toolkit, Altium Toolkit, and KiCad Toolkit use this package as their
+shared runtime. Their package or commercial terms do not replace this
+package's AGPL or separately granted commercial terms. A closed-source product
+using a source toolkit must also have an AGPL-compatible use or a separate
+commercial license for CircuitJSON Toolkit.
+
 ### Documentation and notices
 
 Documentation and non-code text are licensed under Creative Commons