[seveibar]

Unsupported PCB folds and rigid placements in bend zones are expected geometry limitations, but consumers currently have to catch arbitrary exceptions to keep a design renderable. Add explicit shared folding results so renderers can retain flat geometry only for known limitations while unexpected failures still reject.

• Add PcbFoldIssue, PcbFoldError, and PcbFoldResult<T>, with stable issue codes and optional bend IDs. Existing strict APIs preserve their error messages.
• Add tryCreatePcbFold and tryFoldSurfaceMesh, including legacy full-cross-section validation that occurs during surface deformation.
• Share rigid mesh deformation through foldRigidMesh/tryFoldRigidMesh. Validate an optional PCB mount separately from model extents, so CAD offsets cannot conceal an invalid mount.
• Reuse rigid mesh deformation for stiffeners and expose tryFoldStiffenerMesh for already-created flat meshes, preserving the original outline-average anchor without duplicate extrusion.
• Keep malformed board/polygon/stiffener data, missing CAD references, and unexpected transformation failures as exceptions. CAD pose normalization remains strict.

Supports the explicit fallback implementation in tscircuit/circuit-json-to-gltf#230 for tscircuit/tscircuit#5277. Consumers can choose their rendering/reporting policy; flex-utils does not log or automatically select flat geometry.

Validation: bun test passes all 24 tests (1,329 assertions); typecheck and build pass. Tests cover structured diagnostics, unexpected-error propagation, legacy surface failures, separately validated offset CAD mounts, rigid positions/normals/metadata, unchanged input geometry, and stiffener reuse. The new common toMatchPngSnapshot/PoppyGL snapshot shows a valid board and blue CAD folded together while the invalid red bend-zone placement stays flat; the image was visually inspected. Existing snapshots remain unchanged.

[tscircuitbot]

---

Thank you for your contribution! 🎉

PR Rating: ⭐⭐⭐
Impact: Major

Track your contributions and see the leaderboard at: tscircuit Contribution Tracker

---