pcb-scene3d-viewer 1.0.1

package/docs/circuitjson.md

@@ -0,0 +1,190 @@
+# CircuitJSON Usage
+
+`pcb-scene3d-viewer` can render serialized CircuitJSON element arrays directly.
+Use this path when the host application already has CircuitJSON and does not
+need an Altium, KiCad, or other format-specific scene builder.
+
+## Direct Controller Input
+
+Pass the CircuitJSON array as the `documentModel`. The controller detects direct
+CircuitJSON input, converts it to the internal render model, and mounts the
+runtime without a `buildScene` callback.
+
+```js
+import {
+    PcbScene3dController,
+    PcbScene3dShellRenderer
+} from 'pcb-scene3d-viewer'
+
+const circuitJson = [
+    {
+        type: 'pcb_board',
+        width: 50,
+        height: 30,
+        thickness: 1.6,
+        center: { x: 25, y: 15 }
+    },
+    {
+        type: 'source_component',
+        id: 'source-r1',
+        name: 'R1',
+        ftype: 'R_0603'
+    },
+    {
+        type: 'pcb_component',
+        source_component_id: 'source-r1',
+        layer: 1,
+        center: { x: 20, y: 15 },
+        rotation: 90,
+        width: 1.6,
+        height: 0.8,
+        component_height: 0.55
+    },
+    {
+        type: 'pcb_smtpad',
+        layer: 1,
+        x: 19.2,
+        y: 15,
+        width: 0.7,
+        height: 0.9
+    },
+    {
+        type: 'pcb_smtpad',
+        layer: 1,
+        x: 20.8,
+        y: 15,
+        width: 0.7,
+        height: 0.9
+    },
+    {
+        type: 'pcb_trace',
+        layer: 1,
+        route: [
+            { x: 18, y: 15 },
+            { x: 19.2, y: 15 }
+        ],
+        width: 0.25
+    }
+]
+
+container.innerHTML = PcbScene3dShellRenderer.render(circuitJson)
+
+const controller = new PcbScene3dController(
+    container.querySelector('[data-scene-3d-viewport]'),
+    circuitJson
+)
+```
+
+The shell renderer does not inspect the CircuitJSON data. It only renders the
+optional DOM controls. The controller performs the CircuitJSON detection and
+conversion.
+
+## Direct Runtime Input
+
+For custom UI shells, pass the same CircuitJSON array directly to
+`PcbScene3dRuntime`.
+
+```js
+import { PcbScene3dRuntime } from 'pcb-scene3d-viewer'
+
+const runtime = new PcbScene3dRuntime(viewportNode, circuitJson, {
+    setDiagnostics: (messages) => renderDiagnostics(messages),
+    setSelection: (selection) => renderSelection(selection)
+})
+
+await runtime.whenReady()
+runtime.setPreset('isometric')
+```
+
+## Adapter API
+
+The direct path uses `PcbScene3dCircuitJsonAdapter`. Hosts can call it directly
+when they need to inspect or cache the normalized render model.
+
+```js
+import { PcbScene3dCircuitJsonAdapter } from 'pcb-scene3d-viewer'
+
+if (PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(circuitJson)) {
+    const sceneDescription = PcbScene3dCircuitJsonAdapter.build(circuitJson)
+}
+```
+
+`isDirectCircuitJsonModel(value)` returns `false` for compatibility arrays that
+also carry legacy parser fields such as `pcb`, `schematic`, or `bom`. Those
+arrays continue through the host-provided `buildScene` callback so existing
+parser integrations keep their source-specific conversion behavior.
+
+## Units And Coordinates
+
+CircuitJSON input uses millimeters. The adapter converts all board, component,
+pad, via, trace, and silkscreen dimensions into mils before handing the scene to
+the Three.js runtime.
+
+The board center defaults to `{ x: 0, y: 0 }` when omitted. If no `pcb_board`
+element is present, the adapter creates a 25.4 mm by 25.4 mm board with a
+1.6 mm thickness so incomplete test or preview models still render.
+
+Layer values resolve as follows:
+
+- `1`, `top`, `front`, and `f.cu` map to the top side.
+- `32`, `bottom`, `back`, and `b.cu` map to the bottom side.
+- Unknown layer values default to the top side.
+
+## Supported Elements
+
+The adapter focuses on renderer-ready PCB geometry and ignores unsupported
+CircuitJSON elements instead of failing the whole scene.
+
+| Element type          | Rendered as                                         |
+| --------------------- | --------------------------------------------------- |
+| `pcb_board`           | Board size, thickness, center, and optional outline |
+| `source_component`    | Component designator and package metadata           |
+| `pcb_component`       | Fallback component body and selection target        |
+| `pcb_smtpad`          | Top or bottom SMT pad copper                        |
+| `pcb_plated_hole`     | Through-hole pad copper and drill                   |
+| `pcb_hole`            | Non-plated drill opening                            |
+| `pcb_via`             | Via copper and drill                                |
+| `pcb_trace`           | Routed copper track segments                        |
+| `pcb_silkscreen_line` | Top or bottom silkscreen stroke                     |
+| `pcb_silkscreen_text` | Top or bottom silkscreen text placeholder           |
+
+Board outlines can be supplied as `pcb_board.outline`, using an array of points:
+
+```js
+{
+    type: 'pcb_board',
+    outline: [
+        { x: 0, y: 0 },
+        { x: 50, y: 0 },
+        { x: 50, y: 30 },
+        { x: 0, y: 30 }
+    ]
+}
+```
+
+Traces can be supplied as a `route` array. Each adjacent point pair becomes one
+track segment:
+
+```js
+{
+    type: 'pcb_trace',
+    layer: 'top',
+    route: [
+        { x: 5, y: 5 },
+        { x: 10, y: 5 },
+        { x: 10, y: 8 }
+    ],
+    width: 0.2
+}
+```
+
+## Diagnostics
+
+Malformed CircuitJSON input is rejected by `circuitjson-toolkit` before render
+model conversion. Use `PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(value)`
+for a cheap guard when accepting untrusted JSON from users, and catch conversion
+errors around `build(value)` when you need to show a custom diagnostic.
+
+The viewer does not fetch external assets for CircuitJSON input. STEP and WRL
+model matching remains the responsibility of source-specific toolkits or host
+applications that create normalized scene descriptions.

package/docs/model-format.md

@@ -0,0 +1,117 @@
+# Model Format
+
+The viewer consumes a normalized PCB 3D scene description. Format-specific
+toolkits are responsible for creating this data.
+
+## Top-Level Shape
+
+```js
+{
+    sourceFormat: 'altium' | 'kicad' | string,
+    coordinateSystem: 'kicad-3d-y-up' | undefined,
+    board: {
+        widthMil,
+        heightMil,
+        thicknessMil,
+        minX,
+        minY,
+        centerX,
+        centerY,
+        segments,
+        surfaceColor,
+        edgeColor
+    },
+    components: [],
+    externalPlacements: [],
+    boardAssemblyModel: null,
+    detail: {
+        pads: [],
+        tracks: [],
+        arcs: [],
+        fills: [],
+        vias: [],
+        polygons: [],
+        copperTexts: [],
+        silkscreen: {
+            top: {},
+            bottom: {}
+        }
+    }
+}
+```
+
+All dimensions are in mils. The runtime centers board detail around
+`board.centerX` and `board.centerY`.
+
+## Components
+
+Components describe fallback package bodies and selection metadata:
+
+```js
+{
+    designator: 'U1',
+    mountSide: 'top',
+    rotationDeg: 90,
+    positionMil: { x: 0, y: 0, z: 90 },
+    boardPositionMil: { x: 500, y: 500, z: 0 },
+    pattern: 'SOIC-8',
+    source: 'library',
+    body: {
+        family: 'ic',
+        sizeMil: { width: 200, depth: 300, height: 60 }
+    },
+    externalModel: null
+}
+```
+
+## External Placements
+
+External placements describe STEP or WRL model instances:
+
+```js
+{
+    designator: 'U1',
+    mountSide: 'top',
+    rotationDeg: 90,
+    positionMil: { x: 0, y: 0, z: 31.5 },
+    bodyPositionMil: { x: 500, y: 500 },
+    bodyRotationDeg: 0,
+    modelTransform: {
+        rotationDeg: { x: 90, y: 0, z: 0 },
+        dzMil: 0
+    },
+    externalModel: {
+        origin: 'session',
+        name: 'soic-8.step',
+        relativePath: 'packages/soic-8.step',
+        format: 'step',
+        file: File
+    }
+}
+```
+
+Embedded STEP models can use:
+
+```js
+{
+    origin: 'embedded',
+    name: 'embedded.step',
+    format: 'step',
+    payloadText: 'ISO-10303-21;'
+}
+```
+
+## Detail Primitives
+
+The runtime expects pre-normalized primitive lists for:
+
+- pads and vias with drill and copper dimensions;
+- tracks and arcs with layer metadata;
+- fills and polygons with point loops;
+- silkscreen tracks, arcs, fills, and texts;
+- copper text primitives.
+
+The viewer does not infer source-file semantics. When a scene needs
+format-specific layer mapping, solder-mask interpretation, text layout, or
+model matching, the source toolkit should encode those decisions in the scene
+description.

package/docs/testing.md

@@ -0,0 +1,23 @@
+# Testing
+
+Run all tests with:
+
+```bash
+npm test
+```
+
+The test suite covers:
+
+- geometry factories for board solids, pads, vias, drills, solder mask,
+  copper, and silkscreen;
+- runtime camera, preset, resizing, selection, and visibility behavior;
+- external STEP/WRL placement and load ordering;
+- model ZIP archive export;
+- optional shell renderer and CSS contract;
+- worker-client request routing.
+
+Tests use fake scene descriptions and fake model payloads only. Do not add
+customer, vendor, or source-derived fixture identifiers.
+
+Use focused tests for behavior changes. Parser and scene-description builder
+tests belong in the format-specific toolkits, not in this viewer package.

package/package.json

@@ -0,0 +1,65 @@
+{
+    "name": "pcb-scene3d-viewer",
+    "version": "1.0.1",
+    "description": "Reusable Three.js PCB 3D scene viewer for normalized ECAD and CircuitJSON scene descriptions",
+    "keywords": [
+        "pcb",
+        "ecad",
+        "eda",
+        "circuitjson",
+        "3d",
+        "three",
+        "viewer",
+        "step",
+        "wrl"
+    ],
+    "homepage": "https://github.com/SunboX/pcb-scene3d-viewer#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/SunboX/pcb-scene3d-viewer.git"
+    },
+    "bugs": {
+        "url": "https://github.com/SunboX/pcb-scene3d-viewer/issues"
+    },
+    "license": "AGPL-3.0-or-later",
+    "type": "module",
+    "main": "./src/index.mjs",
+    "exports": {
+        ".": "./src/index.mjs",
+        "./scene3d": "./src/scene3d.mjs",
+        "./styles/scene3d.css": "./src/styles/scene3d.css"
+    },
+    "files": [
+        "src",
+        "docs/api.md",
+        "docs/circuitjson.md",
+        "docs/model-format.md",
+        "docs/testing.md",
+        "spec",
+        "LICENSE",
+        "LICENSES",
+        "COMMERCIAL-LICENSE.md",
+        "CONTRIBUTING.md",
+        "NOTICE.md",
+        "README.md",
+        "AGENTS.md",
+        "REUSE.toml"
+    ],
+    "scripts": {
+        "test": "node --test",
+        "format": "prettier --write .",
+        "check:format": "prettier --check ."
+    },
+    "dependencies": {
+        "circuitjson-toolkit": "^1.0.1",
+        "fflate": "^0.8.2",
+        "occt-import-js": "^0.0.23",
+        "three": "^0.183.2"
+    },
+    "devDependencies": {
+        "prettier": "^3.4.2"
+    },
+    "engines": {
+        "node": ">=20"
+    }
+}

package/spec/library-scope.md

@@ -0,0 +1,36 @@
+# Library Scope
+
+`pcb-scene3d-viewer` owns reusable browser-side 3D rendering for normalized PCB
+scene descriptions.
+
+## In Scope
+
+- Three.js runtime orchestration for PCB scenes.
+- Board, copper, via, drill, silkscreen, solder-mask, and fallback package mesh
+  factories.
+- STEP and WRL model loading and placement.
+- Camera presets, view compensation, selection styling, picking, and visibility
+  toggles.
+- Optional DOM shell/controller helpers for hosts that want ready-made scene
+  chrome.
+- ZIP export of resolved STEP and WRL model assets.
+- CSS for the optional scene shell.
+
+## Out of Scope
+
+- Parsing Altium, KiCad, Gerber, or other ECAD source files.
+- Building format-specific 3D scene descriptions from source documents.
+- Host application state, routing, file pickers, drag/drop handling, analytics,
+  localization storage, or app navigation.
+- Server-side upload or network fetch behavior.
+
+## Host Contract
+
+Hosts provide either:
+
+- a prepared scene description through `sceneDescription`;
+- a `scenePrepClient` with `prepareScene(documentModel, sessionAssets)`; or
+- `buildScene(documentModel, { modelRegistry })` plus an optional
+  `createModelRegistry(documentModel, sessionAssets)`.
+
+The viewer treats all scene descriptions and model payloads as untrusted input.