Devesh36/pocket-audio-player

BUGS.md

# Issues encountered while building the audio-player PCB and enclosure

Observed on 10 October 2026 with tscircuit 0.0.2757, core 0.0.2106, props 0.0.695 and capacity-autorouter 0.0.958. These are new observations from this board. The earlier double-row-header and RP2040 crystal-capacitance issues are not counted again.

**Five reproduced tooling problems, one confirmed CLI publication-recovery failure, one reproduced GLB color-loss problem, and one routing problem under investigation.** Repeated diagnostics and downstream unconnected-pin errors are not counted as separate bugs. Repository ownership below identifies the relevant subsystem; where the cause spans packages, it is explicitly provisional.

## 1. Exact part searches return unrelated components

Encountered while selecting the buck-boost regulator and battery charger.

- Query `TPS63031DSKR` returned NTC 10D-9, C6793810.
- Query `MCP73831T-2ACI/OT` returned a USB connector, a rectifier and a varistor.
- SS14 and AO3401A searches also returned unrelated components.
- The intended parts exist and importing their explicit LCSC numbers succeeded: TPS63031DSKR C15516, MCP73831 C424093, SS14 C2480 and AO3401A C15127.

The first two results reproduced in a second live request. Evidence: `logs/part-search-results.json` and `logs/part-search-recheck.log`.

Relevant repository: [tscircuit/jlcsearch](https://github.com/tscircuit/jlcsearch). The live search failure is confirmed; the exact server, cache or database cause has not been isolated. Workaround used: verify the manufacturer's part and import its LCSC identifier.

## 2. React's key attribute is rejected for several JSX elements

Encountered when generating arrays of schematic sections, custom inductor pads, mounting holes and silkscreen labels. TypeScript produced **four TS2322 errors** because `key` was absent from the intrinsic element types for `schematicsection`, `smtpad`, `hole` and `silkscreentext`.

A minimal reproduction independently produces the same four errors. Evidence: `bugs/repros/jsx-key-typing.tsx`, `bugs/repros/key.tsconfig.json`, and `logs/repro-jsx-key.log`.

Relevant repository: [tscircuit/core](https://github.com/tscircuit/core), especially its JSX intrinsic-element declarations and their use of [props](https://github.com/tscircuit/props). Workaround used: place `key` on a React Fragment around each element. The board typecheck passes with this workaround.

## 3. Automatic LED selection creates a polarity mismatch

Encountered when adding the charging indicator as a generic red `0603` LED. Parts lookup selected C3030991, whose pin 1 is the cathode, while the generic LED has pin 1 as the anode. The build correctly reported a supplier polarity mismatch, plus a footprint copper-overlap mismatch.

The minimal circuit `bugs/repros/led-part-selection.circuit.tsx` independently selects the same part and fails with the same diagnostics. Evidence: `logs/repro-led-selection.log` and the original `logs/placement-4.log`.

Relevant repositories: [tscircuit/parts-engine](https://github.com/tscircuit/parts-engine) for selection and [tscircuit/core](https://github.com/tscircuit/core) for applying the supplier pin mapping. The resulting mismatch is confirmed; selection versus mapping responsibility still needs isolation. Workaround used: an explicit HSMS-C170 part, its imported footprint and verified pin labels.

## 4. pcbPathRelativeTo can replace the intended trace endpoints

Encountered when drawing the crystal traces and using a common MCU pin as their coordinate reference.

The minimal circuit requests `R1.pin2 → R2.pin1`, with `R3.pin1` used only as the path coordinate reference. Generated PCB copper instead joins **R3.pin1 → R1.pin2**. R2 is omitted. The source connection still names R1 and R2.

The trace documentation describes this property as a coordinate reference. The current implementation reuses that reference as the routing start port. Evidence: `bugs/repros/pcb-path-reference.circuit.tsx`, `logs/pcb-path-reference-evidence.json`, and `scripts/check-path-repro.test.ts`. The `test.failing` assertion checks that copper endpoints remain R1 and R2; its expected failure reproduces the mismatch.

Relevant repository: [tscircuit/core](https://github.com/tscircuit/core), Trace PCB rendering. [Trace documentation](https://docs.tscircuit.com/elements/trace). Workaround used: each manual crystal path is relative to its own starting component, including that component's rotation.

## 5. Live viewer cannot resolve an installed autorouter dependency

Encountered when opening the completed board in `tsci dev`. Importing `AutoroutingPipelineSolver9_PreloadedTraceGraph` causes `Import "object-hash" not found in "node_modules/@tscircuit/capacity-autorouter/dist"`. The installed `object-hash` package exists (3.0.0). A minimal circuit using only that import and one silkscreen label produces the same browser error while its CLI build succeeds.

Evidence: `bugs/repros/autorouter-browser-import.circuit.tsx`, `logs/repro-browser-import-cli.log` and `logs/repro-browser-import-viewer.log`. The live viewer reports eval 0.0.1589/core 0.0.2105, while this local CLI uses eval 0.0.1571/core 0.0.2106. The different runtimes are recorded rather than assumed identical.

Relevant repository: [tscircuit/eval](https://github.com/tscircuit/eval), with CLI dev integration and the autorouter's browser packaging also candidates. The module-loading failure is reproduced; its exact dependency-resolution cause is not isolated. Workaround used: the preview loads the validated route snapshot without importing the solver. A fresh CLI route loads the solver dynamically from `fresh-router.ts`.

## 6. A completed autoroute still contains invalid or incomplete copper

The first native four-layer route reported `errors=0` and 257 routed traces. Core's subsequent checks returned **16 routing diagnostics**: two unconnected DAC ground pins, two overlength crystal paths, two excessive-via errors, one accidental trace-to-pad contact, one via-to-trace clearance violation, four via-to-pad clearance violations, two via-spacing violations and two via-hole/SMD-pad overlaps.

Evidence: `logs/routing-2.log` and `logs/routing-2-diagnostics.json`. These 16 diagnostics form one routing/integration investigation, not 16 proven independent software bugs. The solver's internal success does not establish PCB correctness.

Relevant repositories: [tscircuit/tscircuit-autorouter](https://github.com/tscircuit/tscircuit-autorouter) and [tscircuit/core](https://github.com/tscircuit/core). A subsequent routed USB pair also had two self-contacting meanders and 1.52 mm skew despite a 0.5 mm requested limit (`logs/routing-9-diagnostics.json`). Exact responsibility for endpoint integration, via geometry, length matching and constraint propagation remains unconfirmed. The later fresh route produced 13 PCB diagnostics (`logs/routing-13-diagnostics.json`) and four wire points narrower than the board's 0.12 mm minimum (0.06 mm at the inductor endpoints). The routing investigation also includes these generated geometry violations.

Workarounds on this board: explicit no-via crystal paths, an explicit USB pair, explicit DAC ground ties, adjusted via positions, three 0.35 mm via pads with 0.20 mm drills, a corrected inductor segment, and a bottom-layer QSPI3 escape. All changes remain in tscircuit's native route representation. The final build has **zero PCB error records**, and the Gerber short check reports **no shorts on all four layers at 40 pixels/mm**. See `logs/release-build.log`, `logs/final-shorts.log` and `validation.json`. This does not establish measured hardware operation.

## Other encountered errors, excluded from the software-bug count

- Initial component/courtyard overlaps and pad clearances were my layout errors. They were corrected by moving components.
- A3 is not an accepted schematic-sheet enum in the installed version; the board uses A4 with an explicit drawing area.
- Partial `pinAttributes` overrides on imported components required the appropriate complete typed mapping. The component imports now contain their supply attributes.
- An invalid `insertionDirection="y-"` caused a runtime TypeError. TypeScript also rejects that value; it is excluded because the input was invalid. Valid directions are used in the finished source.
- Disabling parts lookup left the generic USB-C connector without a footprint. An explicitly imported C165948 footprint resolves this dependency.
- A standard header and the supplier header had different pad geometry, producing a valid footprint mismatch warning. This was not a double-row selection bug. The explicit supplier footprint is now used.
- The native route-save step reported non-unique `.Q_SHARE > port.pin2` and `.J_AUX > port.pin4` selectors. Its cause was not isolated; routing snapshots are stored explicitly and guarded against stale input. This warning is recorded without counting another confirmed bug.
- Early custom-router runs were slow, and one reached the 180-second timeout. The adapter yielded after too few solver steps; its scheduling was corrected. These runs are excluded from the tscircuit-bug count because the adapter caused the delay.

- Transient supplier-footprint fetch failures, a stock/availability warning, and a local disk-space failure occurred during verification. They are recorded as service/environment conditions, not confirmed tscircuit bugs. Checks were rerun.
- Gerber export cannot verify the pick-and-place rotations for L1 and J_AUX because their required pin-1 metadata is absent. Assembly orientation needs a manual check.

- The placement command reports five suboptimal orientations and returns exit 1. Its DRC reports zero errors and zero warnings; the full routed build and Gerber shorts check pass. These orientation suggestions are excluded from the software-bug count.

No upstream issues or PRs were created for these observations.

## Enclosure assembly — 2026-10-11

The assembly builds with the PCB's existing saved routing input unchanged. A separate CLI publication-recovery bug was encountered after enclosure authoring, as recorded below.

- My first locating tongue was inset from the shell without a joining ledge. A connected-surface mesh check caught the separate solid; the final base includes the ledge. This was an enclosure-design mistake.
- The first custom ASCII STL export had unmatched triangulated edges. The export now preserves shared CSG boundary vertices and uses face-centre triangulation. Every final STL has zero unmatched or inconsistently oriented edges and one connected surface. This is recorded as an export-workflow correction, without attributing it to a tscircuit repository.
- Uploading the large optional GLB previews timed out in the registry. The published package contains assembly source and compact printable assets; GLBs remain in the local project bundle. This is a service/upload condition, not a confirmed geometry bug.

Evidence: `dist/enclosure/fit-check.json`, `dist/enclosure/mesh-check.json`, `scripts/check-enclosure.tsx` and `scripts/check-enclosure-mesh.ts`. Physical fit, the external OLED module, battery retention and printing tolerances remain untested.

### 7. Archive upload succeeds but timeout fallback reports every file as failed

**Confirmed observed behavior in @tscircuit/cli 0.1.2277.** While publishing enclosure release 1.0.6, `tsci push --include-dist --compress` timed out waiting for `/package_files/upload_archive`. Its fallback called `/package_files/create` for every file. All 59 requests failed with HTTP 500 and `duplicate key value violates unique constraint "package_release_filepath_pkey"`; the CLI returned exit 1 and left `ready_to_build` false.

The registry file-list API nevertheless contained all 59 files. Downloaded main assembly source, enclosure source, cloud-build config, assembled Circuit JSON and all three STLs matched their local files byte for byte. Recovery completed the normal `/package_releases/update` step with `ready_to_build: true`, using the existing authorized CLI session.

Responsible path: **tscircuit/cli**, `lib/shared/push-snippet.ts`. The installed bundle contains the archive timeout fallback, unconditional per-file `create` calls and early exit before publication when every fallback request fails. The initial HTTP timeout may be a service condition; the confirmed problem is that recovery cannot recognize an already committed archive.

Evidence: `logs/enclosure/publish-cloud-retry.log`, `logs/enclosure/recovered-upload-file-list.json` and the source around lines 84779–84851 in the installed CLI library. A separate earlier cloud job reported `user_code_job_infrastructure_error` / `ReadableStream received over RPC disconnected prematurely` after writing both Circuit JSON outputs; its internal infrastructure cause is unconfirmed. Cloud builds now target only `index.circuit.tsx`; the exploded entry remains available for explicit inspection. No upstream issue or PR has been created for this new observation.

The release 1.0.6 retry also ended with `user_code_job_infrastructure_error`. Its stream reached `bun install` and then disconnected before circuit compilation. This demonstrates a cloud/runtime failure independently of the enclosure geometry; the internal server/network cause remains unconfirmed. See `logs/enclosure/cloud-retry-release.json` and `logs/enclosure/cloud-retry-build-stream.log`. The uploaded native Circuit JSON and online 3D view remain usable.

## 8. Native GLB export loses JSCAD display colors — 2026-10-11

While adding the OLED with `assembly.screen`, its tscircuit-authored green module, dark glass and cyan sample pixels exported as one gray material. The source uses multiple `jscad.colorize` elements. `tsci export oled-shape.tsx -f glb -o dist/enclosure/oled-model.glb` succeeds, but its mesh has no `COLOR_0` attribute and one uniform gray material. The imported 3D screen consequently appeared pale and its text was hard to read.

The relevant subsystem is **tscircuit/circuit-json-to-gltf**, used by the CLI's native GLB export. Exact internal ownership of the flattening operation has not been isolated. The project workaround restores per-triangle colors in `scripts/embed-oled-model.ts` after the native export. This changes the display asset only; it does not alter PCB geometry or routing. The native exporter’s coordinate convention also requires a root rotation when reimporting the model into assembly CAD; that convention adjustment is not counted as a separate bug.

Evidence: `oled-shape.tsx`, `logs/screen/model-export.log`, `dist/enclosure/oled-model.glb` (unmodified native output) and `logs/screen/native-glb-color-evidence.json`. No upstream issue or PR has been created.

Screen release 1.0.7: per-file publication returned HTTP 413 for the two formatted Circuit JSON files. Compact JSON reduced each from about 4.1 MB to 2.8 MB without changing the circuit. Both uploads then succeeded, and all 63 files were present before completing `ready_to_build`. Seven critical source/model/Circuit JSON/STL files were downloaded and matched the staged bytes. This upload-size condition is recorded separately from the confirmed software-bug count. See `logs/screen/push.log`, `upload-recovery.log` and `remote-verification.json`.

### Cloud build failure for release 1.0.7 — 2026-10-11

The job `5aa93b4ec63bc1f8bc4c2a511a05d1d8d5cefdf1e1f0b00b10dbfed878d2cc73` wrote all source files, created bundled dependency links, then stopped at `bun install`. After about four minutes it failed with `ReadableStream received over RPC disconnected prematurely`; release metadata classifies it as `user_code_job_infrastructure_error`. There is no board compilation error in this log.

The published manifest has been reduced to its tscircuit dependency, and `alwaysUseLatestTscircuitOnCloud` selects the bundled cloud runtime. Local CI using this setup finishes dependency installation in 11 ms and passes circuit generation, preview generation and transpilation. Its PCB geometry matches the existing board, with zero PCB errors. The same unlocked release was updated through `package_files/create_or_update` and rebuilt through `package_releases/rebuild`. A cloud success is not claimed until the new job completes.

Evidence: `logs/screen/release-build-failure.json`, `release-build-failure-stream.log`, and `logs/screen/cloud-build-fix/`. The infrastructure disconnect’s internal cause is still unconfirmed; this packaging change avoids reinstalling the full local toolchain but is not evidence of a server-side root-cause fix.

The revised release’s retry failed before creating any sandbox. The server reports `Maximum number of running container instances exceeded`, retries 11 times across 10 instances, and ends with `Failed to create sandbox after 11 attempts`. It never writes the revised board files or runs dependency installation. This confirms a separate concrete cloud-service capacity blocker; it does not establish the original RPC disconnect’s underlying cause. Release 1.0.7 still has a failed cloud job, despite a passing local CI build. The recorded dependency change remains locally validated but cannot be verified on the cloud until its worker capacity is available. No upstream issue or PR has been created for this server-capacity observation.

### Reference-style assembly: thin marker rendering (ownership unconfirmed)

The native 3D export dropped the top faces of the `m`/`e` glyphs and parts of the playback icons when the disconnected 0.025 mm marker solids were combined by a CSG union. This was visible even with the case removed from the scene: `logs/ipod-reference/isolated-legends.png` and `label-loss-before.json` preserve the result and CAD input. Serializing each authored marker's native JSCAD polygons without Boolean fusion restores the complete text and symbols (`fixed-legends.png`). `scripts/generate-mechanical-models.tsx` applies this workaround to the control and battery legends. Exact ownership between the native export pipeline and its JSCAD dependencies has not been isolated; this observation is not added to the confirmed upstream bug count.

## Real display and battery connector revision — 2026-10-11

The 1.9-inch ST7789V2 module uses SPI, not the previous conceptual display's I²C. Its GH socket contact order comes from the manufacturer schematic. JST's **mated** GH connector height is 7.3 mm, so the PCB socket is placed below the screen footprint rather than under the module. PCB courtyard conflicts from initial passive placement were corrected; these were design errors, not tscircuit bugs.

The `platedhole` JSX element also rejects React's `key` prop with TS2322. A keyed Fragment resolves it, matching problem 2's existing workaround; this is not counted as a new independent bug. The native CAD GLB export again flattened colors from the manufacturer meshes and menu overlay. Per-vertex colors are restored after native export, as in problem 8.

A full fresh autoroute reported `errors=0` but the subsequent native PCB checks found **10 violations**: four drill/pad overlaps, two via/pad clearance failures, two headphone-trace/non-plated-hole clearances and two other copper-clearance failures. This confirms that solver completion alone is insufficient. Evidence: `logs/low-profile/fresh-routing.log` and `logs/low-profile/fresh-routed-circuit.json`. The relevant packages are capacity-autorouter's returned copper and core/checks' independent validation; the exact solver cause is not isolated. This is additional evidence for the existing routing problem, not ten distinct software bugs. The incremental reuse attempt reached the 240-second routing timeout. A second fresh native route with explicit via/pad and hole clearance produced eight core violations. Local copper refinements cleared them without relaxing the checks; shared via coordinates are updated together. The final saved native routes and refinement notes are retained in `routing/`. Final PCB and all-layer Gerber checks are recorded in `validation.json`.

## Further case thinning — 2026-10-11

Reducing the shell to 18.1 mm exposed a design-fit problem in an additional populated-body check: the right upper LCD mounting stud intersected the AUX jack model (5.62 mm³ precise mesh overlap in the first candidate). The LCD and its window/mounts were moved 6.8 mm lower, retaining horizontal centering. The final screen clears all 21 supplied PCB body models. This is a board/assembly layout error, not a newly confirmed tscircuit bug. The battery wire paths were lowered to clear the shortened button levers throughout the checked 0.45 mm travel. PCB placement, copper and charging connections are unchanged.

Evidence: `scripts/check-lcd-pcb-fit.ts`, `dist/enclosure/lcd-pcb-fit.json`, `dist/enclosure/fit-check.json` and `validation.json`. Unmodeled bodies, screws and cable tolerances still require a physical prototype.