altium-toolkit 0.1.1 → 0.1.16

package/README.md

@@ -10,14 +10,24 @@ Altium Toolkit is an ESM JavaScript library for parsing native Altium
 schematic and PCB documents and rendering deterministic, non-interactive
 outputs from the recovered model.
 
-The package was extracted from ECAD Forge so parser behavior, normalized model
-shape, and renderer output can be reused by other browser or Node-based tools.
+The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
+is used for browser-based Altium document parsing and deterministic render
+output. Its parser behavior, normalized model shape, and renderer output can be
+reused by other browser or Node-based tools.
 
 ## Features
 
-- Parse standalone native `.SchDoc` and `.PcbDoc` files from `ArrayBuffer`
-- Recover schematic records, PCB outlines, placements, primitives, embedded
-  schematic images, and embedded PCB STEP payload metadata
+- Parse standalone native `.SchDoc`, `.PcbDoc`, `.PcbLib`, and `.PrjPcb` 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
+- 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
 - Render schematic SVG, PCB SVG, and grouped BOM HTML
 - Build non-interactive PCB 3D scene-description data for host applications
 - Render a static 3D board summary
@@ -25,6 +35,9 @@ shape, and renderer output can be reused by other browser or Node-based tools.
 
 ## Install
 
+The package is published on npm as
+[`altium-toolkit`](https://www.npmjs.com/package/altium-toolkit).
+
 ```bash
 npm install altium-toolkit
 ```
@@ -36,14 +49,18 @@ import {
     AltiumParser,
     SchematicSvgRenderer,
     PcbSvgRenderer,
+    preparePcbSideResolvedRenderModel,
     BomTableRenderer,
     PcbScene3dBuilder
 } from 'altium-toolkit'
 
 const documentModel = AltiumParser.parseArrayBuffer(file.name, arrayBuffer)
+const backRenderModel = preparePcbSideResolvedRenderModel(documentModel, {
+    side: 'back'
+})
 
 const schematicMarkup = SchematicSvgRenderer.render(documentModel)
-const pcbMarkup = PcbSvgRenderer.render(documentModel)
+const pcbMarkup = PcbSvgRenderer.render(backRenderModel)
 const bomMarkup = BomTableRenderer.render(documentModel.bom || [])
 const sceneDescription = PcbScene3dBuilder.build(documentModel)
 ```
@@ -58,6 +75,7 @@ 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)
 - [Testing](docs/testing.md)
 - [Scope](spec/library-scope.md)
 

package/docs/api.md

@@ -27,10 +27,41 @@ import { AltiumParser } from 'altium-toolkit/parser'
 const documentModel = AltiumParser.parseArrayBuffer(fileName, arrayBuffer)
 ```
 
-`fileName` is used to infer schematic versus PCB parsing from the extension.
-The parser accepts native `.SchDoc` and `.PcbDoc` document bytes as an
-`ArrayBuffer` and returns the normalized model described in
-[Model Format](model-format.md).
+`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.
+
+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
+normalized component list and BOM are built.
+
+```js
+import { NormalizedModelSchema } from 'altium-toolkit/parser'
+
+if (documentModel.schema !== NormalizedModelSchema.CURRENT_SCHEMA_ID) {
+    throw new Error('Unsupported normalized model schema')
+}
+```
+
+Specialized parser helpers are exported for lower-level integrations, including
+`PcbBoardRegionSemanticsParser`, `PcbComponentPrimitiveIndexer`,
+`PcbEmbeddedFontExtractor`, `PcbFontMetricsParser`, `PcbPadStackParser`,
+`PcbViaStackParser`, `PcbRuleParser`, and `PcbRawRecordRegistry`.
+`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
+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.
 
 ## Renderers
 
@@ -38,12 +69,19 @@ The parser accepts native `.SchDoc` and `.PcbDoc` document bytes as an
 import {
     SchematicSvgRenderer,
     PcbSvgRenderer,
+    PcbSideResolvedRenderModel,
+    preparePcbSideResolvedRenderModel,
     BomTableRenderer
 } from 'altium-toolkit/renderers'
 ```
 
 - `SchematicSvgRenderer.render(documentModel)` returns schematic SVG markup.
 - `PcbSvgRenderer.render(documentModel)` returns PCB SVG markup.
+- `PcbSideResolvedRenderModel.resolve(documentModel, { side })` and
+  `preparePcbSideResolvedRenderModel(documentModel, { side })` return a
+  side-specific PCB render model for top-oriented renderers. Use
+  `side: 'back'` to project bottom components, documentation layers, copper
+  primitives, vias, and pad stack geometry into the top-facing render surface.
 - `BomTableRenderer.render(rows)` returns grouped BOM table markup.
 
 Renderer output is deterministic string markup. The library does not attach DOM

package/docs/model-format.md

@@ -11,11 +11,22 @@ The parser returns one object per parsed native document.
 
 ## Common Fields
 
-- `kind`: `schematic` or `pcb`
+- `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`
 - `fileName`: original file name passed to the parser
 - `diagnostics`: parser warnings and recovery notes
 - `bom`: grouped component metadata where available
 
+## Schema Contracts
+
+The current root model 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`.
+
 ## Schematic Fields
 
 Schematic documents include recovered `schematic` data with sheet metadata,
@@ -27,10 +38,89 @@ the SVG renderer maps them into SVG space.
 
 PCB documents include recovered `pcb` data with board outline geometry,
 component placements, layer metadata, primitive detail, copper, pads, vias,
-fills, arcs, embedded model references, and model body placement metadata.
+fills, arcs, embedded model references, model body placement metadata,
+`embeddedFonts`, and `rawRecords`. Embedded font entries include the recovered
+family/style, source stream, self-contained base64 payload, TrueType/OpenType
+format hint, MIME type, byte counts, and basic sfnt metrics such as
+units-per-em, ascent, descent, cell height, cap height, average advance width,
+and weight class. Decoded TrueType PCB text primitives may reference these
+metrics through `embeddedFontIndex` and `fontMetrics`. Raw record entries expose
+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.
+
+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
+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.
+
+Component annotations may also include `uniqueId`, `parameters`, and
+`parameterSource` when the PCB contains `PrimitiveParameters/Data` entries keyed
+by the component primitive ID. Modern Texts6 designator records are resolved
+through `WideStrings6/Data` when Altium stores the display string in that table;
+when such a Texts6 designator differs from `SOURCEDESIGNATOR`, the public
+component uses the displayed designator and preserves the original value in
+`baseDesignator` with `displayDesignator` and `designatorSource` metadata.
+Component-owned Texts6 comment/value records are marked with `role: 'comment'`
+and `isComment`; unresolved annotation slots are additionally marked with
+`isPlaceholder`.
+
+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
+`padShapeNames`. Extended pad records also expose named hole shapes, normalized
+`holeGeometry` for round/square/slot drills, merged `middleLayerPads` entries
+that combine middle-layer size and effective shape data, per-layer shape names,
+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.
+
+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`.
+
+Board-planning regions are decoded separately from copper regions through
+`pcb.boardRegions`. These entries retain their contour geometry and now add
+rigid-flex semantics from BoardRegions/Data properties: `objectKind`, `name`,
+`layerStackId`, `substackIndex`, `substackName`, flex/rigid flags, `locked3d`,
+`cavityHeight`, and typed `bendingLines`. Bend lines preserve the raw
+semicolon-delimited payload while exposing angle, radius, fold index, endpoint
+coordinates, and calculated affected width in mils. Board-level substack
+metadata is exposed in `pcb.layerSubstacks`, and
+`pcb.boardRegionContexts` provides a compact region-to-substack lookup for
+callers that do not need the full geometry.
+
+## PCB Library Fields
+
+PCB footprint libraries include recovered `pcbLibrary` data with library header
+properties, optional SectionKeys mappings, ComponentParamsTOC entries, and an
+ordered `footprints` list. Each footprint exposes its source storage name,
+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.
+
+## Project Fields
+
+PCB projects include recovered `project` data from `.PrjPcb` files. The parser
+preserves raw INI sections while also exposing normalized document entries,
+document groups, project parameters, project variants, configurations, and
+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`.
 
 ## Compatibility Rule
 
-Consumers should treat unknown fields as additive. Parser fixes may add detail,
-but existing field names and shapes should stay compatible unless a major
-version explicitly documents a model migration.
+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.