altium-toolkit 1.0.8 → 1.0.10

package/README.md

@@ -18,20 +18,30 @@ browser or Node-based tools.
 
 ## Features
 
-- Parse standalone native `.SchDoc`, `.PcbDoc`, `.PcbLib`, and `.PrjPcb` files from
-  `ArrayBuffer`
+- Parse standalone native `.SchDoc`, `.PcbDoc`, `.PcbLib`, `.PrjPcb`, and
+  `.IntLib` files from `ArrayBuffer`
 - Recover schematic records, PCB outlines, placements, PCB library footprints,
   project document references, variants, parameters, primitives, embedded
   schematic images, component annotations from PrimitiveParameters/Text streams,
-  embedded PCB STEP payload metadata, and embedded PCB/PcbLib font payloads with
-  basic text metrics
+  PCB pad/via stack and hole-tolerance detail, via-protection sidecars, custom
+  pad shape links, extended mask/paste sidecars, PCB union metadata, embedded
+  PCB 3D payload metadata, PCB component provenance, differential-pair class
+  joins, schematic directive semantics, barcode PCB text metadata, mechanical
+  layer pairs, pick-and-place coordinate modes, PCB dimensions, project
+  class-generation policy, project-level design bundles, annotation mappings,
+  effective variant views, schematic/PCB ownership sidecars, deterministic
+  wirelist/netlist exports, library render manifests, library lookup indexes,
+  schematic project-parameter text resolution, PCB QA statistics, structured
+  diagnostics, and embedded PCB/PcbLib font payloads with basic text metrics
 - Preserve raw PCB primitive records through a read-only record registry so
   unsupported or partially decoded stream data remains inspectable
 - 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
+- Render semantically annotated schematic SVG, semantically annotated PCB SVG,
+  deterministic per-layer PCB SVG exports, and grouped BOM HTML
 - Build non-interactive PCB 3D scene-description data for host applications,
-  including refined board outlines and silkscreen drill cutouts
+  including refined board outlines, silkscreen drill cutouts, and external
+  model projection diagnostics
 - Render a static 3D board summary
 - Run entirely with local input data; no network calls are made by the parser
 
@@ -78,6 +88,8 @@ import 'altium-toolkit/styles/altium-renderers.css'
 - [API](docs/api.md)
 - [Model Format](docs/model-format.md)
 - [Normalized Model Schema](docs/schemas/altium_toolkit/normalized_model_a1.schema.json)
+- [Project Bundle Schema](docs/schemas/altium_toolkit/project_bundle_a1.schema.json)
+- [Netlist Schema](docs/schemas/altium_toolkit/netlist_a1.schema.json)
 - [Testing](docs/testing.md)
 - [Scope](spec/library-scope.md)
 

package/docs/api.md

@@ -28,18 +28,22 @@ import { AltiumParser } from 'altium-toolkit/parser'
 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 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.
+`fileName` is used to infer schematic, PCB document, PCB footprint-library, PCB
+project, or integrated-library parsing from the extension. The parser accepts
+native `.SchDoc`, `.PcbDoc`, `.PcbLib`, `.PrjPcb`, and `.IntLib` 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`, `integratedLibrary`, `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
-joined by native primitive unique id, and modern `Texts6` designator records may
-resolve their display string through the wide-string table before the
+as `PrimitiveParameters/Data`, `WideStrings6/Data`,
+`ExtendedPrimitiveInformation/Data`, `CustomShapes/Data`, `UnionNames/Data`,
+and `SmartUnions/Data`. Component parameters are joined by native primitive
+unique id, modern `Texts6` designator records may resolve their display string
+through the wide-string table, custom pad geometry is linked to anchor pads, and
+smart-union memberships are attached to referenced primitives before the
 normalized component list and BOM are built.
 
 ```js
@@ -56,19 +60,52 @@ an integration still needs the legacy renderer model object. The
 `toRendererModel()`, and `isCircuitJson()` for explicit conversions.
 
 Specialized parser helpers are exported for lower-level integrations, including
-`PcbBoardRegionSemanticsParser`, `PcbComponentPrimitiveIndexer`,
-`PcbEmbeddedFontExtractor`, `PcbFontMetricsParser`, `PcbPadStackParser`,
-`PcbViaStackParser`, `PcbRuleParser`, and `PcbRawRecordRegistry`.
+`IntLibStreamExtractor`, `PcbBoardRegionSemanticsParser`,
+`PcbComponentPrimitiveIndexer`, `PcbCustomPadShapeParser`,
+`PcbDimensionParser`, `PcbEmbeddedFontExtractor`,
+`PcbExtendedPrimitiveInformationParser`, `PcbFontMetricsParser`,
+`LibraryRenderManifestBuilder`, `LibrarySearchIndex`,
+`PcbOwnershipGraphBuilder`, `PcbPadStackParser`,
+`PcbPickPlacePositionResolver`,
+`ProjectAnnotationParser`, `ProjectDesignBundleBuilder`,
+`ProjectNetlistExporter`, `ProjectVariantViewBuilder`,
+`PcbMechanicalLayerPairParser`, `PcbSpecialStringResolver`, `PcbUnionParser`,
+`PcbViaStackParser`, `PcbRuleParser`, `PcbRawRecordRegistry`,
+`PcbStatisticsBuilder`, `SchematicOwnershipGraphParser`, and
+`SchematicProjectParameterResolver`.
 `PcbBoardRegionSemanticsParser` exposes the substack and bending-line
 normalization used by `.PcbDoc` models. `PcbComponentPrimitiveIndexer` exposes
 the native component-index grouping used to populate
 `pcb.componentPrimitives` and `pcb.componentPrimitiveGroups`. The pad, via, and
 rule helpers expose the same mask/cache, stack, and typed-constraint
-normalization used by `.PcbDoc` parsing. The font helpers expose the same
+normalization used by `.PcbDoc` parsing. `PcbDimensionParser` exposes the
+parser-only Dimensions6 normalization used by `.PcbDoc` parsing.
+`SchematicOwnershipGraphParser` and `PcbOwnershipGraphBuilder` expose the
+read-only ownership sidecars that parser roots attach under
+`schematic.ownership` and `pcb.ownership`.
+`PcbPickPlacePositionResolver` exposes the component-origin and pad-anchor
+coordinate modes used by the normalized `pnp` model.
+`ProjectDesignBundleBuilder` composes separately parsed project, schematic, and
+PCB models into a project-level JSON bundle, and
+`ProjectVariantViewBuilder` applies DNP, alternate fitted rows, parameter
+overrides, and annotation designator mappings to bundle BOM, PnP, component,
+and net views. `ProjectAnnotationParser` parses read-only annotation mapping
+files, and `ProjectNetlistExporter` emits deterministic wirelist and richer
+JSON netlist contracts from normalized bundles. The JSON contract includes
+schematic source sheets, graphical elements, aliases, terminal endpoints,
+hierarchy paths, and PCB net-table provenance when present.
+`PcbMechanicalLayerPairParser`
+exposes the mechanical-layer flip map used by `.PcbDoc` parsing. The font
+helpers expose the same
 embedded font payload and metric shape that `.PcbDoc` and `.PcbLib` parsing adds
 to normalized models. `PcbRawRecordRegistry` exposes immutable primitive stream
 descriptors and the raw-record preservation helpers used by the PcbDoc/PcbLib
 extractors.
+`LibraryRenderManifestBuilder` and `LibrarySearchIndex` expose deterministic
+SchLib/PcbLib render/export manifests plus exact, keyword, and fuzzy lookup
+helpers. `PcbStatisticsBuilder` emits board QA summaries used by `.PcbDoc`
+models. `SchematicProjectParameterResolver` resolves dot-prefixed and
+equals-prefixed schematic special strings for parser and SVG integrations.
 
 ## Netlist Query
 
@@ -111,8 +148,13 @@ import {
 } from 'altium-toolkit/renderers'
 ```
 
-- `SchematicSvgRenderer.render(documentModel)` returns schematic SVG markup.
+- `SchematicSvgRenderer.render(documentModel, options)` returns schematic SVG
+  markup. Pass `options.projectParameters` to resolve schematic special strings
+  in visible text and title-block fields during rendering.
 - `PcbSvgRenderer.render(documentModel)` returns PCB SVG markup.
+- `PcbSvgRenderer.renderLayerSvgs(documentModel)` returns deterministic
+  per-layer PCB SVG entries with layer descriptors and layer-filtered SVG
+  markup.
 - `PcbSideResolvedRenderModel.resolve(documentModel, { side })` and
   `preparePcbSideResolvedRenderModel(documentModel, { side })` return a
   side-specific PCB render model for top-oriented renderers. Use
@@ -123,6 +165,23 @@ import {
 Renderer output is deterministic string markup. The library does not attach DOM
 events or mutate a host document.
 
+Schematic SVG output includes stable semantic `data-*` attributes on recovered
+wire, label, pin, and fallback component elements when source metadata is
+available. The embedded `schematic-semantic-metadata` JSON sidecar uses schema
+`altium-toolkit.schematic.svg.semantics.a1` and links element keys to nets,
+components, and pins for downstream highlighting.
+
+PCB SVG output includes stable semantic `data-*` attributes on recovered board,
+copper, pad, via, component, and text elements. The embedded
+`pcb-semantic-metadata` JSON sidecar uses schema
+`altium-toolkit.pcb.svg.semantics.a1` and links SVG element keys to primitive
+kind, layer, net/class, component, pad number, hole ownership, and board-outline
+identity where that metadata is available. The same sidecar also records view
+context, including board centroid, included layer ids, layer roles, cutouts, and
+pad/via drill render state (`open`, `covered`, `filled`, or `capped`).
+`PcbSvgRenderer.renderLayerSvgs()` uses the same semantic sidecar shape with
+`view.kind: 'layer'` and a layer-specific `layerSet`.
+
 ## 3D Scene Data
 
 ```js
@@ -138,7 +197,10 @@ import {
   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.
+  `drillCutouts` plus fill holes for drilled pads and vias. External model
+  placements include `projection` diagnostics indicating whether bounds came
+  from authored overrides, resolved model bounds, nearby pad spans, procedural
+  component fallback, or only the model anchor.
 - `PcbScene3dModelRegistry` resolves embedded or session model candidates for
   component placements.
 - `PcbScene3dScenePreparator.prepare(documentModel, options)` prepares the same

package/docs/model-format.md

@@ -35,10 +35,13 @@ the object form can call
 
 - `schema`: normalized model schema id, currently
   `urn:altium-toolkit:normalized-model:a1`
-- `kind`: `schematic`, `pcb`, `pcb-library`, or `project`
-- `fileType`: `SchDoc`, `PcbDoc`, `PcbLib`, or `PrjPcb`
+- `kind`: `schematic`, `pcb`, `pcb-library`, `project`,
+  `integrated-library`, or `design-bundle`
+- `fileType`: `SchDoc`, `PcbDoc`, `PcbLib`, `PrjPcb`, `IntLib`, or
+  `ProjectDesignBundle`
 - `fileName`: original file name passed to the parser
-- `diagnostics`: parser warnings and recovery notes
+- `diagnostics`: parser warnings and recovery notes. Each diagnostic carries a
+  machine-readable `code` plus `severity` and `message`.
 - `bom`: grouped component metadata where available
 
 ## Schema Contracts
@@ -58,6 +61,61 @@ primitives, wires, labels, power ports, sheet symbols, images, net metadata, and
 component ownership hints. Coordinates remain in recovered document units until
 the SVG renderer maps them into SVG space.
 
+`schematic.recordTypes` summarizes the native schematic `RECORD` ids seen in
+the document. Each entry includes the numeric `recordType`, stable `name`,
+semantic `family`, parser `supported` flag, and observed `count`. Bezier and
+pie-chart primitives are exposed as first-class `schematic.beziers` and
+`schematic.pies` arrays for deterministic SVG rendering. Rounded rectangles are
+exposed through `schematic.roundedRectangles`, and IEEE drawing symbols are
+exposed through `schematic.ieeeSymbols` with a stable `symbolName`. The registry
+also names schematic families such as notes, compile masks, harness records,
+blankets, and hyperlinks so consumers can inspect supported parser coverage
+without stringly typed local maps.
+
+Record-28 text frames are preserved both as drawable note text and as a
+read-only `schematic.textFrames` contract with frame rectangle, alignment,
+border width, fill/border state, font, margin, and render-order metadata.
+Polyline records preserve authored endpoint marker kind and size on the first
+and last rendered segment when present.
+
+`schematic.directiveSemantics` exposes first-class schematic directives beside
+their drawable geometry. It groups No ERC markers, parameter sets,
+differential-pair directives, compile masks, and blankets. Parameter sets carry
+owner-linked child parameter rows and a `parameterMap`, which lets consumers
+distinguish hidden directive metadata from visible sheet text.
+
+`schematic.ownership` is a read-only sidecar built from raw record
+`OwnerIndex` and `IndexInSheet` values. It exposes stable record keys,
+`childrenByParentKey`, `parentsByChildKey`, and `recordsByIndexInSheet` so
+consumers can inspect component, sheet-symbol, and directive children without
+reimplementing owner-index lookup rules.
+
+Schematic project parameters and special strings can be resolved without
+mutating source parser models through `SchematicProjectParameterResolver`.
+The resolver supports dot-prefixed project parameters, equals-prefixed template
+fields, and simple quoted-literal concatenation expressions. Schematic SVG
+rendering accepts `projectParameters` and uses the resolver for visible sheet
+text and title-block fields.
+
+`schematic.renderDiagnostics` is an optional structured sidecar for rendering
+fallback decisions. Font-family fallbacks are emitted with code
+`schematic.font.family-fallback`, the raw source family, resolved deterministic
+family, and matching top-level warning diagnostic.
+
+The normalized schematic net model is single-sheet. `schematic.nets` is built
+from the wires, labels, ports, pins, junctions, bus entries, and sheet entries
+present in the parsed `.SchDoc`. Project-level hierarchy, repeated channels,
+variants, and cross-sheet compilation metadata are preserved through the
+`.PrjPcb` parser, but this schema does not currently emit a compiled
+multi-sheet design netlist.
+
+Embedded schematic images preserve the raw record geometry and expose
+browser-facing payload metadata. When an embedded stream contains a native
+PNG/JPEG/GIF/SVG/WebP payload alongside a preview, `mimeType` and `dataBase64`
+refer to the native payload while `sourceMimeType` records the preview format.
+Alpha-bearing 32-bit BMP previews are converted to PNG and marked with
+`hasAlpha` so SVG renderers can display transparency deterministically.
+
 ## PCB Fields
 
 PCB documents include recovered `pcb` data with board outline geometry,
@@ -73,6 +131,19 @@ the registry id, source stream, primitive family/type, byte offsets, byte
 counts, parse status, encoding style, and a base64 payload for unsupported or
 partially decoded primitive stream data.
 
+Barcode PCB text records preserve their barcode kind, render mode, authored
+full size, margins, minimum bar width, show-text flag, and inverted state. SVG
+rendering uses those fields to emit deterministic vector barcode groups with
+semantic data attributes.
+
+`pcb.mechanicalLayerPairs` lists paired mechanical layer ids and display names.
+`pcb.layerFlipMetadata.mechanicalFlipMap` gives the bidirectional layer-id map
+needed when bottom-side components or footprints are mirrored between paired
+mechanical overlays.
+
+PCB printable and sidecar property streams are decoded as UTF-8 first, with
+Windows-1252 and GB18030 fallbacks for legacy text-backed properties.
+
 Component-owned PCB primitives are exposed directly from native Altium owner
 indexes. `pcb.componentPrimitives[componentIndex]` returns the grouped pads,
 tracks, arcs, fills, vias, regions, texts, and component bodies linked to that
@@ -80,6 +151,10 @@ component; missing sparse component indexes are represented as `null`. The
 compatibility list `pcb.componentPrimitiveGroups` carries the same group objects
 in placement order. Board-owned or net-owned primitives without a native
 `componentIndex` are intentionally left out of these component groups.
+`pcb.ownership` is the broader primitive ownership sidecar. It groups public
+primitive keys by component index, net index, and polygon index, while
+`primitiveOwners` records the component/net/polygon owner for each decoded
+primitive where that metadata exists.
 
 Component annotations may also include `uniqueId`, `parameters`, and
 `parameterSource` when the PCB contains `PrimitiveParameters/Data` entries keyed
@@ -92,6 +167,29 @@ Component-owned Texts6 comment/value records are marked with `role: 'comment'`
 and `isComment`; unresolved annotation slots are additionally marked with
 `isPlaceholder`.
 
+Component rows may include schematic and library provenance in
+`component.provenance`: channel offsets, source unique-id and hierarchy
+segments, source library references, footprint descriptions, annotation
+autoposition values, and pin/part swapping flags. This metadata is read-only
+and is carried before any project-level schematic compilation is attempted.
+
+Pick-and-place coordinates are exposed as `pnp` at the model root and mirrored
+under `pcb.pickPlace`. The default `positionMode` is `altium-pick-place`, which
+uses the center of component-owned pad anchors when available and falls back to
+the component origin. `pnp.modes.componentOrigin.entries` exposes the same
+components using authored component-origin coordinates. Entries preserve the
+authored component rotation while using the normalized PCB coordinate frame.
+
+`pcb.statistics` provides a deterministic board QA summary for regression
+diffs and reports. It includes outline dimensions and centroid, drill and slot
+counts, plated/non-plated hole counts, primitive-width histograms, and a
+layer-stack summary with per-layer primitive counts. When stack metadata is
+available, layer entries also carry material, copper thickness/weight,
+dielectric thickness, dielectric constant, and dissipation factor, plus
+aggregate material and role counts. The `planning` section summarizes keepout
+regions, room-related rules and names, board-region flex/rigid counts, locked
+3D regions, bending-line counts, and board-region layer-stack usage.
+
 Decoded pad primitives preserve raw `padFlags` plus named tenting and testpoint
 flags. Pad shape codes are kept as raw `shapeTop` / `shapeMid` / `shapeBottom`
 values and mirrored through normalized `shape*Name` labels plus
@@ -102,14 +200,64 @@ pad-cache thermal-relief fields through `padCache`, corrected cache-validity
 fields for plane/thermal/power relief, raw paste/solder mask modes, effective
 mask expansions, and side-specific `hasTop*MaskOpening` /
 `hasBottom*MaskOpening` booleans for renderers that need layer-accurate paste
-and solder-mask decisions.
+and solder-mask decisions. Pad and via drill tolerances use
+`positiveTolerance`, `negativeTolerance`, and grouped `holeTolerance`; unset
+native sentinel values are omitted instead of exposed as numeric mil values.
+
+Decoded via primitives preserve stack mode, per-layer diameters, removed-pad
+metadata, solder-mask-from-hole-edge flags, back solder-mask expansion,
+`drillLayerPairType`, optional `propagationDelayPs`, and sidecar-linked
+`viaProtection` metadata. `pcb.viaStructures` exposes the read-only sidecar
+contract: `structures` describes IPC-4761-style protection definitions and
+feature rows, `links` maps structure definitions to via primitive indexes, and
+`byPrimitiveIndex` provides the same lookup in object form.
+Linked via-protection records also add `drill` metadata to matching vias with
+`holeKind`, `plating`, `renderState`, and `ipc4761Type`. Render states are
+normalized as `open`, `covered`, `filled`, or `capped` for SVG and 3D
+consumers.
+
+PCB dimensions from `Dimensions6/Data` are exposed through `pcb.dimensions`.
+Dimension entries preserve native kind codes and raw fields while adding a
+normalized `kind` (`linear`, `angular`, `radial`, `datum`, `baseline`, or
+`ordinate`), reference points, optional text location, prefix/suffix, precision,
+measured value, angle value, and unit.
+
+`pcb.extendedPrimitiveInformation` exposes
+`ExtendedPrimitiveInformation/Data` entries keyed by primitive index and, when
+available, primitive object id. Matching decoded primitives receive an
+`extendedPrimitiveInformation` object with raw paste and solder mask-expansion
+modes, source labels, and manual expansion values.
+
+`pcb.customPadShapes` exposes `CustomShapes/Data` entries keyed by anchor pad
+primitive index. Matching normalized pads receive a `customShape` object whose
+layer entries reference the normalized region, shape-region, arc, track, and
+fill geometry that forms the custom pad shape.
+
+`pcb.unions` exposes `UnionNames/Data` and `SmartUnions/Data` metadata.
+Smart-union type ids are normalized to stable labels such as `via-stitching`,
+`via-shielding`, `drill-table`, `length-tuning`, and `layer-stack-table`.
+Primitive records referenced by smart unions receive `unionMemberships`.
+
+Differential-pair records are exposed through `pcb.differentialPairs`.
+`Classes6/Data` entries whose kind identifies differential-pair classes are
+joined into `pcb.differentialPairClasses`; each pair lists `classNames`, and
+each class lists resolved `pairNames` plus `unresolvedMembers` for members that
+were present in the class table but absent from `DifferentialPairs6/Data`.
+
+PCB text primitives preserve authored special-string expressions in `text`.
+When parser callers supply project parameters through extraction context,
+matched text records also expose `rawText`, `resolvedText`, and
+`specialString` metadata. The resolver supports dot-prefixed project parameter
+references and simple quoted-literal concatenation expressions.
 
 PCB design rules preserve native rule-specific `constraints` as strings and add
 typed views for common consumers. `ruleType` exposes a normalized rule kind and
 category, `constraintValues` parses common numeric units such as mil, mm, inch,
-degrees, percentages, and booleans, and `typedConstraints` maps common Width and
-Clearance rule fields to semantic names such as `minWidth`,
-`preferredWidth`, `maxWidth`, `minClearance`, and `genericClearance`.
+degrees, percentages, and booleans, and `typedConstraints` maps common rule
+fields to semantic names. Covered families include width, clearance, routing
+topology/corners/priority, fanout, length, matched length, solder-mask sliver,
+silkscreen clearances, component clearance, annular ring, vias-under-SMD,
+testpoint style, and testpoint usage rules.
 
 Board-planning regions are decoded separately from copper regions through
 `pcb.boardRegions`. These entries retain their contour geometry and now add
@@ -131,7 +279,23 @@ parameters, component metadata, primitive order, unknown record markers, and
 decoded pads, tracks, arcs, vias, fills, texts, and regions. Each footprint also
 preserves raw mixed-format primitive records with the same registry metadata
 shape used by PcbDoc raw records. Library-level `embeddedFonts` uses the same
-payload and metric shape as PCB documents.
+payload and metric shape as PCB documents. Library-level `embeddedModels` and
+`componentBodies` preserve embedded 3D payloads and body references when
+present.
+`pcbLibrary.indexes.footprintsByName` provides read-only footprint lookup and
+search metadata, including source storage, primitive counts, pad/text counts,
+and keyword tokens from footprint and component parameters. Footprint entries
+may also preserve implementation rows, component-model rows, and pin display
+mode metadata when those records are available from extraction.
+Footprints carry the same advanced field shapes as PCB documents when available:
+extended mask/paste sidecars attached to primitives, custom pad shape geometry,
+barcode text metadata, embedded model references, and projection diagnostics for
+component bodies. `pcbLibrary.renderManifest` exposes stable footprint SVG keys,
+per-layer SVG keys, layer descriptors, and embedded asset descriptors. Asset
+descriptors may include native format, wrapper type, byte size, checksum, and
+structured diagnostics when extraction supplied that metadata.
+`LibrarySearchIndex` provides exact, keyword, and fuzzy symbol/footprint lookup
+helpers over parsed library read models.
 
 ## Project Fields
 
@@ -142,9 +306,66 @@ output groups. Reachable schematic documents follow the durable project
 metadata convention used by Altium: schematic stubs with only `DocumentPath` and
 `DocumentUniqueId` remain listed, but richer schematic document entries are
 preferred in `project.documentGroups.reachableSchematics`.
+`project.classGeneration` preserves `[PrjClassGen]` policies and any
+per-document class-generation options, including differential-pair class and
+room-transfer policy flags when present.
+
+Project parsing is metadata-only. It does not load referenced schematics or
+emit a compiled multi-sheet netlist; consumers that need a design-wide netlist
+should combine project metadata with separately parsed schematic documents.
+
+`ProjectAnnotationParser` parses read-only annotation mapping files into
+`annotations.mappings`, `bySourceDesignator`, and `byCompiledDesignator`.
+`ProjectDesignBundleBuilder.build({ projectModel, documentModels,
+annotationModels })` composes already parsed project, schematic, PCB, and
+annotation models into a `design-bundle` payload. The bundle exposes `project`,
+`variants`, `sheets`, `components`, `schematic_hierarchy`, `pnp`, `nets`,
+`annotations`, and `indexes` so multi-document consumers can use one normalized
+JSON object above single-document parser output. Passing `variantName` adds
+`effectiveVariant`, which applies DNP rows, alternate fitted rows, parameter
+overrides, and annotation designator mappings to BOM, PnP, component, and net
+views without mutating the source parser models. `ProjectNetlistExporter` emits
+deterministic wirelist and JSON netlist contracts from the normalized bundle or
+effective variant view. The wirelist remains a compact line-oriented
+`component.pin` view. The JSON netlist also carries aliases, auto-named flags,
+schematic source sheets, graphical source elements, terminal endpoints,
+hierarchy paths, and PCB net-table provenance when the bundle includes those
+details.
+
+## SVG And 3D Contracts
+
+`PcbSvgRenderer.renderLayerSvgs(documentModel)` returns one layer descriptor and
+SVG string per recovered display layer. Layer SVGs use the same PCB semantic
+metadata sidecar as the composite SVG, with `view.kind` set to `layer`, a
+single included layer id, and `layerSet.layerView` describing the exported
+layer.
+
+External model placements in the 3D scene description include a `projection`
+diagnostic object. The `source` explains whether bounds came from an authored
+projection override, resolved model bounds, nearby pad-span fallback,
+procedural component fallback, or model-anchor fallback. The diagnostic does
+not alter placement coordinates.
+
+## Integrated Library Fields
+
+Integrated libraries include recovered `integratedLibrary` data from `.IntLib`
+compound documents. The parser preserves `Version.Txt`, cross-reference rows
+from `LibCrossRef.Txt`, parameter records from `Parameters   .bin`, and bundled
+source entries from schematic-symbol, PCB-footprint, and PCB-3D library
+folders. Source entries expose their stream path, file name, file type, library
+kind, compression wrapper, byte count, base64 payload, and printable payload
+text when the recovered bytes are text-like. Child source payloads are
+read-only; callers can parse extracted `.SchLib`, `.PcbLib`, or 3D library
+payloads with separate workflows where applicable.
+`integratedLibrary.indexes` adds source lookups by file name and source kind,
+plus cross-reference indexes that group schematic symbol and PCB footprint
+models by component.
 
 ## Compatibility Rule
 
 Consumers should treat unknown fields as additive within the same schema id.
 Parser fixes may add detail, but existing field names and shapes should stay
 compatible unless a new schema id explicitly documents a model migration.
+Focused machine-readable schemas are available under
+`docs/schemas/altium_toolkit/` for the normalized root, project bundle, netlist
+JSON, schematic SVG semantic metadata, and PCB SVG semantic metadata contracts.

package/docs/schemas/altium_toolkit/ci_artifact_bundle_a1.schema.json

@@ -0,0 +1,76 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "altium-toolkit.ci.artifact-bundle.a1",
+    "title": "Altium Toolkit CI Artifact Bundle A1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": [
+        "schema",
+        "summary",
+        "designBundle",
+        "documentGraph",
+        "normalizedModels",
+        "netlist",
+        "bom",
+        "pnp",
+        "schematicSvgs",
+        "pcbLayerSvgs",
+        "statistics",
+        "diagnostics"
+    ],
+    "properties": {
+        "schema": {
+            "const": "altium-toolkit.ci.artifact-bundle.a1"
+        },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true
+        },
+        "units": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "designBundle": {
+            "type": "object"
+        },
+        "documentGraph": {
+            "type": "object"
+        },
+        "normalizedModels": {
+            "type": "array"
+        },
+        "netlist": {
+            "type": "object",
+            "required": ["json", "wirelist"],
+            "properties": {
+                "json": {
+                    "type": "object"
+                },
+                "wirelist": {
+                    "type": "string"
+                }
+            },
+            "additionalProperties": true
+        },
+        "bom": {
+            "type": "object"
+        },
+        "pnp": {
+            "type": "object"
+        },
+        "schematicSvgs": {
+            "type": "array"
+        },
+        "pcbLayerSvgs": {
+            "type": "array"
+        },
+        "statistics": {
+            "type": "object"
+        },
+        "diagnostics": {
+            "type": "array"
+        }
+    }
+}

package/docs/schemas/altium_toolkit/draftsman_digest_a1.schema.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "altium-toolkit.draftsman.digest.a1",
+    "title": "Altium Toolkit Draftsman Digest A1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schema", "pages"],
+    "properties": {
+        "schema": {
+            "const": "altium-toolkit.draftsman.digest.a1"
+        },
+        "sourceDocumentName": {
+            "type": "string"
+        },
+        "pages": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": [
+                    "index",
+                    "title",
+                    "titleBlocks",
+                    "notes",
+                    "images",
+                    "unsupportedRawItems"
+                ]
+            }
+        },
+        "indexes": {
+            "type": "object",
+            "additionalProperties": true
+        }
+    }
+}

package/docs/schemas/altium_toolkit/netlist_a1.schema.json

@@ -0,0 +1,53 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "altium-toolkit.netlist.a1",
+    "title": "Altium Toolkit Netlist A1",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schema", "project", "nets"],
+    "properties": {
+        "schema": {
+            "const": "altium-toolkit.netlist.a1"
+        },
+        "project": {
+            "type": "string"
+        },
+        "units": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "nets": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["name", "pins"],
+                "properties": {
+                    "name": {
+                        "type": "string"
+                    },
+                    "aliases": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "autoNamed": {
+                        "type": "boolean"
+                    },
+                    "pins": {
+                        "type": "array"
+                    },
+                    "sources": {
+                        "type": "array"
+                    },
+                    "pcb": {
+                        "type": "array"
+                    }
+                }
+            }
+        }
+    }
+}