mohan-bee/fitness-band

ISSUES.md

# tscircuit platform issues

Only observed tscircuit toolchain problems are listed here, ordered by priority. Hardware design decisions, antenna clearance selection, battery/dock protection, enclosure fit, stock availability and physical qualification belong in [HARDWARE_REVIEW.md](HARDWARE_REVIEW.md).

Versions observed: tscircuit 0.0.2976; @tscircuit/cli 0.1.2385. Repository ownership below identifies the first place to investigate; it does not imply that every underlying dependency has been isolated. The search safeguard was submitted as tscircuit/jlcsearch PR #616; other entries below retain their recorded investigation status.

## High priority

### P10 — Website library bundling fails when allowJs has no explicit outDir

**Status: reproduced locally and in the v0.0.1 website logs; configuration workaround applied. Entry point: tscircuit/cli transpilation with @rollup/plugin-typescript.** With allowJs enabled and no outDir, the plugin creates a temporary output directory. Its path validation then rejects Rollup output in dist/index.js: `Path of Typescript compiler option outDir must be located inside the same directory as the Rollup file option`. An explicit outDir of dist and exclusion of generated dist files restores ESM, CJS and declaration bundling. Evidence: validation/website-v0.0.1-build.log, validation/publish-before-transpile.log and validation/publish-after-transpile.log.

### P1 — CLI startup crashes with TypeScript 7

**Status: observed; worked around. Owner: [tscircuit/cli](https://github.com/tscircuit/cli), dependency compatibility.** With TypeScript 7.0.2 resolved, even `tsci --help` failed inside `@rollup/plugin-typescript/dist/es/index.js:528` when accessing `ModuleKind.ES2015`: `TypeError: undefined is not an object`. This blocks CLI usage before circuit evaluation.

Reproduce in a disposable project with the above CLI version, TypeScript 7.0.2 and its normal dependencies, then invoke `bunx tsci --help`. The original failure was observed during setup; its terminal output was not saved as a standalone log. The delivered project pins and overrides TypeScript 5.9.3, which restores CLI operation. The exact responsible dependency change has not been isolated.

### P6 — Main routing aborts in the static reachability precheck

**Status: reproduced; checked native routes now replay through a guarded custom routing adapter. First investigation: [tscircuit/tscircuit-autorouter](https://github.com/tscircuit/tscircuit-autorouter), called through [core](https://github.com/tscircuit/core).** The current main source fails before global routing: `net.V3V3_mst9 (internal element->internal element)` / `source_net_1_mst9 (pcb_port_127->pcb_port_170)`, capacity-autorouter 0.0.988. The exact reservation/start-region conversion cause is not isolated; a failure alone does not prove the input is invalid or the solver algorithm is defective.

Evidence: [current build](validation/release-main-build.log). Reproduce with `bunx tsci build index.circuit.tsx --disable-parts-engine --autorouter-timeout 180s`. The same footprint placement/netlist has been independently completed and passes native DRC; 190 native main-board pad positions and named nets match the tscircuit circuit. The release is a native-routing workaround, not a claim that this platform failure was fixed upstream.

### P7 — Consecutive via route points export the connecting segment on the wrong layer

**Status: reproduced; explicit wire waypoint workaround. Owner: [tscircuit/circuit-json-to-kicad](https://github.com/tscircuit/circuit-json-to-kicad).** A top wire followed by top→bottom via, bottom→top via, then top wire should have a bottom segment between the vias. The converter's `getRoutePointLayer` handles `layer` and `through_pad`, but does not read a via's `from_layer`/`to_layer`; it inherits the previous top layer. In the initial flex export this caused crossings with the eight top tail traces, despite the tscircuit build passing.

Focused fixture: [via-via.circuit.json](validation/repros/via-via.circuit.json); [exported board](validation/repros/via-via.kicad_pcb). Export it with `tsci export ... -f kicad_pcb` and inspect the 4 mm vertical segment. The delivered TSX adds an intermediate bottom wire waypoint so the intended layer is explicit. Bundled converter observed: circuit-json-to-kicad 0.0.241.

## Low priority

### P2 — Flex route serialization fails after a successful build

**Status: observed; unresolved. Owner: [tscircuit/cli](https://github.com/tscircuit/cli) saved-route export path; underlying serializer ownership needs tracing.** `bun run build:flex` succeeds and emits routed Circuit JSON, but the CLI prints:

> Could not save autorouting paths for subcircuit_source_group_0: Routes contain a junction or endpoint that cannot select a unique PCB port

Evidence: [flex-build.log](validation/flex-build.log). Reproduce with `bun run build:flex`. The final geometry passes this project's short and connectivity checks; the failure concerns saving reusable autorouting paths. A minimal upstream reproduction has not yet been extracted.

### P3 — Schematic decoupler-grouping heuristic crosses named sections

**Status: observed diagnostic issue. Entry point: [tscircuit/cli](https://github.com/tscircuit/cli), `check schematic-placement`; heuristic comes from `@tscircuit/circuit-json-schematic-placement-analysis`.** The checker groups capacitors sharing a rail even when they serve different ICs in separate named schematic sections. For example, flex C14/C15 serve the optical sensor while C18 serves TMP117; the checker requests grouping all three together.

Reproduce: `bunx tsci check schematic-placement sensor-flex.circuit.tsx`. Evidence: [flex-schematic-placement.log](validation/flex-schematic-placement.log), also [main-schematic-placement.log](validation/main-schematic-placement.log). Expected improvement: respect section boundaries or identify the IC served before suggesting a decoupler cluster. The relevant analyzer repository has not been independently verified, so it is not assigned a guessed GitHub URL.

### P4 — Reserving an unbroken inner plane exceeded the routing time budget

**Status: observed performance limit; not a proven correctness bug. Entry point: [tscircuit/cli](https://github.com/tscircuit/cli) → [tscircuit/core](https://github.com/tscircuit/core) → autorouter pipeline.** Add `unbroken` to the main board's `GROUND_PLANE` copper pour and run `bun run build:main`. The solver remained in `pipeline9JointDrcRepairSolver` and the CLI aborted after 60.7 seconds under the configured 60-second limit.

Evidence: [attempt log](validation/main-unbroken-plane-attempt.log). This is an earlier timeout observation; the current main source instead stops in P6. The frozen native release retains a continuous inner GND plane. A longer timeout or another layout may succeed; no claim is made that unbroken planes are unsupported.

### P5 — CLI component search returns an unrelated part

**Status: reproduced. Owner: [tscircuit/cli](https://github.com/tscircuit/cli), search integration; upstream search-service cause not isolated.** Running `bunx tsci search MAX30102` returned only A2006HU-2x4P / C5180184, a connector housing rather than the requested optical sensor. Exact-ID import of MAX30102 C2839431 succeeded during this project.

Evidence: [current search output](validation/platform-search-max30102.log). Search results should match the requested part or report no match; returning this unrelated result makes component selection unreliable.

### P8 — Flex manufacturing metadata requires a separate artwork workflow

**Status: observed export limitation. Entry point: [circuit-json-to-kicad](https://github.com/tscircuit/circuit-json-to-kicad) / [CLI](https://github.com/tscircuit/cli).** Circuit JSON contains the flex material, three stiffeners and a static bend, but the normal PCB export does not supply separately identified PI/FR4 stiffener fabrication layers or a reviewed laser-coverlay definition. A standard solder-mask export is insufficient for this flex assembly. This is a fabrication-workflow gap, not evidence that all flex geometry is unsupported.

The release supplies explicit custom Gerbers and layer mapping through scripts/finish-fabrication.py, scripts/coverlay.py and manufacturing/rev-b/FABRICATION.md. The original metadata is retained in dist/sensor-flex/circuit.json.

### P9 — Successful flex build does not establish drill-to-drill clearance

**Status: observed validation gap; constrained to this required process rule. Investigation: [tscircuit/checks](https://github.com/tscircuit/checks) and autorouter rule propagation.** The passing routed flex had same-net 0.20 mm drills only 0.306/0.314 mm apart, leaving approximately 0.106/0.114 mm between holes. Native DRC against this project's 0.20 mm hole-gap requirement detected them. The source build did not enforce that additional requirement; no claim is made that its configured copper-clearance rule was violated by overlapping same-net annuli.

Evidence/coordinates: [via normalization record](validation/flex-via-normalization.json). scripts/merge-flex-vias.py retains one hole per overlapping pair and adds two surface links inside the original copper union. Final native drill, copper and connectivity checks pass. A user-configurable drill-gap check with propagation into routing would avoid this post-export step.