altium-toolkit 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Altium Toolkit
+
+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.
+
+## 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
+- 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
+- Run entirely with local input data; no network calls are made by the parser
+
+## Install
+
+```bash
+npm install altium-toolkit
+```
+
+## Usage
+
+```js
+import {
+    AltiumParser,
+    SchematicSvgRenderer,
+    PcbSvgRenderer,
+    BomTableRenderer,
+    PcbScene3dBuilder
+} from 'altium-toolkit'
+
+const documentModel = AltiumParser.parseArrayBuffer(file.name, arrayBuffer)
+
+const schematicMarkup = SchematicSvgRenderer.render(documentModel)
+const pcbMarkup = PcbSvgRenderer.render(documentModel)
+const bomMarkup = BomTableRenderer.render(documentModel.bom || [])
+const sceneDescription = PcbScene3dBuilder.build(documentModel)
+```
+
+Optional renderer CSS is available through:
+
+```js
+import 'altium-toolkit/styles/altium-renderers.css'
+```
+
+## Documentation
+
+- [API](docs/api.md)
+- [Model Format](docs/model-format.md)
+- [Testing](docs/testing.md)
+- [Scope](spec/library-scope.md)
+
+## Examples
+
+- [Arduino Uno Altium example](examples/arduino-uno/) based on Mehdi
+  KHALFALLAH's public
+  [My-Arduino-UNO-Design](https://github.com/Mehdi-KHALFALLAH/My-Arduino-UNO-Design)
+  project. The example fetches credited source documents from
+  `raw.githubusercontent.com` at runtime and does not redistribute them.
+
+Run the local example server with:
+
+```bash
+npm start
+```
+
+## Test
+
+```bash
+npm test
+```
+
+The test suite uses repo-owned, obfuscated fixture shards only. Do not add
+native customer, vendor, or source project files to this repository.
+
+## License
+
+This project is available under two licensing options.
+
+### 1. Open-source software license
+
+GNU General Public License v3.0 or later (`GPL-3.0-or-later`).
+
+You may use, modify, and distribute this project under the GPL. If you
+distribute modified versions or larger works based on this project, they must
+comply with the GPL, including source-code availability requirements.
+
+### 2. Commercial/proprietary license
+
+For use in closed-source, proprietary, or otherwise GPL-incompatible products,
+a separate paid commercial license is required.
+
+Commercial licensing contact: https://github.com/SunboX
+
+### Documentation and notices
+
+Documentation and non-code text are licensed under Creative Commons
+Attribution-ShareAlike 4.0 (`CC-BY-SA-4.0`) unless otherwise marked.
+
+Copyright (C) 2026 André Fiedler.
+
+Copyright, license, attribution, and source-origin notices must be preserved as
+required by the GPL, CC-BY-SA-4.0, and the notice files in this repository.
+See [LICENSE](LICENSE), [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md), and
+[NOTICE.md](NOTICE.md).

package/docs/api.md

@@ -0,0 +1,73 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# API
+
+## Entrypoints
+
+`altium-toolkit` exports the supported parser, renderer, and 3D
+scene-description classes from one entrypoint.
+
+Specialized entrypoints are also available:
+
+- `altium-toolkit/parser`
+- `altium-toolkit/renderers`
+- `altium-toolkit/scene3d`
+- `altium-toolkit/workers/altium-parser.worker.mjs`
+- `altium-toolkit/styles/altium-renderers.css`
+
+## Parser
+
+```js
+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).
+
+## Renderers
+
+```js
+import {
+    SchematicSvgRenderer,
+    PcbSvgRenderer,
+    BomTableRenderer
+} from 'altium-toolkit/renderers'
+```
+
+- `SchematicSvgRenderer.render(documentModel)` returns schematic SVG markup.
+- `PcbSvgRenderer.render(documentModel)` returns PCB SVG markup.
+- `BomTableRenderer.render(rows)` returns grouped BOM table markup.
+
+Renderer output is deterministic string markup. The library does not attach DOM
+events or mutate a host document.
+
+## 3D Scene Data
+
+```js
+import {
+    PcbScene3dBuilder,
+    PcbScene3dModelRegistry,
+    PcbScene3dScenePreparator,
+    PcbScene3dSummaryRenderer
+} from 'altium-toolkit/scene3d'
+```
+
+- `PcbScene3dBuilder.build(documentModel, options)` returns procedural board,
+  placement, copper, silkscreen, and external-model scene-description data.
+- `PcbScene3dModelRegistry` resolves embedded or session model candidates for
+  component placements.
+- `PcbScene3dScenePreparator.prepare(documentModel, options)` prepares the same
+  scene-description data behind an async API suitable for host workers.
+- `PcbScene3dSummaryRenderer.render(documentModel)` returns static 3D summary
+  HTML.
+
+The library intentionally does not create Three.js objects, canvases, controls,
+or event listeners.

package/docs/model-format.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Model Format
+
+The normalized model is intentionally stable with the ECAD Forge parser model.
+The parser returns one object per parsed native document.
+
+## Common Fields
+
+- `kind`: `schematic` or `pcb`
+- `fileName`: original file name passed to the parser
+- `diagnostics`: parser warnings and recovery notes
+- `bom`: grouped component metadata where available
+
+## Schematic Fields
+
+Schematic documents include recovered `schematic` data with sheet metadata,
+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.
+
+## PCB Fields
+
+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.
+
+## 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.

package/docs/testing.md

@@ -0,0 +1,25 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Testing
+
+Run the complete suite:
+
+```bash
+npm test
+```
+
+The tests cover:
+
+- Binary and OLE helpers
+- Printable and binary Altium parser recovery
+- Obfuscated fake schematic and PCB fixture shards
+- Schematic SVG, PCB SVG, BOM HTML, and static 3D summary renderers
+- Non-interactive PCB 3D scene-description builders and model registry logic
+
+Fixture data must remain repo-owned and obfuscated. Do not add native provided
+Altium files, real customer identifiers, real vendor identifiers, or
+source-descriptive fixture names.

package/examples/README.md

@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2026 André Fiedler
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Examples
+
+## Arduino Uno
+
+The `arduino-uno` example is a browser page for loading `.SchDoc` and
+`.PcbDoc` files locally and rendering the recovered schematic, PCB, BOM,
+interactive Three.js PCB view, and static 3D summary outputs. It automatically
+fetches the credited source schematic and source PCB from GitHub at startup.
+
+It is based on the public
+[My-Arduino-UNO-Design](https://github.com/Mehdi-KHALFALLAH/My-Arduino-UNO-Design)
+Altium project by Mehdi KHALFALLAH. Credit for that Arduino Uno Altium design
+belongs to Mehdi KHALFALLAH.
+
+The example does not redistribute Mehdi KHALFALLAH's Altium project files,
+screenshots, datasheets, or manufacturing outputs. The browser fetches selected
+source `.SchDoc` and `.PcbDoc` files from `raw.githubusercontent.com` at runtime.
+You can also load local files downloaded from the original project.
+
+From the repository root, start the local example server:
+
+```bash
+npm start
+```
+
+Then visit:
+
+```text
+http://localhost:4173/examples/arduino-uno/
+```
+
+The server binds to `127.0.0.1` by default. Override it with `HOST` or `PORT`
+when needed:
+
+```bash
+PORT=4174 npm start
+```
+
+The parser and renderers remain local-first library code. This example page
+explicitly makes outbound runtime requests to `raw.githubusercontent.com` only
+for the credited source demo files.