{
  "hot": {"Q1": {"watts": 5.5, "tabNet": "LOAD_POS"}},
  "packageCooling": [{
    "reference": "Q1",
    "junctionCaseKPerW": 0.42,
    "caseSinkKPerW": 0.53,
    "sinkAmbientStillKPerW": 8.0,
    "sinkAmbientMovingKPerW": 1.5,
    "boardLinks": [],
    "provenance": "Illustrative only: replace every parameter with justified assembly data; empty boardLinks explicitly assumes no package-to-board conduction"
  }]
}

# Package-to-heatsink thermal paths

`packageCooling` adds explicit junction, case and sink nodes for a named `hot` component. It is a steady-state network supplied by the caller. It does not calculate fin airflow, fan pressure, mounting pressure, contact quality or fault transients.

The component's `hot.watts` enters its junction once. That component's old board heat injection is removed, while all other chip heat and PCB Joule losses remain. The junction connects to the case; the case connects to the sink and any declared board terminal links. The sink loses heat through separate supplied still-air and moving-air resistances. Board heat may flow back into the case and sink. Negative `boardCouplingW` is valid; it must not be clamped away.

```json
{
  "hot": {"Q1": {"watts": 5.5, "tabNet": "LOAD_POS"}},
  "packageCooling": [{
    "reference": "Q1",
    "junctionCaseKPerW": 0.42,
    "caseSinkKPerW": 0.53,
    "sinkAmbientStillKPerW": 8.0,
    "sinkAmbientMovingKPerW": 1.5,
    "boardLinks": [],
    "provenance": "Illustrative only: replace every parameter with justified assembly data; empty boardLinks explicitly assumes no package-to-board conduction"
  }]
}
```

These example numbers are not an approved electronic-load cooling design. Do not infer an installed fan velocity from a sink's catalog rating. An empty `boardLinks` list is explicit isolation, not an automatic approximation for TO-220 leads. To model a terminal, add a link such as `{"pad":"2","at":[127.46,80.8],"layer":"F.Cu","resistanceKPerW":20.0}` using the **actual** physical pad coordinates and a justified package-to-pad thermal resistance. The example coordinate/resistance is illustrative. Every link must resolve to exactly one physical pad on the named copper layer and inside the solve grid. Repeated logical pin numbers need distinct coordinates. Links are point couplings to solve cells; assess mesh sensitivity and contact-model suitability.

Every resistance must be finite and positive. References must exist in `hot` and occur once in `packageCooling`. Provenance is required. Typos within a package/link object, duplicate links, wrong layers and missing/ambiguous pads are rejected.

## Results and acceptance boundary

`packageCooling[]` in the result includes the definition and, for both air states, junction/case/sink rises, source watts, signed case-to-board watts, sink-to-ambient watts and an energy residual. The command refuses an unbalanced result. The viewer lists these values separately from board-face blocks; it does not invent a heatsink mesh.

For a package-mode component, the legacy chip `riseC`/`riseMovingC` fields are conservatively the maximum of the board terminal-region temperature, case and junction. Existing thermal checks therefore cannot hide an overheated external node behind a cool PCB pad. Board texture scales remain board temperatures. The package temperatures have their own result fields. Nearby copper/via fluxes still describe the PCB region; they are not fractions of the total package dissipation.

Still-air remains a full-power steady-state case. A tach-controlled shutdown does not justify changing it to zero watts or waiving it. Fault-dependent transient acceptance requires a separate supported model, measured detection timing and appropriate thermal capacity data. This feature supplies none of those.

## Validation

Analytical tests exercise an uncoupled series network, equal parallel board/sink paths, reverse heat flow from a hotter board, energy conservation and invalid parameters. Integration tests ensure package power is not also deposited on the PCB and the legacy chip result still sees a hot junction. Physical-pad identity and wrong-layer checks are exercised.

Run the CLI fixture against `docs/fixtures/conducting-block/board.kicad_pcb` with `docs/fixtures/package-cooling/spec.json`, `--pitch 0.2 --no-parts --no-silk`. Its 2 W source and 0.5/1/3 K/W series path give +9 C junction, +8 C case and +6 C sink in still air; moving air gives +7/+6/+4 C. This validates arithmetic and integration, not an assembled board. The fixture intentionally isolates the package from the board.

This source feature is independent of the pending actual-layer/barrel/physical-terminal improvements. Those changes remain necessary before applying the current shared Fields base to the electronic load's two-layer board. Do not replace another owner's shared runtime or call a review build a release.