# adom-usbc — making USB-C receptacles actually work

**Read this before touching a USB-C receptacle on an Adom tscircuit
board.** Written because Claude got USB-C wrong ~20 times before we
wrote the rules down. If you skip this skill and try to wing it, you
will repeat every one of those failures.

## THE CORE INVARIANT — DO NOT VIOLATE

**Footprint (pads + holes) and cadModel (3D body) are tied together.
Whatever rotation you apply to one MUST be applied identically to the
other. Same rotation AND same translation.** They are one physical
object. Treating them as independently rotatable is the root cause
of every USB-C alignment bug we've hit.

Ways to satisfy this invariant:

1. **Bundle them in one component** with a single `pcbRotation` prop
   that applies to BOTH the `<chip>`'s footprint children AND the
   cadModel's `positionOffset`. The wrapper in §"The workaround"
   below does this — it computes `positionOffset` as `rotate(native_offset,
   pcbRotation)` in userland so the body rotates with the footprint.
2. **Compute body placement in the SAME local frame as the footprint.**
   Never express body offset in world coords while the footprint is
   in local coords. If you set `positionOffset` directly without
   rotating it by `pcbRotation`, the body will drift off its pads on
   every non-zero rotation.

The common violation: "I'll rotate the chip 270° for east edge, and
I'll add 2.5 mm positionOffset to shift the body forward." The first
rotation applies to pads/holes (tscircuit auto-rotates them in the
footprint local frame). The second shift applies to the body (in
world frame, no rotation). They decouple. The body ends up on the
wrong side of the pads, and the anchor holes end up OUTSIDE the body
footprint. I rebuilt this ~15 times before realising this was the
bug, not a tuning issue.

**Test for the invariant**: the distance between the body centroid
and each anchor hole must be the same at `pcbRotation=0` as it is at
`pcbRotation=90/180/270`. If that distance changes with rotation, the
invariant is broken, the build is wrong, and you must NOT ship the
board.

## The fundamental problem

`@tsci/seveibar.smd-usb-c` and `@tsci/ArnavK-09.smd-usb-c` both
hardcode a `cadModel` with:

```js
cadModel: {
  objUrl: "…easyeda_models/download?…pn=C165948",
  rotationOffset: { x: 0, y: 0, z: 180 },
  positionOffset: { x: 0, y: -2.5, z: 0 },
}
```

This works at the default `pcbRotation=0` (mouth facing south) because
`(0, -2.5)` puts the body 2.5 mm south of the pad centroid, which is
where the receptacle's body sits relative to its back-row of SMT pads.

**It breaks at every other rotation.** Two reasons:

1. **`positionOffset` is applied in world coords, not rotated with
   `pcbRotation`.** So at `pcbRotation=270` (pads rotated to the east),
   the body stays 2.5 mm south instead of moving 2.5 mm *east* with
   the pads. The body drifts off the pads and the mouth points into
   the board.
2. **The wrapper's `{...props, cadModel: HARDCODED}` spread order
   silently discards any `cadModel` override passed by the caller.**
   So you can't fix bug #1 by passing `cadModel` on `<SmdUsbC>`.

Filed upstream as `TSCIRCUIT_FEATURE_REQUESTS.md §6`.

## The workaround: a local `UsbCReceptacle.tsx`

Ship a local wrapper in your project's `lib/` that builds a raw
`<chip>` with an explicit footprint (copied from ArnavK-09's JSX) and
your own `cadModel` that rotates `positionOffset` with `pcbRotation`.
This survives `bun install`, gives you full control, and — critically
— you can unit-test it with the lint below without waiting on
upstream fixes.

### The template (copy this verbatim)

```tsx
// lib/UsbCReceptacle.tsx
const USB_C_PN = "C165948"
const USB_C_UUID = "2a4bc2358b36497d9ab2a66ab6419ba3"

// Body-to-pad offset in the mouth direction for TYPE-C-31-M-12.
// Measured: the SMT pad row sits at the BACK of the receptacle, and
// the body centroid is 2.5 mm forward of that. Centering body on pads
// (positionOffset 0) makes the back half of the body extend BEHIND
// the pads into the board — wrong geometry, even if numerics look
// "clean".
const BODY_FORWARD_MAG = 2.5

const pinLabels = {
  pin1:  ["GND1", "A1"],  pin2:  ["GND2", "B12"],
  pin3:  ["VBUS1", "A4"], pin4:  ["VBUS2", "B9"],
  pin5:  ["SBU2", "B8"],  pin6:  ["CC1", "A5"],
  pin7:  ["DM2", "B7"],   pin8:  ["DP1", "A6"],
  pin9:  ["DM1", "A7"],   pin10: ["DP2", "B6"],
  pin11: ["SBU1", "A8"],  pin12: ["CC2", "B5"],
  pin13: ["VBUS1", "A9"], pin14: ["VBUS2", "B4"],
  pin15: ["GND1", "A12"], pin16: ["GND2", "B1"],
} as const

// 16 SMT pads, pitch 0.5 mm, centered at y=0 so bounds.center = pad
// centroid (no holes included — see §Why we drop the holes).
const PADS: Array<{ port: string; x: number }> = [
  { port: "A1",  x: -3.35 }, { port: "B12", x: -3.05 },
  { port: "A4",  x: -2.55 }, { port: "B9",  x: -2.25 },
  { port: "B8",  x: -1.75 }, { port: "A5",  x: -1.25 },
  { port: "B7",  x: -0.75 }, { port: "A6",  x: -0.25 },
  { port: "A7",  x:  0.25 }, { port: "B6",  x:  0.75 },
  { port: "A8",  x:  1.25 }, { port: "B5",  x:  1.75 },
  { port: "B4",  x:  2.25 }, { port: "A9",  x:  2.55 },
  { port: "B1",  x:  3.05 }, { port: "A12", x:  3.35 },
]

export const UsbCReceptacle = ({
  name, pcbX, pcbY, pcbRotation = 0,
}: {
  name: string; pcbX: number; pcbY: number;
  pcbRotation?: 0 | 90 | 180 | 270
}) => {
  // Native CAD has mouth at local +Y. cad.rotation.z = pcbRotation
  // + rotationOffset.z (tscircuit adds them, CCW). We set
  // rotationOffset.z=0 so cad_z = pcbRotation. Then the mouth direction
  // in world frame is rotate((0,+1), pcbRotation CCW) =
  // (-sin pcbRotation, cos pcbRotation).
  const rad = (pcbRotation * Math.PI) / 180
  const mouthX = -Math.sin(rad)
  const mouthY =  Math.cos(rad)
  const posX = BODY_FORWARD_MAG * mouthX
  const posY = BODY_FORWARD_MAG * mouthY

  return (
    <chip
      name={name}
      pcbX={pcbX} pcbY={pcbY} pcbRotation={pcbRotation}
      supplierPartNumbers={{ jlcpcb: [USB_C_PN] }}
      manufacturerPartNumber="TYPE-C-31-M-12"
      pinLabels={pinLabels as any}
      cadModel={{
        objUrl: `https://modelcdn.tscircuit.com/easyeda_models/download?uuid=${USB_C_UUID}&pn=${USB_C_PN}`,
        rotationOffset: { x: 0, y: 0, z: 0 },
        positionOffset: { x: posX, y: posY, z: 0 },
      }}
      footprint={
        <footprint>
          {PADS.map(p => (
            <smtpad key={p.port} portHints={[p.port]}
              shape="rect" width="0.3mm" height="1.3mm"
              pcbX={`${p.x}mm`} pcbY="0mm" />
          ))}
        </footprint>
      }
    />
  )
}
```

## Per-edge placement recipe

For a board of width `W` centered at x=0 (so edges at ±W/2):

| Edge you want mouth to face | `pcbRotation` | `pcbX` | `pcbY` |
|---|---|---|---|
| South (bottom) | 0   | 0 or offset along x  | −(H/2) + 4 |
| East (right)   | 270 | +(W/2) − 4           | 0 or offset along y |
| North (top)    | 180 | 0 or offset along x  | +(H/2) − 4 |
| West (left)    | 90  | −(W/2) + 4           | 0 or offset along y |

`pcbX / pcbY` is the **chip origin** = **pad row centroid** position.
For a 64×32 board with USB-C on east edge: `pcbX=28, pcbY=0,
pcbRotation=270`. Pads at x=28 (inside the board by 4 mm), body at
x=28+2.5=30.5, mouth cantilevers to about x=34.5 (2.5 mm past edge).

### **Corollary: no SMT pad may extend past the board edge.**

The **body / mouth / mechanical shell** can and should cantilever
past the edge. SMT **pads** must not. If any copper pad (VBUS1/2,
GND1/2, DP1/2, DM1/2, CC1, CC2, SBU1/2) ends up at `|pcbX| > W/2`,
tscircuit grows the GLB board mesh asymmetrically to include the
overhang — and because the texture art is drawn with `pcbX=0` at
the canvas centre, the whole silkscreen / copper / annular-ring
layer renders shifted by `asymmetry/2` relative to the 3D mesh.
Every via drill appears off-centre in its annular ring, every
passive body appears shifted from its pad. The PCB itself is fine,
but the 3D view looks broken.

Real failure: a 72×32 board with the USB-C receptacle at `pcbX=35`.
That put the east-most SMT pads at `pcbX≈37.2`, growing the mesh
to `[-38.174, +37.2]` (centre `-0.487`) and shifting every copper
feature ~0.5 mm in the render. Fix: moved the receptacle to
`pcbX=33` (= `W/2 − 4 + overhang_0`). Mesh became `[-37.2, +37.2]`,
shift gone. **Use `pcbX = W/2 − 4` for the east edge; do not improvise.**

## Mandatory verification lint

**Run this after every build with a USB-C receptacle.** Not
optional. The only way we stopped getting USB-C wrong was by
gating on these two numeric checks:

```js
// scripts/check-usbc.mjs
import j from "./dist/lib/index/circuit.json" with { type: "json" }

for (const src of j.filter(x => x.type === "source_component")) {
  // Heuristic: USB-C receptacle = any chip with jlcpcb matching a
  // known USB-C family. Extend as new families are supported.
  const pn = src.supplier_part_numbers?.jlcpcb?.[0]
  if (!pn || !/^C(165948|2760486|283540|840342)/.test(pn)) continue

  const pc = j.find(x => x.type === "pcb_component"
                      && x.source_component_id === src.source_component_id)
  const pads = j.filter(x => x.type === "pcb_smtpad"
                          && x.pcb_component_id === pc.pcb_component_id)
  const cad = j.find(x => x.type === "cad_component"
                        && x.pcb_component_id === pc.pcb_component_id)
  const board = j.find(x => x.type === "pcb_board")

  const padCx = pads.reduce((s, p) => s + p.x, 0) / pads.length
  const padCy = pads.reduce((s, p) => s + p.y, 0) / pads.length
  const rot   = cad.rotation.z * Math.PI / 180
  const mX    = -Math.sin(rot), mY = Math.cos(rot)

  // Check 1: body forward of pads by ~BODY_FORWARD_MAG in mouth dir
  const fwd = (cad.position.x - padCx) * mX + (cad.position.y - padCy) * mY
  if (fwd < 1.5 || fwd > 3.5) {
    throw new Error(`${src.name}: body_forward=${fwd.toFixed(2)} mm; expected ~2.5.
      Body is ${fwd < 0 ? "BEHIND" : "too close to"} pads — geometry wrong.`)
  }

  // Check 2: mouth ray exits the board outline
  const ray = { x: cad.position.x + 12 * mX, y: cad.position.y + 12 * mY }
  const bx = board.center?.x ?? 0, by = board.center?.y ?? 0
  const inside = ray.x >= bx - board.width/2 && ray.x <= bx + board.width/2
              && ray.y >= by - board.height/2 && ray.y <= by + board.height/2
  if (inside) {
    throw new Error(`${src.name}: mouth points INTO the board at ${ray.x.toFixed(1)},${ray.y.toFixed(1)}.
      Cable would collide with FR4. Rotate receptacle 180° (toggle rotationOffset.z 0↔180).`)
  }

  console.log(`✓ ${src.name}: body_fwd=${fwd.toFixed(2)}mm, mouth dir (${mX.toFixed(2)},${mY.toFixed(2)}) exits board at (${ray.x.toFixed(1)},${ray.y.toFixed(1)})`)
}
```

**Wire it into your build loop:**

```bash
bunx tsci build lib/index.tsx --glbs --svgs && adom-tsci lint
```

`adom-tsci lint` does exactly the checks above (for every JLC USB-C
part in its known list) plus catches ghost chips and autorouter
silent-failures. Same exit-code gating. Prefer it over the inline
`node -e` above — it's shipped with the tool and maintained
alongside the lint rules.

Or if you only have `node` and not `adom-tsci lint`:

## Visual proof-of-placement (the toggle-and-shotlog ritual)

**Numeric lint can be gamed.** A body can satisfy `forward_dot >= 1.5`
yet still be visually misaligned with the pad geometry if a footprint
dimension is wrong. After every USB-C placement change, do this
three-step visual proof:

```bash
# 1. Top view with receptacle visible
adom-tsci view top --port 8853
adom-desktop browser_screenshot '{"sessionId":"<project>","maxWidth":1800}'
shotlog inject -c usbc-validate -d "USB-C placed on east edge, body visible cantilevered off the board" -s pup_screenshot <path>

# 2. Hide the receptacle to see the pads underneath
adom-tsci toggle-component J1 --port 8853 --hide
adom-desktop browser_screenshot '{"sessionId":"<project>","maxWidth":1800}'
shotlog inject -c usbc-validate -d "USB-C hidden; pads underneath should be flush with board east edge, all 16 pads on copper" -s pup_screenshot <path>

# 3. Un-hide
adom-tsci toggle-component J1 --port 8853 --show
```

The user reads the two screenshots side-by-side and confirms:
- Body cantilevers off the correct edge (mouth away from board)
- The pads sit inside the board (none hanging off)
- Pad row aligns with where the body's back edge is

**If you don't post both screenshots to shotlog, the user can't
verify, and you can't claim the placement works.** "The lint passes"
is necessary but not sufficient.

## Include ALL mounting holes — do NOT drop them to simplify the math

**The rule:** the TYPE-C-31-M-12 footprint must include all 4 plated
corner anchor holes + 2 drill-only support holes. Without the anchors
the connector is held by 16 tiny SMT joints only, which tear off the
board under cable insert/extract stress in well under 100 cycles. A
USB-C port that rips loose after a week is a bug, not a trade-off.

**The compensation:** tscircuit computes `pcb_component.center` as
the bbox of pads + holes. For the TYPE-C-31-M-12 layout (pads at
local y=0, holes at y ∈ {-1.04, -1.27, -5.22}), the bbox center sits
2.61 mm south of the pad centroid. To keep the cad body 2.5 mm
forward of the pad row, bump `BODY_FORWARD_MAG` from 2.5 to 2.5 +
2.61 = **5.11** in the wrapper template.

Formula for any directional connector with asymmetric holes:

```text
BODY_FORWARD_MAG = body_over_pads + |bbox_center_y − pad_row_y|
```

Measure the bbox shift by building once with holes included, reading
`pcb_component.center` from `circuit.json`, and subtracting your
known pad row y.

Filed upstream as TSCIRCUIT_FEATURE_REQUESTS §6.1: `cadModel` should
accept `boundsSource: "pads" | "all"` so we don't have to compensate
in userland. Until then, the compensation above is load-bearing.

## Failure modes → diagnosis table

| Symptom | Cause | Fix |
|---|---|---|
| Body visible but pads hanging off the board edge | `pcbX/Y` too close to the edge; pads should be INSIDE copper | Move `pcbX` inward by ~4 mm |
| Mouth points into the board (butt cantilevers off edge) | `rotationOffset.z` is wrong by 180° | Flip `rotationOffset.z` (0 ↔ 180) |
| Body drifts diagonally off the pads at non-zero rotation | You used upstream `SmdUsbC` without the rotation-compensation | Switch to the local `UsbCReceptacle.tsx` wrapper above |
| Body centered on pads, but half the body extends into the board | `positionOffset` is (0,0); forgot `BODY_FORWARD_MAG * mouth_dir` | Add the forward-offset math |
| USB-C missing from Components HUD in adom-tsci | refdes doesn't match `/^J[\d_]/i` OR no cad_component emitted | Rename to `J1`/`J_1`; check `circuit.json` for `cad_component` row |
| `pcb_autorouting_error: Failed to solve 1 nodes` after adding USB-C | USB-C pads near high-density chip pin row | Move USB-C further from adjacent chips, or grow board |

## Upstream feature requests

See `adom-tsci/TSCIRCUIT_FEATURE_REQUESTS.md §6` for:
- cadModel.positionOffset should co-rotate with pcbRotation
- @tsci wrappers should use `{ cadModel: props.cadModel ?? DEFAULT, ...props }` so caller overrides work
- bounds.center should be opt-in pads-only for cadModel placement