hrithik18k/punck-tscircuit-recreation

HIGH_PRIORITY_ISSUES.md

# Punck recreation: high-priority tscircuit issues

## Follow-up: native schematic and autorouter work

The subsequent native rebuild is under `native/`; see `NATIVE_BUILD.md`. Earlier limitations below describe the initial import workflow, not every capability of the new native build.

### P1 — Repeated physical pads can disappear from PCB port matching

Owner: [tscircuit/core](https://github.com/tscircuit/core), footprint-to-port matching and PCB port generation. In the native board, U7 has two SMD pads with `portHints=["pin2"]`; RESET1 has paired pads for each pin. Their logical source ports existed but the affected PCB ports were absent. The router received only 112 of 114 required multi-port nets and the build flagged U2.NRST and L2 output as unconnected. Mapping each repeated physical pad to a unique native alias, still connected to the same original net, restores PCB ports and all 114 routing connections. Reproduce with the fixture geometry in `native/components.json`, removing the duplicate aliases and assigning original repeated pin hints. Acceptance: one electrical pin can own multiple physical pads without losing any route target or requiring artificial logical pins.

### P1 — A successful router phase can leave via holes overlapping SMD pads

Owners: [capacity-autorouter](https://github.com/tscircuit/capacity-autorouter) and core's routing/DRC integration. The corrected electronics run reported router `errors=0` and 302 trace records, but subsequent core DRC found via holes overlapping U2.VSS and C41.pin2. Evidence: `evidence/native-corrected-components.log` and intermediate routing artifacts. The outer-layer shorts check passed; that does not resolve via-to-pad manufacturing clearance. Acceptance: the solver and post-route DRC agree on via-hole/pad constraints and report unresolved violations as router failures. The 0.2 mm run retained the C41 failure; 0.4 mm retained C41 and produced a U2.PA12 via-in-pad error. The final output uses two explicit via/trace-vertex repairs in `scripts/repair-native-vias.ts`, then recomputes all checks (0 errors) and passes the separate shorts test. Raw output: `evidence/native-autorouter-raw.circuit.json`; precise changes: `evidence/native-via-repairs.json`. Increasing clearance alone did not fix the defect.

### P1 — Netlist-only checking starts routing with incomplete geometry

Owner: [tscircuit/cli](https://github.com/tscircuit/cli), partial-build phase control, coordinated with core. `tsci check netlist native/controls.circuit.tsx` prints a router exception (`ExpandEdgesToEmptySpaceSolver bounds must be finite`, null bounds) before reporting `Errors: 0`, whereas a full build routes successfully. Evidence: `evidence/native-netlist-controls-final.log`. Acceptance: stop before PCB autorouting during a netlist-only check, report the intended validation result without unrelated async failures, and ensure errors affect exit status appropriately.

Tested 7 October 2026 on Windows with Bun 1.3.14. These are locally reproduced findings, not submitted GitHub issues. P1 means a blocker for reliable import, electrical identity, or faithful reproduction; it does not mean every tscircuit project is affected.

## Fixture and versions

- Original: [dchwebb/Punck, Hardware_v1_1](https://github.com/dchwebb/Punck/tree/06cc9914f34f9e53bc21cdb8d0246d97dfda66ec/Hardware_v1_1), commit `06cc9914f34f9e53bc21cdb8d0246d97dfda66ec`.
- `tscircuit` 0.0.2757; CLI 0.1.2257; core 0.0.2106; Circuit JSON 0.0.520.
- `kicad-to-circuit-json` 0.0.142; `circuit-json-to-kicad` 0.0.230; `circuit-to-svg` 0.0.445.
- Parser initially resolved to `kicadts` 0.0.53; the original PCB failures were also reproduced after explicitly installing latest published 0.0.58.
- Inspected importer commit `967a8c823d8d19cdf18060fd7b66ce5d79e91c12`, exporter `b337d73bd88a26dab3b880e19399ad9cf5f9747a`, parser `bd803fb20e74dcc015240b749d65160f39a8ede1`.

Project: `E:\project\tscircuit\Punck`. Commands below run there after `bun install --frozen-lockfile`. `bun run reproduce` writes compact evidence; `bun run recreate` regenerates conversions and local repairs. Originals in `source/` are unmodified.

## P1-1 — Imported copper pours lose their electrical net identity

**Fix repository:** [kicad-to-circuit-json](https://github.com/tscircuit/kicad-to-circuit-json), [CollectZonesStage.ts](https://github.com/tscircuit/kicad-to-circuit-json/blob/967a8c823d8d19cdf18060fd7b66ce5d79e91c12/lib/stages/pcb/CollectZonesStage.ts).

**Observed:** pours contain `net_name: "GND"` but omit the schema's `source_net_id`. The insertion is cast `as any`. The raw electronics board produces **905 shorts** in `tsci check shorts`; attaching existing net IDs, without moving or changing any copper, produces **zero**. The controls board also passes after this repair.

**Reproduce:** compare `bunx tsci check shorts boards/components.pcb.circuit.json` with `bunx tsci check shorts prepared/components.circuit.json`. Evidence: `evidence/shorts-components.log`, `shorts-components-repaired.log`, `components-repairs.json`.

**Impact:** disconnected logical planes, misleading short reports, and unreliable downstream net association. This was an import metadata defect; the 905 findings are not evidence that the original hardware has 905 physical shorts.

**Proposed fix:** resolve each zone's net key through `netNumToSourceNetId`, emit `source_net_id`, and type-check against the actual pour schema. Keep netless artwork distinct from electrical nets.

**Acceptance:** known-net pours reference existing source nets; same-net touching copper passes shorts; deliberately touching different-net copper still fails; preserve all copper polygons and holes.

## P1-2 — Valid source syntax prevents every original PCB from loading

**Fix repository:** [kicadts](https://github.com/tscircuit/kicadts), `lib/sexpr/classes/PadPrimitiveGrCircle.ts`, `GrLine.ts`, `GrRect.ts`, and schematic token registration. Add fixtures in the importer too.

**Observed:** electronics fails with `pad primitive gr_circle fill expects yes/no/none or boolean, received "solid"`; controls fails with `gr_line encountered unexpected primitive child: "locked"`; panel fails with the equivalent `gr_rect` error. Combined import then encounters unregistered `symbol_instances` metadata.

**Reproduce:** `bun run reproduce`; see `evidence/raw-conversion.json`, `raw-latest-parser.json`, and `reproductions.json`. The three PCB errors persist with parser 0.0.58. The schematic error was observed during the initial 0.0.53 run.

**Workaround:** `scripts/sexpr.ts` parses S-expressions, removes editing locks and legacy symbol-instance metadata, and normalizes circle `fill solid` to `fill yes` in the in-memory input. This does not rewrite originals. It intentionally loses lock state and legacy instance metadata, so it is not a general lossless upgrade.

**Proposed fix:** accept version-appropriate boolean/enum spellings and both bare and structured lock forms; preserve legacy metadata instead of throwing. Avoid sharing context-specific token parsers where board and pad grammars differ.

**Acceptance:** all three untouched fixtures parse; locks, fills, and references survive serialization; malformed syntax still yields a useful file/token diagnostic.

## P1-3 — Combined PCB/schematic conversion creates disconnected component identities

**Fix repository:** [kicad-to-circuit-json](https://github.com/tscircuit/kicad-to-circuit-json), `CollectLibrarySymbolsStage.ts`, `CollectFootprintsStage/process-footprint.ts`, and shared conversion context.

**Observed:** electronics produces 209 schematic components plus 114 PCB components and 323 source components. Controls produces 94 plus 36 and 130 respectively. **Zero source-component IDs are shared between schematic and PCB representations.** Schematic names use library IDs such as `Device:C_Small`; PCB names use references such as `C1`.

Counts alone are not proof of duplication: power symbols and multi-unit parts can legitimately change counts. The decisive evidence is the disjoint identity sets and the unconditional source-component creation in both pipelines.

**Reproduce:** `bun run reproduce`; inspect `evidence/reproductions.json` and `boards/*.combined.circuit.json`.

**Impact:** cross-probing, BOM identity, pin connectivity, and schematic-driven board changes cannot rely on one shared device model.

**Proposed fix:** index components by hierarchical instance/reference identity, merge footprint and schematic views, preserve refdes as `name`, store library IDs separately, and map multi-unit symbols onto one physical package. Handle virtual power symbols separately.

**Acceptance:** each physical reference links both views to the same source component; pin-to-net memberships agree; multi-unit and virtual symbols do not inflate the BOM.

**Local decision:** final PCB entrypoints use PCB-only conversion. Combined imports remain diagnostic artifacts, not the authoritative netlist.

## P1-4 — Alphanumeric pad identifiers produce schema-invalid source ports

**Fix repository:** [kicad-to-circuit-json](https://github.com/tscircuit/kicad-to-circuit-json), PCB port creation. Coordinate the representation with [circuit-json](https://github.com/tscircuit/circuit-json) if broader pin-number support is intended.

**Observed:** controls ports `pcb_component_7_port_R`, `_S`, and `_T` use string values in `pin_number`, which Circuit JSON 0.0.520 defines as numeric. Validation fails with `Expected number, received string`.

**Reproduce:** `bun run reproduce`. Compact offending records and schema errors are in `evidence/reproductions.json`.

**Impact:** common audio-jack pad labels break schema-valid interchange despite the converter reporting success.

**Workaround:** remove only optional invalid `pin_number`; keep `name`, IDs, physical pads, and connectivity unchanged. All prepared records then pass schema validation.

**Acceptance:** fixtures with numeric, alphanumeric, and repeated physical pad labels validate without losing identities or net membership. Do not invent numeric replacements that change connectivity.

## P1-5 — No reliable handoff from the converter to native TSX/netlist validation

**Fix repositories:** [core](https://github.com/tscircuit/core) for Circuit JSON inflation; [cli](https://github.com/tscircuit/cli) for consistent JSON-input handling.

**Observed A:** `<board circuitJson={json} />` rejects the importer's `simple_test_point` with `No inflator implemented for source component ftype: "simple_test_point"`.

**Observed B:** `tsci build prepared/components.circuit.json` succeeds, and placement/shorts accept it, but `tsci check netlist prepared/components.circuit.json` attempts to render the JSON array as a React component and fails with `Element type is invalid ... got: array`.

**Evidence:** `evidence/check-netlist.log`, `netlist-components-json.log`, `build-json.log`; wrappers in `experiments/`. The generic-chip test-point workaround and disabled schematic allow an experimental TSX render to emit JSON, but its build still exits 1 with diagnostics. It is not the accepted deliverable path.

**Proposed fixes:** add/test test-point inflation and enforce coverage for every source ftype emitted by the importer. Make netlist checking consume Circuit JSON through the same file-dispatch path used by placement/shorts.

**Acceptance:** an imported test-point fixture builds without substitution; JSON netlist checking returns actual connectivity diagnostics rather than a React error. Compare emitted copper before accepting an inflation result.

## P1-6 — Published exporter lacks a required runtime dependency

**Fix repository:** [circuit-json-to-kicad](https://github.com/tscircuit/circuit-json-to-kicad), [package.json](https://github.com/tscircuit/circuit-json-to-kicad/blob/b337d73bd88a26dab3b880e19399ad9cf5f9747a/package.json) and publishing checks.

**Observed:** the first `bun scripts/convert.ts` fails at import time: `Cannot find package 'polygon-clipping' from ... circuit-json-to-kicad/dist/index.js`. Installing `polygon-clipping@0.15.7` in the consuming project fixes that blocker. The inspected package declares it under `devDependencies` while the distributed runtime imports it.

**Reproduce:** in a disposable clean project, install `circuit-json-to-kicad@0.0.230` and TypeScript, then import `CircuitJsonToKicadPcbConverter`. Do not install this project's explicit workaround first.

**Proposed fix:** bundle the library or declare it as a runtime dependency; test the packed/published tarball in an empty consumer, not only the repository checkout.

**Acceptance:** clean Node and Bun consumers can import and export a pour fixture with only documented dependencies installed. This does not prove all other external dependencies are packaged correctly; audit those too.

## P1-7 — Solder-mask artwork is silently lost during panel recreation

**Fix repositories:** start with [kicad-to-circuit-json](https://github.com/tscircuit/kicad-to-circuit-json), `CollectGraphicsStage.ts` and `layer-mapping.ts`; coordinate a lossless representation with [circuit-json](https://github.com/tscircuit/circuit-json), then implement matching output in [circuit-json-to-kicad](https://github.com/tscircuit/circuit-json-to-kicad). Preview support belongs in [circuit-to-svg](https://github.com/tscircuit/circuit-to-svg).

**Observed:** the source panel has nine board-level `F.Mask` circles. None survive as mask graphics in Circuit JSON, and the exported KiCad board has zero board-level circles. Numerous panel texts/graphics are also omitted. See `source/Punck_Panel.kicad_pcb`, `dist/Punck_Panel.kicad_pcb`, and `evidence/fidelity-audit.json`.

**Impact:** copper/holes can look plausible while the fabricated panel appearance and exposed-copper artwork change. This blocks an exact visual/manufacturing recreation.

**Proposed fix:** preserve arbitrary mask geometry, text, layer, and fill semantics end to end. Until supported, emit explicit loss diagnostics. Do not silently map mask artwork onto silkscreen or copper.

**Acceptance:** mask-layer image comparison against the source retains all nine circles and lettering, with dimensions and polarity intact; unsupported features make conversion visibly incomplete.

## Additional finding: component bounds are all zero

**Owner:** importer, `CollectFootprintsStage/process-footprint.ts`, lines assigning `width: 0` and `height: 0`. All 191 PCB component records have zero bounds. Placement utilization and collision reports consequently cannot be treated as trustworthy package-level checks. Derive bounds from transformed courtyards/body geometry with a documented pad fallback and add bottom-side/rotation fixtures. This is a follow-up priority, not proof that the source has physical component collisions.

## Verified result and remaining limits

All 191 footprint positions match. All 1,022 routed segments match endpoints, widths, layers, and net names after documented name sanitization, to 0.00001 mm comparison precision. All 254 vias are retained by count. All prepared records validate; all three prepared boards pass the default top/bottom Gerber-derived shorts check. That check does **not** certify the two internal copper layers of the electronics board.

Electronics placement still reports four orientation suggestions; controls and panel report none. Original layout was retained rather than rotating already routed parts merely to silence a heuristic. Combined schematic placement has overlaps and incorrect identities. No native KiCad DRC or fabrication certification was performed. The deliverable is a verified PCB-data reconstruction with documented gaps, **not a completed lossless TSX/schematic migration or fabrication-ready replacement**.