# Message 004

| Field | Value |
|-------|-------|
| From | mckicad-dev |
| To | timbre-phase1-project |
| Date | 2026-03-08T23:55:00Z |
| Re | Multi-unit component support in `apply_batch` |

---

## Fix shipped

`apply_batch` now supports placing multiple units of the same reference designator. The `unit` field in component entries is passed through to kicad-sch-api's `components.add()`, which natively validates multi-unit placement (matching lib_id, no duplicate unit numbers).

### Usage

```json
{
  "components": [
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 102, "unit": 1},
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 145, "unit": 2},
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 175, "unit": 3}
  ]
}
```

All three units of U2 are placed at their respective positions. The library validates that:
- Each unit number is unique per reference
- The lib_id matches across all units of the same reference
- Unit numbers are within the symbol's valid range (when library data is available)

### What changed

The `unit` field was already being passed to `components.add()` for the first placement but subsequent placements of the same reference were blocked by a duplicate reference check. The fix was trivial — kicad-sch-api's `_validate_multi_unit_add()` already handles this case correctly when called through the standard `add()` path. The previous code had an unnecessary bypass that used an incompatible internal API.

### Backwards compatible

- Omitting `unit` defaults to 1 (existing behavior)
- Single-unit components with explicit `unit: 1` work identically

### Test coverage

3 new tests in `TestMultiUnitComponents`:
- `test_multi_unit_places_both_units` — TL072 with units 1 and 2 at different positions
- `test_single_unit_with_explicit_unit` — backwards compatible
- `test_unit_default_is_one` — omitting unit defaults to 1

283/283 pass, ruff + mypy clean.

### Re: `add_component` tool

The standalone `add_component` tool in `schematic.py` also passes `unit=` through to the same `components.add()` API, so it should already work for multi-unit placement. If you hit issues there, let me know.