circuitjson-toolkit 1.0.16 → 1.1.0

package/docs/capabilities.md

@@ -0,0 +1,70 @@
+# Capability inventory
+
+`ToolkitCapabilities.inventory()` is the machine-readable operation inventory
+shared by CircuitJSON, Gerber, Altium, and KiCad toolkits. Every row has the
+same fields:
+
+```js
+{
+    id: 'scene3d.prepare',
+    category: 'scene3d',
+    operation: 'prepare',
+    status: 'shared',
+    entrypoint: 'PcbScene3dPreparator',
+    summary: '...',
+    reason: '...',
+    tested: true,
+    documented: true
+}
+```
+
+`status` is one of `native`, `shared`, `derived`, or `unavailable`. An
+unavailable operation must throw `ToolkitError` with
+`ERR_CAPABILITY_UNAVAILABLE`; an empty or invented result is not a substitute.
+
+## Common behavior families
+
+The canonical contract requires these operation ids across all four toolkits:
+
+- `bom.build`
+- `interaction.pcb`
+- `manufacturing.export`
+- `parse.document`
+- `project.load`
+- `query.document`
+- `render.pcb`
+- `render.schematic`
+- `scene3d.build`
+- `scene3d.prepare`
+- `simulation.spice`
+- `validation.document`
+- `worker.load-project`
+- `worker.parse`
+
+The CircuitJSON package additionally inventories retained shared and extension
+operations:
+
+- `export.selected-part`
+- `metadata.normalize`
+- `units.convert`
+
+Source-format packages may add native capability ids for features that cannot
+be represented by CircuitJSON. Their availability maps still state whether the
+same behavior is native, shared, derived, or unavailable in every toolkit.
+
+## Host gating
+
+Hosts should gate controls by capability id and status, not by package name:
+
+```js
+const capabilities = new Map(
+    ToolkitCapabilities.inventory().map((row) => [row.id, row])
+)
+
+if (capabilities.get('scene3d.prepare')?.status !== 'unavailable') {
+    await PcbScene3dPreparator.prepare(document, options)
+}
+```
+
+This keeps ECAD Forge and other consumers independent of source-specific class
+names while preserving explicit access to native extensions.

package/docs/migration/behaviors.md

@@ -0,0 +1,45 @@
+# Observable behaviors migration mappings
+
+This generated appendix contains 8 of the 1207 exhaustive
+1.0.17 to 1.1.0 feature mappings. Regenerate it with
+`npm run sync:migration`.
+
+[Back to the migration guide](../migration.md)
+
+## manufacturing.export
+
+| 1.0.17 feature                                     | Kind     | Disposition | 1.1.0 replacement                                               | Availability                                                          |
+| -------------------------------------------------- | -------- | ----------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| manufacturing downloads reject unsupported formats | behavior | shared      | circuitjson-toolkit/manufacturing#ManufacturingService.export() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+
+## parse.document
+
+| 1.0.17 feature                                     | Kind     | Disposition | 1.1.0 replacement                         | Availability                                                          |
+| -------------------------------------------------- | -------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------- |
+| parser metadata survives structured cloning        | behavior | shared      | circuitjson-toolkit/parser#Parser.parse() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| parser rejects malformed JSON with SyntaxError     | behavior | shared      | circuitjson-toolkit/parser#Parser.parse() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| parser rejects non-CircuitJSON JSON with TypeError | behavior | shared      | circuitjson-toolkit/parser#Parser.parse() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+
+## query.document
+
+| 1.0.17 feature                                   | Kind     | Disposition | 1.1.0 replacement                               | Availability                                                       |
+| ------------------------------------------------ | -------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------ |
+| indexer builds deterministic type and id lookups | behavior | shared      | circuitjson-toolkit/query#QueryService.create() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+
+## render.pcb
+
+| 1.0.17 feature                                            | Kind     | Disposition | 1.1.0 replacement                                     | Availability                                                          |
+| --------------------------------------------------------- | -------- | ----------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
+| PCB renderer selects top or bottom side deterministically | behavior | shared      | circuitjson-toolkit/renderers#PcbSvgRenderer.render() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+
+## simulation.spice
+
+| 1.0.17 feature                                                   | Kind     | Disposition | 1.1.0 replacement                                      | Availability                                                          |
+| ---------------------------------------------------------------- | -------- | ----------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
+| SPICE simulation returns deterministic transient graph summaries | behavior | shared      | circuitjson-toolkit/simulation#SimulationService.run() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+
+## validation.document
+
+| 1.0.17 feature                          | Kind     | Disposition | 1.1.0 replacement                                           | Availability                                                       |
+| --------------------------------------- | -------- | ----------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
+| validator rejects unknown element types | behavior | shared      | circuitjson-toolkit/parser#DocumentResult.createValidated() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |

package/docs/migration/parser.md

@@ -0,0 +1,60 @@
+# Parser entrypoint migration mappings
+
+This generated appendix contains 43 of the 1207 exhaustive
+1.0.17 to 1.1.0 feature mappings. Regenerate it with
+`npm run sync:migration`.
+
+[Back to the migration guide](../migration.md)
+
+## parse.document
+
+| 1.0.17 feature                                                             | Kind   | Disposition | 1.1.0 replacement                                             | Availability                                                          |
+| -------------------------------------------------------------------------- | ------ | ----------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
+| ./parser#CircuitJsonParser                                                 | export | shared      | circuitjson-toolkit/extensions#CircuitJsonParser              | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseBytes()                                    | method | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseBytes() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseBytes().argument.bytes                     | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseBytes() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseBytes().argument.options                   | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseBytes() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseBytes().argument.options.property.fileName | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseBytes() | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText()                                     | method | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().argument.options                    | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().argument.options.property.fileName  | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().argument.text                       | option | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.bom                          | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.diagnostics                  | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.fileName                     | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.fileType                     | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.kind                         | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.manufacturing                | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+| ./parser#CircuitJsonParser.parseText().result.supportMatrix                | field  | shared      | circuitjson-toolkit/extensions#CircuitJsonParser.parseText()  | CircuitJSON: shared; Gerber: derived; Altium: derived; KiCad: derived |
+
+## validation.document
+
+| 1.0.17 feature                                                                         | Kind   | Disposition | 1.1.0 replacement                                        | Availability                                                       |
+| -------------------------------------------------------------------------------------- | ------ | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
+| ./parser#CircuitJsonDocument                                                           | export | shared      | circuitjson-toolkit#CircuitJsonDocument                  | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.assertModel()                                             | method | shared      | circuitjson-toolkit#CircuitJsonDocument.assertModel()    | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.assertModel().argument.value                              | option | shared      | circuitjson-toolkit#CircuitJsonDocument.assertModel()    | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata()                                          | method | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.circuitJson                     | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata                        | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.bom           | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.diagnostics   | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.fileName      | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.fileType      | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.kind          | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.manufacturing | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().argument.metadata.property.supportMatrix | option | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.bom                               | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.diagnostics                       | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.fileName                          | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.fileType                          | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.kind                              | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.manufacturing                     | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.sourceFormat                      | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.attachMetadata().result.supportMatrix                     | field  | shared      | circuitjson-toolkit#CircuitJsonDocument.attachMetadata() | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.isElement()                                               | method | shared      | circuitjson-toolkit#CircuitJsonDocument.isElement()      | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.isElement().argument.value                                | option | shared      | circuitjson-toolkit#CircuitJsonDocument.isElement()      | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.isModel()                                                 | method | shared      | circuitjson-toolkit#CircuitJsonDocument.isModel()        | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.isModel().argument.value                                  | option | shared      | circuitjson-toolkit#CircuitJsonDocument.isModel()        | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.validateModel()                                           | method | shared      | circuitjson-toolkit#CircuitJsonDocument.validateModel()  | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |
+| ./parser#CircuitJsonDocument.validateModel().argument.value                            | option | shared      | circuitjson-toolkit#CircuitJsonDocument.validateModel()  | CircuitJSON: shared; Gerber: shared; Altium: shared; KiCad: shared |