circuitjson-toolkit 1.0.17 → 1.1.0

package/docs/release-notes-v1.1.0.md

@@ -0,0 +1,154 @@
+# circuitjson-toolkit 1.1.0
+
+## Breaking API convergence
+
+This minor release intentionally changes public names, parameters, return
+shapes, and package layout so CircuitJSON, Gerber, Altium, and KiCad toolkits
+can expose the same API.
+
+The root is an exact 17-class contract: the 14 canonical classes plus temporary
+`CircuitJsonDocument`, `CircuitJsonIndexer`, and `CircuitJsonUnits` viewer
+compatibility exports. Exactly 37 previous CircuitJSON-specific classes remain
+available from `circuitjson-toolkit/extensions`; they were not removed and are
+classified as shared or derived for all four toolkits.
+
+Key changes:
+
+- `Parser.parse({ fileName, data }, options)` replaces filename/text-specific
+  parser calls and returns `ecad-toolkit.document.v1`.
+- `ProjectLoader` returns `ecad-toolkit.project.v1` with canonical document
+  envelopes. It now captures one bounded stable entry snapshot, enforces
+  `maxEntries` before inspecting entries, and gives direct and worker paths the
+  same known-field behavior.
+- Parser failures use `ToolkitError`; `tryParse` and `tryLoad` return exact
+  success/failure discriminants.
+- `retainSource` is now the explicit `'none' | 'reference'` contract.
+  Reference mode preserves exact caller identity only on direct parser calls,
+  exposes it non-enumerably, and never serializes or freezes the caller input.
+- PCB, schematic, BOM, interaction, query, manufacturing, simulation, and 3D
+  services consume either a document result, a CircuitJSON model, or a reused
+  `CircuitJsonDocumentContext`.
+- Canonical schematic graphics now include asset-backed `schematic_image`
+  rows and hierarchical `schematic_sheet_symbol` rows. Images keep payloads
+  in ToolkitAsset records, and child sheet symbols no longer masquerade as
+  selectable pages or hide unowned root graphics.
+- `PcbScene3dBuilder` and `PcbScene3dPreparator` return data-only,
+  millimeter-based, right-handed Z-up scenes. The package does not depend on
+  Three.js and never fetches assets implicitly.
+- `ecad-toolkit.worker.v1` provides equivalent parse/project results, ordered
+  progress, cancellation, strict clone-safe errors, opt-in input transfer, and
+  worker-owned output transfer.
+- `ParserWorkerClient.parseAttempt()` and `loadProjectAttempt()` give source
+  toolkits request-scoped automatic-worker fallback: only local construction
+  failure sets `unavailable: true`; parser, protocol, and runtime failures stay
+  visible.
+- Canonical subpaths now include `/parser`, `/project`, `/renderers`,
+  `/interaction`, `/query`, `/manufacturing`, `/simulation`, `/scene3d`,
+  `/capabilities`, `/extensions`, and `/testing`.
+- Shared validation proofs, indexes, render preparation, queries, and scene
+  preparation are request-scoped and reused to avoid repeated parsing,
+  validation, cloning, and spatial work.
+- Validated source extensions are captured once as immutable owned data under
+  a separate 128 MiB payload and 2,000,000-item ceiling. Realistic large native
+  graphs now survive direct and worker results; over-limit graphs fail visibly
+  and the worker keeps its 250 MB whole-result ceiling. Binary extension values
+  stay byte-backed behind defensive-copy access rather than expanding into
+  plain number arrays.
+- `CircuitJsonDocumentContext` can now only be created through `prepare()`;
+  direct construction fails before reading input so viewers and applications
+  can consume the same validation-bound context without adapter workarounds.
+- `CircuitJsonDocument.normalizeModel(model, { owned })` is the shared
+  copy-on-write compatibility boundary for legacy table geometry, PCB artwork
+  paths, pad diagnostics, courtyards, layer aliases, and stroke dash fields.
+  Toolkits normalize owned projections before one validation pass; viewers no
+  longer need application-side repair code.
+- The complete serialized-input validator is compiled from the pinned
+  development dependency `circuit-json@0.0.446`. It preserves upstream
+  refinement, pipeline, and SI-unit transform rejection behavior while keeping
+  the published browser runtime dependency-free.
+- Compiler provenance now also verifies and records the exact lock integrity
+  and distribution entry SHA-256 for `format-si-unit@0.0.7` and `zod@3.25.76`.
+- Full compatibility parsing canonicalizes legacy Gerber/KiCad outer-layer
+  aliases (`1`/`32`, `F.*`/`B.*`, and descriptor `layer.name`), fills via layer
+  defaults, converts legacy trace vias, and retains silkscreen circle/oval and
+  courtyard geometry for viewers without app-side adapters.
+- `CircuitJsonPcbHolePrimitiveModel` now measures polygon `pad_outline` in the
+  pad's rotation-local coordinate system and retains pill drill width, height,
+  diameter, and independent board-space rotation. Legal `outer_width`,
+  `outer_height`, `rect_ccw_rotation`, and `hole_ccw_rotation` variants are
+  preserved. Downstream viewers no longer need format-specific plated-slot
+  sizing logic.
+- Legal square `pcb_hole` rows normalize to equal-width rectangular apertures
+  rather than circular fallbacks.
+- `extensions: 'none'` now has the exact common return shape `{}` for native
+  documents and projects instead of a source-namespaced placeholder.
+- `ZipArchiveInspector` now validates exact local/central filenames, CRC32, and
+  size metadata and exposes `verifyExtractedBytes()` so stored and deflated
+  corruption is rejected after bounded inflation. Compression ratios use
+  compressed and uncompressed member payload totals, so ZIP comments or other
+  container padding cannot bypass expansion limits.
+- `/testing` now exports `ToolkitLoopbackWorker` alongside the contract fixtures
+  and runner so all toolkits share one real structured-clone worker regression
+  boundary.
+- Direct async parser/project paths now snapshot exact binary windows and
+  selected assets before progress callbacks. Worker-received inputs reuse their
+  structured-clone ownership boundary, and direct companion assets are prepared
+  once, closing callback mutation races without redundant receiver/result copies.
+- `npm run sync:schema -- --check` is a read-only drift gate that recompiles the
+  live pinned union and checks exact contract, provenance, snapshot, and
+  generated-module equality.
+- Validation now freezes each proven model once, the legacy parser hands its
+  already-built index to the next consumer, multi-side legacy rendering shares
+  one primitive preparation, and compact identifier indexes avoid cloning
+  duplicate element graphs.
+- `ToolkitAsset.measure()`, `prepare()`, and `prepareAll()` provide one
+  descriptor-safe asset boundary. Metadata mode copies no payload; full mode
+  copies once; project limits include attached assets in direct and worker
+  execution. Missing media types are inferred consistently for common ECAD
+  model and image suffixes, including `model/vrml` for WRL/VRML and
+  `model/step` for STEP/STP, while explicit values remain authoritative.
+- Canonical schematic rendering preserves explicit multi-value dash patterns,
+  accepts only safe SVG line-cap values, and honors `show_label: false` in both
+  component markup and bounds. Source toolkits can retain native styles and
+  hidden designators without renderer or application workarounds.
+- The release benchmark runner enforces the frozen 1.0.17 workloads: both
+  primary cases must be at least 20% faster, non-primary regressions are
+  bounded, and the duplicate index graph must be at least 25% smaller. Timing
+  uses three independent processes. Every process imports toolkit modules from
+  the freshly extracted npm tarball candidate and records an execution marker
+  that reconciles its package version and source digest with candidate
+  provenance.
+- The retained Node 20 / Apple M3 Max result passes every timing and clone
+  gate, including at least 20% faster for both primary workloads and 85.32%
+  fewer duplicate-index clone bytes. See
+  `benchmarks/results-v1.1.0.json` for samples and checksums.
+- Gerber, Altium, and KiCad packages now consume CircuitJSON Toolkit as their
+  shared runtime; their license terms do not replace this package's AGPL or
+  separately granted commercial terms.
+
+Before:
+
+```js
+import { CircuitJsonParser } from 'circuitjson-toolkit'
+
+const model = CircuitJsonParser.parseText(text, {
+    fileName: 'board.json'
+})
+```
+
+After:
+
+```js
+import { Parser } from 'circuitjson-toolkit'
+
+const document = Parser.parse({
+    fileName: 'board.json',
+    data: text
+})
+
+console.log(document.model)
+```
+
+See [migration.md](migration.md) and its generated
+[appendix pages](migration/root.md) for the exhaustive 1.0.17 feature mapping,
+and [capabilities.md](capabilities.md) for host-side capability gating.

package/docs/testing.md

@@ -1,16 +1,126 @@
-# Testing
+# Testing and downstream conformance
 
-Run the full test suite with:
+## Repository gates
 
 ```bash
+npm ci
 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 pack --dry-run
+npm run check:packed-entrypoints
+npm run check:browser-dependencies
 ```
 
-Check formatting with:
+`sync:schema -- --check` recompiles the complete element union from the pinned
+development dependency `circuit-json@0.0.446` and compares its contract hash,
+schema snapshot, provenance, and browser-neutral generated validator with the
+checked-in artifacts. Check mode is read-only. It also preserves upstream
+transform rejection boundaries, including malformed SI-unit strings that the
+upstream schema rejects by throwing instead of returning a failed parse.
 
-```bash
-npm run check:format
+The schema differential suite samples every upstream union leaf, compares
+required-field failures, exercises transform-owned resistor, capacitor,
+inductor, current-source, and crystal fields, and verifies that a fresh compile
+is exactly equal to the generated runtime contract. Unsupported future Zod
+constructs fail the compiler closed.
+
+`check:features -- --strict` packs the package, imports its public entrypoints,
+checks every 1.0.17 ledger row against the capability inventory, and verifies
+all referenced test and documentation paths.
+
+The benchmark comparison freezes historical workload semantics, fixtures,
+expected results, clone bytes, environment metadata, samples, medians, and
+checksums. Candidate timing is the median of at least three independent Node
+processes. Each process imports the toolkit runtime from the freshly extracted
+npm package candidate rather than the live worktree. Its execution marker must
+match the candidate package version and packed-source digest; candidate
+provenance additionally records the fresh tarball SHA-256.
+Primary convergence cases must improve by the release threshold; unchanged
+cases may not exceed their regression budgets. The enforced limits are 20%
+faster for both primary cases, at most 5% regression for other large cases, at
+most 10% for small cases, and at least 25% fewer clone bytes for the duplicate
+index graph.
+
+The two packed checks always create and install a fresh npm pack in isolated
+fixtures. If an explicit tarball is supplied, its digest must equal that fresh
+pack, so a stale retained candidate cannot pass. The
+entrypoint gate imports every documented subpath and runs the complete shared
+contract. The browser graph gate starts at every JavaScript, worker, and CSS
+export, follows packed relative imports, and rejects Node built-ins,
+`circuit-json`, undeclared packages, and development-only runtime edges.
+
+## Shared toolkit contract
+
+Source toolkits consume the packed harness:
+
+```js
+import {
+    ToolkitContractFixtures,
+    runToolkitContract
+} from 'circuitjson-toolkit/testing'
+import * as toolkit from 'gerber-toolkit'
+
+const report = await runToolkitContract(toolkit, {
+    fixtures: ToolkitContractFixtures.gerber()
+})
+
+assert.deepEqual(report.failures, [])
 ```
 
-Use only small fake CircuitJSON samples in tests. Do not add customer, vendor,
-or source project files to this repository.
+Fixtures are available for CircuitJSON, Gerber, Altium, and KiCad. The harness
+checks the exact canonical class list, parser and project success/failure
+paths, synchronous/asynchronous equivalence, document result shapes, context
+reuse, top/bottom rendering, interaction, query, manufacturing, simulation,
+3D scenes, typed errors, and common capability ids.
+
+Worker checks install an in-memory `ecad-toolkit.worker.v1` loopback with real
+structured-clone and transfer boundaries, then require `worker: true`. A direct
+fallback cannot satisfy these checks.
+
+Extension ownership tests use a realistic native graph above the former
+compact-metadata item ceiling. They require one bounded immutable capture,
+mutation isolation, a direct capture under two seconds, exact worker-result
+round-trip behavior, and visible rejection beyond the separate 128 MiB
+extension payload ceiling. A 3 MiB binary regression additionally requires
+byte-backed `Uint8Array` shape, defensive-copy mutation isolation, direct and
+worker parity, bounded elapsed time, and bounded JavaScript heap growth.
+
+Variant-geometry tests also lock rotation-local polygon-plated pad extents and
+pill drill dimensions, independent outer/drill rotations, and every legal
+outer-size field so Gerber, KiCad, Altium, and viewers share the same hole
+primitive contract. Legal square holes remain rectangular apertures.
+
+ZIP tests reject local/central filename, CRC32, and size disagreements, then
+verify extracted bytes for both stored and deflated members. A same-length
+payload bit flip must fail CRC32 verification instead of reaching a format
+parser.
+
+Async ownership tests mutate exact-window `SharedArrayBuffer` parser/project
+bytes, attached assets, and companion assets from the first progress callback.
+Sync, direct async, and structured-clone worker results must remain identical,
+and prepared companion assets must not be copied a second time at result build.
+
+The harness reads capability status before invoking optional behavior. A
+`shared`, `native`, or `derived` operation must return its canonical result; an
+`unavailable` operation must throw `ToolkitError` with
+`ERR_CAPABILITY_UNAVAILABLE`. This lets a source format explicitly reject work
+it cannot represent instead of returning an invented empty success.
+
+Each source repository also owns format-specific differential, worker,
+cancellation, transfer, native-fidelity, extension, and performance tests.
+
+Core convergence tests additionally exercise copy-on-write and owned legacy
+normalization, exact geometry preservation, singular/plural diagnostic
+relations, and worker-received native extensions. Performance gates cover
+50,000-element parse and index preparation, repeated hit testing, multi-side
+rendering, and clone allocation so compatibility does not add an
+application-visible slow path.
+
+## Fixture policy
+
+Use only small synthetic, obfuscated, repository-owned samples. Never commit
+customer, vendor, or source project files. Fixes must derive from the format,
+schema, or protocol rather than sample names or known text.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.0.17",
-    "description": "Dependency-free CircuitJSON parsing, validation, indexing, and utility helpers",
+    "version": "1.1.0",
+    "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
         "circuit-json",
@@ -29,12 +29,28 @@
     "exports": {
         ".": "./src/index.mjs",
         "./parser": "./src/parser.mjs",
-        "./renderers": "./src/renderers.mjs"
+        "./project": "./src/project.mjs",
+        "./renderers": "./src/renderers.mjs",
+        "./interaction": "./src/interaction.mjs",
+        "./query": "./src/query.mjs",
+        "./manufacturing": "./src/manufacturing.mjs",
+        "./simulation": "./src/simulation.mjs",
+        "./scene3d": "./src/scene3d.mjs",
+        "./capabilities": "./src/capabilities.mjs",
+        "./extensions": "./src/extensions.mjs",
+        "./testing": "./src/testing.mjs",
+        "./workers/parser.worker.mjs": "./src/workers/parser.worker.mjs",
+        "./styles/renderers.css": "./src/styles/renderers.css"
     },
     "files": [
         "src",
         "docs/api.md",
+        "docs/capabilities.md",
+        "docs/migration.md",
+        "docs/migration",
         "docs/model-format.md",
+        "docs/provenance.md",
+        "docs/release-notes-v1.1.0.md",
         "docs/testing.md",
         "spec",
         "LICENSE",
@@ -49,10 +65,20 @@
     "scripts": {
         "test": "node --test",
         "format": "prettier --write .",
-        "check:format": "prettier --check ."
+        "check:format": "prettier --check .",
+        "sync:schema": "node scripts/sync-circuit-json-schema.mjs",
+        "sync:migration": "node scripts/generate-migration-doc.mjs",
+        "capture:api": "node scripts/capture-api-baseline.mjs",
+        "check:features": "node scripts/check-feature-preservation.mjs",
+        "check:packed-entrypoints": "node scripts/check-packed-entrypoints.mjs",
+        "check:browser-dependencies": "node scripts/check-browser-dependency-graph.mjs",
+        "benchmark": "node --expose-gc scripts/run-benchmarks.mjs --compare benchmarks/baseline-v1.0.17.json"
     },
     "devDependencies": {
-        "prettier": "^3.4.2"
+        "circuit-json": "0.0.446",
+        "format-si-unit": "0.0.7",
+        "prettier": "^3.4.2",
+        "zod": "3.25.76"
     },
     "engines": {
         "node": ">=20"