Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
# ECAD Forge Specification
## 1. Goal
Build a browser-based viewer for Altium, KiCad, Gerber, and CircuitJSON design files with client-side parsing, normalized document models, and browser views for schematic, PCB, interactive 3D, BOM, and diagnostics.
## 2. Functional Requirements
1. The app starts via `npm start` and serves the browser app locally.
2. The app accepts standalone native `.SchDoc` and `.PcbDoc` files, KiCad `.kicad_pro`/`.kicad_sch`/`.kicad_pcb` files, KiCad project ZIPs, Gerber/Excellon files, fabrication ZIPs, CircuitJSON `.json` files, companion `.PrjPcb`/`WRL`/`STEP` assets, and project-folder selections through drag-and-drop or file selection.
3. Parsing runs client-side in browser JavaScript with worker offload and main-thread fallback.
4. The app normalizes shared data as CircuitJSON, accepts canonical toolkit
document envelopes, and retains native compatibility data when it has no
source-neutral equivalent.
Normal app intake uses only the common toolkit `Parser` and `ProjectLoader`
contracts; source-specific ZIP, project-context, validation, and asset
behavior must not be reconstructed in the app.
5. The `Schematic` tab renders recovered schematic geometry, hierarchy markers, embedded-image placements, and text.
6. The `PCB` tab renders recovered board outline, layer metadata, fabrication layers, standards-shaped element-array board geometry, detail artwork, diagnostics overlays, source-connectivity rats-nest lines, trace-length budget labels, solder-mask/paste inspection layers, group/anchor-offset overlays, and component placements where available. PCB viewports include an interaction gate to reduce accidental pan/zoom, fit/reset viewport control, numeric layer visibility shortcuts, in-board view settings for object and component-side visibility, and route rendering guards that avoid drawing continuous trace segments across explicit layer changes. The hidden default toolbar path must perform no up-front interaction preparation and must build zero primitive models when component keys resolve from document rows. When a toolbar, measurement, or diagnostic-focus consumer is active, all consumers in that render must share one prepared model. Common component-side tagging must resolve document component rows in one SVG pass and retain a generic interaction-model fallback for unresolved native renderer keys.
7. Clicking a PCB footprint or schematic symbol selects the shared component, opens the matching `Footprints` or `Symbols` sidebar panel, and highlights and scrolls the selected row into view there. Multipart schematic symbols share one `Symbols` row and highlight every visible part for the selected component. Clicking a schematic wire, PCB trace, pad, via, or net row selects the shared net, opens the `Nets` sidebar panel, and renders only matching trace, arc, pad, and via geometry in the viewer highlight color with a subtle glow. PCB pours, planes, zones, silkscreen, text, and other non-copper artwork are inert for hover, click, and touch selection even when format-owned records classify their geometry as tracks or carry stale component or net metadata. PCB hover and bounds interactions honor hidden layers, hidden object families, and top/bottom component filters, publish candidate previews to the sidebar, and mark matching footprint/net rows, with an opt-in hover-focus toolbar mode for zooming to hovered primitive bounds. The PCB toolbar provides distance and bounds measurement tools that work in board coordinates, snap to primitive center/edge/corner anchors where geometry is available, can show snap targets while measuring, and can copy, zoom to, select contents from, or export clipped SVG/PNG snapshots for completed bounds measurements. In-board diagnostic rows group related issues into collapsible sections, persist the focused issue, preview related primitives until the focus changes, animate the viewport to matching bounds, and show copied state when messages are copied.
8. The `3D` tab renders an interactive PCB scene with an interaction gate,
orbit, pan, zoom, procedural board/package geometry, bare-board Gerber
fabrication geometry, embedded STEP extraction, and direct canonical
document/session resolution for STEP/STP, WRL/VRML, GLB/GLTF, STL, OBJ, and
3MF assets. Safe project-relative GLTF BIN, OBJ MTL, and WRL texture
companions resolve without an app wrapper or network access. URL loading is
explicit and collision-safe caches distinguish equal basenames by source
path. Whole-board STEP/WRL/GLTF/GLB export includes board detail, supported
component meshes or fallback bodies, material alpha/colors, bounding-box CAD
flags, and optional GLTF/GLB board-face artwork textures. Opt-in missing-model
search retains fetched STEP/WRL assets as session data for view/export reuse.
9. The `BOM` tab renders grouped component rows from recovered metadata.
10. The `Diagnostics` tab exposes parser recovery, connectivity, and warning messages. PCB views with in-board diagnostics also provide grouped issue navigation, marker focus, and message copy actions.
11. The UI reads app metadata (version) from `/api/app-meta` and falls back to `/api/app-meta.php` on PHP-only hosts, with both endpoints sourcing the version from `package.json`.
12. The app test suite validates app integration, interaction behavior, server behavior, and project structure; parser, deterministic renderer, and non-interactive scene-data behavior is validated in the shared toolkit packages.
13. Runtime language switching detects supported browser locales on first load, persists manual user selection, falls back to English, and includes Brazilian Portuguese.
14. The schematic parser preserves supported hierarchy records, explicit junctions, bus entries, and a normalized single-sheet net model when those records are recoverable.
15. Embedded schematic image payloads remain local-first; the app renders embedded image data when present and falls back to visible placeholders plus diagnostics when the payload is missing.
16. Shared-hosting deployment publishes an Apache-ready static frontend artifact with versioned browser module URLs and no-store cache headers.
17. The app uses a callable `document.modelContext.registerTool` directly, without importing or configuring the packaged bridge. When unavailable, it loads the `@mcp-b/global` WebMCP fallback with same-origin tab and iframe transports. It registers read-only loaded-session tools for listing loaded designs, listing/searching components and nets, reviewing design coverage, auditing metadata/connectivity issues, listing diagnostics, querying direct net membership, querying BOM rows, listing pin connections, listing component type counts, listing single-pin nets, cross-referencing schematic nets against PCB pads, comparing schematic/PCB and BOM/PCB parity, summarizing loaded design state, querying component pins, inspecting PCB component placement, inspecting PCB net geometry, summarizing PCB board/routing/stackup data, listing PCB design rules, reviewing fabrication-readiness signals, and tracing extended connectivity.
18. The app shell provides the production WebMCP origin-trial token for `https://ecadforge.app/`, an import-map entry for the packaged WebMCP runtime, and the served/deployed app applies `Origin-Agent-Cluster: ?1` plus `Permissions-Policy: tools=(self)`.
19. Object-form WebMCP `execute(input, { signal })` callbacks keep execution context separate from JSON input and propagate genuine cancellation signals through the adapter and tool registry to the app-owned loaded-design execution boundary. Pre-aborted synchronous calls fail before app inspection or Altium/KiCad toolkit dispatch starts without changing existing return shapes.
20. SPICE simulation requests run through a browser worker boundary and return complete simulation CircuitJSON, graph-only transient elements, graph summaries, and diagnostics from local input data.
21. Canonical documents reuse one CircuitJSON context across rendering,
interaction, BOM derivation, and 3D preparation. Only canonical documents
received after the parser worker's completed structured-clone boundary use
the explicit cooperative adoption path. That path validates and freezes the
exclusively transferred browser-owned graph without a second full extension
copy and yields within large extension traversal and sealing and between
successive documents and first consumer rendering. Direct, fallback, and
compatibility inputs use exact defensive context preparation. Retained native features remain
available through explicit toolkit `/extensions` entrypoints. Shared
preparation isolates caller cancellation, and parser-worker terminal
messages must match the exact active request id. Shared adoption must fall
back when a host scheduler rejects, cache terminal structural failures by
document identity, reject synchronous preparation while that identity is
still being adopted, and never publish a queued parse result or error after
controller disposal.
## 3. Non-Functional Requirements
The header exposes a prominent, localized Request support link to the public
GitHub issue tracker in landing and loaded-viewer modes, in both themes and on
narrow screens. It opens a new tab with opener/referrer isolation and a visible
keyboard focus indicator. Agents can discover the same destination via HTML
help links, `/llms.txt`, and a read-only `prepare_issue_report` WebMCP tool.
Preparing a report needs no loaded design and returns a bounded public draft
with the app version and GitHub submission instructions. It never claims to
submit or automatically attaches private session contents. Static guidance
remains accessible when JavaScript or WebMCP is unavailable.
1. Use modern JavaScript ESM modules.
2. Keep each source file below 1000 LOC.
3. Use 4-space formatting with single quotes and no semicolons.
4. Include JSDoc for all public and private methods.
5. Keep documentation in `docs/` and tests in `tests/`.
6. Keep file parsing local-first and avoid outbound network calls unless the user explicitly enables the 3D missing-model search option. Missing-model lookup must not upload native design or fabrication files.
7. WebMCP tools must not upload files, scan local paths, fetch remote resources, mutate app state, or expose raw file contents. Registered descriptors must mark the tools as read-only, non-consequential (`consequentialHint: false`), and untrusted-content capable, and fallback runtime transport configuration must avoid wildcard origin allowlists.
8. Production analytics may load only on deployed HTTP(S) origins; localhost, file URLs, and private-network dev origins must not send events with the production site key.
## 4. Architecture
1. `src/core/`: state and domain primitives.
2. The Altium, KiCad, Gerber, and CircuitJSON toolkit roots expose the same
common API and canonical document behavior.
3. Each source toolkit `/extensions` entrypoint retains its native-only
parser, renderer, query, scene, worker, and inspection functionality.
4. `circuitjson-toolkit` owns immutable shared documents, reusable contexts and
indexes, rendering, interaction, query, manufacturing, simulation, and
canonical scene services. The app may select its structured-clone fast path
only where browser worker provenance proves the complete graph crossed that
boundary.
5. `pcb-scene3d-viewer` accepts canonical documents, prepared contexts, pure
arrays, and retained native scene descriptions, and directly resolves
canonical CAD model metadata plus document/session assets without an app
adapter.
6. `src/core/simulation/`: local SPICE simulation worker client and message handler.
7. `src/ui/`: app shell, local interaction controllers, and interactive 3D runtime modules.
8. `src/AppController.mjs`: orchestration and action layer.
9. `src/workers/ecad-parser.worker.mjs`: worker parser entrypoint.
10. `src/workers/spice-simulation.worker.mjs`: worker simulation entrypoint.
11. `src/main.mjs`: browser entrypoint.
12. `src/server.mjs`: local static/API server.
13. `src/StaticDeployBuilder.mjs` and `scripts/build-static-deploy.mjs`: static FTP deployment artifact builder.
14. `src/core/webmcp/`: WebMCP runtime loader, adapter, tool registry, and loaded-session dispatch to toolkit-owned netlist query APIs.
## 5. Security / Privacy
1. Keep secrets server-side only.
2. Validate supported file types before parsing.
3. Escape parser-derived text before inserting it into the DOM.
4. Document any external network call behavior.
5. Do not upload native design or fabrication files anywhere.
6. Resolve embedded schematic images from the local file container only; never fetch remote image assets during parsing.
7. Simulation workers must run from local netlist text only and must not fetch remote simulator code or upload netlists.
## 6. Acceptance Criteria
1. `npm install && npm start` serves the app without errors.
2. `npm test` passes.
3. The UI can load a native `.SchDoc` and show a populated schematic view.
4. The UI can load a native `.PcbDoc` and show a populated PCB view.
5. The UI can load standalone KiCad schematic/PCB files or a KiCad project folder/ZIP and show schematic, PCB, BOM, and diagnostics views from the normalized documents.
6. The UI can load Gerber/Excellon files or a fabrication ZIP and show a composite PCB fabrication view with a separated-layer option.
7. The UI can load standalone CircuitJSON board files and show a populated 2D PCB view with layer visibility, numeric layer shortcuts, reset/fit viewport control, in-board view settings for trace lengths, rats-nest, solder mask/paste, silkscreen, fabrication notes, courtyards, groups, anchor offsets, and top/bottom components, component/net selection with explicit PCB net highlight colors, hover/bounds candidate previews in the sidebar that honor visibility filters, opt-in hover focus, net hover context, diagnostics overlays, persistent diagnostic focus navigation with singular or plural related-primitive previews, exact primitive-geometry copper clearance checks, rats-nest connectivity, source-net group metadata, trace-length budget labels, solder-mask/paste overlays, group and anchor-offset overlays, measurement copy, bounds zoom/selection, clipped SVG/PNG bounds export, and trace segments split safely at explicit layer changes. Its hidden-default resolved-key render builds no interaction primitives, while active toolbar, measurement, and diagnostic consumers share one prepared model. Common component-side keys are tagged in one SVG pass and unresolved native keys retain compatibility fallback behavior. Standards-shaped PCB geometry covers rounded and rotated SMT pads, route-level via geometry, legacy round hole aliases, plated holes with polygon pads, oval/rotated-rectangle solder paste, polygon board outlines, rectangular copper pours, aligned and knockout PCB text, silkscreen, fabrication, and note path artwork with stroke/dash styling, shape-specific courtyard rows, and circle/path/polygon/rect cutout and keepout variants.
8. The `BOM`, `3D`, and `Diagnostics` tabs render from compatible normalized models without crashing.
9. The `3D` tab remains usable from a lone `.PcbDoc` and from canonical
CircuitJSON documents, renders bare-board Gerber scenes, embedded STEP, and
matching local STEP/STP, WRL/VRML, GLB/GLTF, STL, OBJ, or 3MF models, and
resolves canonical CAD model metadata plus document/session companions
directly in `pcb-scene3d-viewer`. It honors material alpha, vertex/material
colors, and bounding-box flags; whole-board STEP/WRL/GLTF/GLB export adds
fallback bodies and optional board-face textures. Missing-model network
search runs only after explicit user opt-in and stores results for reuse.
10. Docs and spec files are present and linked from `README.md`.
11. The app version shown in UI matches the single-source version in `package.json`.
12. Supported schematic hierarchy records, explicit junctions, bus entries, and embedded images render without breaking existing schematic content.
13. Supported schematic files expose a normalized `nets` model and emit diagnostics for missing embedded image payloads, missing KiCad sheet files, conflicting explicit net names, and optional schematic net geometry checks for missing, ambiguous, suspiciously shaped, disconnected, cross-net overlapping, label-colliding, anchor-preflight, simplifiable, restricted-centerline, or obstacle-crossing wire geometry with staged debug metadata, focused repro metadata, compact stage snapshots, merged and semantic label obstacle groups, spatial index metadata, routing guideline overlays, candidate rejection telemetry, candidate decision timelines with selected, score, and collision-source metadata, stage health rows, per-advisor candidate budgets with final acceptance status, and non-mutating label, sampled and port-only label-relocation with stale-collision suppression, trace-detour, snip-and-reconnect trace-detour, merged-label detour, whole-island lane-shift with obstacle-aware offsets, segment-overlap-shift, alternate congested L-turn reroute with blocker-intersection telemetry, long-distance connection, section-boundary connection, anchor-aware supplemental-connection decision, supplemental-connection, guideline-snapped-elbow, collision-aware path-cleanup, sampled constrained label-orientation with connector collision statuses, power-label corner, symbol-fit decision telemetry, symbol-fit, and endpoint-preserving jog candidate overlays.
14. The FTP workflow uploads the static build artifact rather than raw browser source.
15. In browsers with native WebMCP support or the configured `@mcp-b/global` runtime, the registered tools answer from currently loaded documents only and return clear errors for missing designs, ambiguous selectors, broad regex searches, missing schematic/PCB cross-reference data, PCB-only schematic traversal, missing components, missing nets, and blocked power/ground traversal starts.
16. Share/startup URLs can restore the requested viewer tab, active loaded document, selected component, and selected net when `view=`, `document=`, `component=`, and `net=` query parameters are present.
17. CircuitJSON parsing attaches element and variant-level schema support coverage, grouped BOM rows with source function/type/icon metadata, pick-and-place rows, routing exchange text, group/subcircuit indexes, CAD external-model scene coverage, and categorized diagnostics to the loaded document model. Schema drift checks compare known element types, ID exceptions, source component function types, PCB shape variants, simulation source/waveform variants, and solver-method variants so schema changes are reported before they silently become metadata-only.
18. CircuitJSON schematic rendering covers explicit group bounds, text sizing and rotation, debug objects, geometric shapes, probes, table grid geometry from anchors, row/column sizes, padding, borders, spans, alignment, and font sizes, ports, and diagnostics without breaking basic schematic documents.
19. The SPICE simulation worker accepts local netlist text, returns complete CircuitJSON simulation experiment output plus graph-only voltage/current elements, preserves probe, source endpoint, model/subcircuit mapping, and AC/DC source metadata when present, provides deterministic setup and graph summaries, and reports failures as diagnostics or worker errors.
## WebMCP observability acceptance
- Preserve all loaded-design tool results, thrown errors and native abort reasons.
- Count semantic error responses as failures; distinguish cancellation.
- Report callback starts/completions with page-lifetime correlation, timing and
bounded structural options only. Never transmit input values or result contents.
- Retain at most 100 sanitized startup events; tracking failures cannot break tools.
- Expose explicit, consequential agent feedback with strict schema validation,
local-origin exclusion, duplicate limits, a network timeout and real acknowledgement.
- Dashboard telemetry is observational; unknown historical dimensions and missing
completions must not imply confirmed ChatGPT identity or a confirmed crash.
## Loaded net-name query acceptance
- `list_nets` and `search_nets` enumerate declared net names from the selected
Altium or KiCad schematic or PCB, including retained native envelopes.
- Names do not require attached component pins; duplicates and blank names are
omitted. Selecting a PCB must not substitute another loaded schematic.
- Existing sorting, pagination, regex validation, cancellation, and privacy-safe
success/error telemetry remain intact.
- Schematic traversal and `hasConnectivity` continue to require the schematic
pin graph. A list of PCB net names must not imply traversable schematic data.
5f635a4c0This file is pinned to the selected release. Download the original to open it in your design tool.