hrithik18k/switch-pcb

BUGS.md

# tscircuit issues observed while designing Switch

Environment: Windows; Bun 1.3.14; tscircuit 0.0.3047; @tscircuit/cli 0.1.2427; @tscircuit/core 0.0.2245. Versions refer to this installed dependency tree, not all versions.

## Highest priority confirmed issue: documented pcbkeepout fails at runtime (P2)

The supplied skill's elements/pcbkeepout.md documents `<pcbkeepout shape="rect" ... />`. Using it in this project and running `bun node_modules/tscircuit/cli.mjs check netlist` fails with `Unsupported component type "pcbkeepout". No element with this name is registered in the @tscircuit/core catalogue.`

Minimal reproduction:

    export default () => <board width={50} height={48}>
      <pcbkeepout shape="rect" pcbX={0} pcbY={0} width={10} height={5} />
    </board>

Expected: the documented keepout builds and excludes copper. Actual: component registration error stops evaluation. Local workaround: `<keepout ... />`; final source retains the antenna keepout using that working primitive. Do not work around this by deleting the antenna keepout.

Likely code fix repository: https://github.com/tscircuit/core — add/verify an alias in element catalogue registration, with a regression test that produces pcb_keepout and excludes autorouted copper. Alternatively correct docs to use keepout consistently. Props currently supplies pcbKeepoutProps, which is separate from JSX element registration. The skill documentation also needs correction at C:/Users/Hrithik/.agents/skills/tscircuit/elements/pcbkeepout.md. Root cause attribution is based on local catalogue error and Keepout class inspection, not an upstream patch.

No confirmed P0/P1 tool defect was found. P2 here means a documented workflow is blocked with a usable workaround; it does not establish an unsafe manufactured board.

## Transient local dev upload timeout (P3, not consistently reproducible)

`bun node_modules/tscircuit/cli.mjs dev --port 3020` failed during initial local file upload with `Timeout while uploading "bun.lock" to the local file server` and a POST /api/files/upsert timeout. Node 24 launching the identical CLI on port 3021 succeeded, uploaded dependencies and served HTTP 200. A second Bun launch on port 3022 succeeded (dev-bun-repro.log). This disproves a general Bun incompatibility. The initial timeout remains a transient incident with unconfirmed cause; ports differed. Do not file it as a reproducible Bun-only defect.

Repository to investigate: https://github.com/tscircuit/cli — DevServer.start, upsertInitialFiles, upload timeout diagnostics and local HTTP client. Reproduce on Windows with both runtimes and the same free port before assigning root cause. Add a readiness probe and better reporting of the initial failed request if confirmed.

## React key access warning (P3)

Commands print `trace: key is not a prop` when trace JSX elements have React keys. Netlist/build still succeed. Keep correct React keys in mapped children; consumers should not access props.key. Repository to investigate: https://github.com/tscircuit/core (element construction / prop handling). Exact internal caller not isolated, so attribution is provisional.

## Setup incident, not a confirmed upstream defect

The init command installs dependencies asynchronously from the shell's perspective. I accidentally started a second dependency install before init had completed; the concurrent installs produced EBUSY copy failures. Serial `bun install --backend copyfile` repaired the installation. Do not file this as a tscircuit defect without reproducing it from one clean init process.

## CLI documentation mismatch (P3)

The supplied skill suggests bare `tsci check trace-length`; current CLI requires `<pinOrNetRef> [file]`. Bare command exits with `missing required argument pinOrNetRef`. Use `tsci check trace-length U1.D6 dist/index/circuit.json`. Fix the skill's CLI.md/SKILL.md examples, rather than treating the required argument as a routing defect.


## Rev B highest-priority new finding: unrelated JLC part search results (P2)

Reproduced with CLI 0.1.2427 and directly against the service, so this is not only a CLI rendering issue.

    tsci search --jlcpcb "ESP-12F" --json
    GET https://jlcsearch.tscircuit.com/api/search?limit=3&q=ESP-12F

Observed results: C19724200 / TK-1085-A switch, C1345312 / S912ZVHY64F1VLQ MCU, C7435518 / SKM100GB12T4 IGBT. None is the requested ESP module. The CLI relay query `G5Q-1A4-EU DC5` returned an LTC2954 power supervisor (relay-search.log). AP2112K-3.3 and TTP223-BA6 searches also returned unrelated devices during this session. These are search relevance/escaping failures, not proof of an incorrect automatically imported footprint.

Expected: rank exact/normalized manufacturer part-number matches first, or return no match; do not present arbitrary unrelated matches as the only hits. Importing known identifiers C82891, C2757936, C51118 and C20917 succeeded and bypassed this search ambiguity. The wrong search results were NOT used as design substitutes.

Primary repository to investigate: https://github.com/tscircuit/jlcsearch . The CLI calls /api/search with q=encodeURIComponent(query), matching the documented API. Add endpoint regression cases for hyphenated exact MPNs, compare hyphen/period tokenization and ranking, and examine whether negative-term parsing is incorrectly activated. That mechanism is a hypothesis; it has not been isolated. Secondary repository https://github.com/tscircuit/cli could expose a no-exact-match notice to avoid misleading part selection.

This is the highest new priority for procurement reliability, alongside the earlier P2 keepout documentation mismatch. No P0/P1 is claimed without evidence.

## Rev B build cautions that are not tool bugs

Availability warnings on direct part imports do not establish stock; supplier availability must be checked before ordering. Schematic/placement warnings found during development were corrected in the circuit sources. Missing schematicsheet and unspecified metadata warnings, if present in build logs, must not be confused with proven electrical safety. The three-board draft still requires an engineering mains/thermal review and actual load ratings.

## Rev B autorouter failure reproduction (P2)

The controller routes with 12 named nets / 65 obstacles initially exhausted iterations in capacity-autorouter@0.0.1018. Error: `DK ran out of iterations`, pipeline9 portPointPathingSolver, followed by 48 pcb_port_not_connected_error records and no completed copper routes. A two-layer reproduction source and failed output are saved in debug/esp-two-layer-repro.tsx and debug/esp-route-failed.circuit.json; original log debug/esp-route-failed.log. Four-layer and built-in pipeline4 trials also failed (logs in debug/). A retry with reduced track widths still failed. This is an observed convergence limit, not proof that the layout is impossible or an electrical short.

Investigate https://github.com/tscircuit/capacity-autorouter (solver iteration budget/pathing diagnostics) with the SRJ inputs in dist/esp-router. The current attempt imports ALL components from JLCPCB and uses the documented autorouterEffortLevel=5x. Do not treat successful JSON/image generation or a no-shorts result on an unrouted failed design as routing success. The CLI correctly returned a nonzero build result.

## Keepout layers must be explicit

The default keepout obstacle was top-only in the generated SRJ. This is not assumed to be an engine defect because a layer default can be intentional. All-layer antenna and relay isolation requirements must explicitly list the actual board copper layers. Final sources specify top and bottom; the rejected four-layer attempt specified top/inner1/inner2/bottom. Verify this in phase-0.input.simple-route.json before fabrication review.

## Direct-import verification

The first attempted connector ID C8469 had no importable EasyEDA geometry; it was not used. C49256 proved to be an 8-pin header rather than a 2-pin header and is not used. Final inter-board/power headers are verified C49257 (3 pins), programming socket C50950 (5 pins), and mains terminal C474881. Diode import C81598 defines pin1=cathode, pin2=anode; the circuit explicitly uses that mapping. These checks prevented incorrect substitutions and are not upstream footprint bug claims.

## Successful controller routing workaround and final status

The all-JLC controller using the same layout/SRJ successfully routed with documented autorouterVersion="beta_pipeline1", autorouterEffortLevel="5x": 36 traces, zero router errors, about 11.8 s router time. Default pipeline9 with 5x effort failed after about 67 s on 12 nets / 66 obstacles. Preserve this comparison when investigating capacity-autorouter. Final pipeline1 routed output passed the Gerber copper-short check. All three final boards have zero circuit error records, and pass schematic/PCB placement checks and copper-short checks.

Imported header and terminal geometry lacked insertion direction metadata; it was added locally without modifying pads. This resolves inferred connector-access warnings. The vertical header/socket uses from_above; KF301 uses from_y_neg in its unrotated footprint frame, followed by +90 degree board placement to point wire entry toward the right board edge. This is a metadata improvement, not evidence of an incorrect imported pad layout.

## Local preview response validation error during initial sync (P2, cause unisolated)

The final Node dev launch emitted `TypeError: Cannot read properties of undefined (reading length)` at formatZodError while handling a ResponseValidationError during node_modules upload. This masks the original schema validation failure. It did not affect CLI build validation. Investigate https://github.com/tscircuit/cli and its bundled response-validation middleware dependency; preserve the original validation error and support the installed Zod error shape (issues vs errors) rather than assuming an array. Exact failing response and root cause have not been isolated; this is not claimed as a PCB error.

## Rev C power-board work

Added direct JLCPCB imports IRM-03-5 C6969425 and axial high-breaking-capacity time-delay fuse 0215001.MXEP C178837. Initial power-board layout had output-header pads within the isolation band and a connector courtyard near a mounting hole; placement checks correctly caught both. Components were moved and checks rerun. These were design errors caught by checks, not tscircuit defects. Do not disable placement DRC to route such a mains board.

An imported MOV C840589 was evaluated but is not fitted because a MOV without coordinated thermal fault protection is not a complete surge strategy. It was archived outside the package. No new confirmed upstream tool defect is claimed for Rev C. Earlier autorouter and search reports remain in this document.

Rev C validation note: some in-progress checks were invalidated when unused import files were moved during compilation (ENOENT). They were restored and the final checks rerun against an unchanged file set. These failed attempts are not reported as successful validation or upstream bugs. MOV_10D471K and PowerInputTerminal are unused source files only; neither appears in the circuit BOM. Power circuit uses the original imported KF301 component and its unchanged from_y_neg wire-entry metadata, rotated +90 degrees on the right board edge.

Final Rev C power layout: schematic and PCB placement passed, routed build completed without circuit errors. Fuse was moved to x=0 mm to resolve the 0.05 mm courtyard overlap introduced when the mains connector moved to the right edge. This was a design correction. No high-priority new upstream defect was demonstrated in this step.