# pcbnew (PCB editor) — bridge specifics

Differences from `0001-general-bridge-design.md`. pcbnew implements the **same unified bridge
contract** (general §1) with the **richest** native hooks of the three. Two things dominate its
specifics: **mandatory connectivity/ratsnest recompute** and **scale** (10k–100k+ items).

## Adapter — native (richest of the three) — and *why*
- **Identity free:** `BOARD_ITEM` ⊂ `EDA_ITEM` → `const KIID m_Uuid` (`include/eda_item.h:516`),
  serialized as `(uuid …)` on every item by `PCB_IO_KICAD_SEXPR` (e.g. track
  `pcb_io_kicad_sexpr.cpp:2619`, footprint `:1170`, zone `:2647`). Fast lookup via
  `std::unordered_map<KIID, BOARD_ITEM*> m_itemByIdCache` (`board.h:1458`). **No format change.**
- **Granular change set:** `BOARD_COMMIT::Push` (`pcbnew/board_commit.cpp:176–631`) tags each
  entry `CHT_ADD/REMOVE/MODIFY` and collects bulk add/remove/changed vectors.
- **Native observer — hook without patching core:** `BOARD_LISTENER` (`board.h:283–301`) is the
  richest interface — singular *and* bulk callbacks, plus a combined one:
  ```cpp
  OnBoardItemAdded/­ItemsAdded · OnBoardItemRemoved/­ItemsRemoved
  OnBoardItemChanged/­ItemsChanged · OnBoardNetSettingsChanged
  OnBoardHighlightNetChanged · OnBoardRatsnestChanged
  OnBoardCompositeUpdate(board, added[], removed[], changed[])   // ← one event, all three sets
  ```
  Registered via `board->AddListener(bridge)` (`board.cpp:2964`); fired through
  `InvokeListeners(...)` (`board.h:1424`). `BOARD_COMMIT::Push` → `OnItemsCompositeUpdate`
  (`board_commit.cpp:580` → `board.cpp:3001`). **`OnBoardCompositeUpdate` is the ideal single
  emit hook.**

## Model — typed containers (vs flat list / vs rtree)
8 typed containers, not one list (`board.h:1447–1455`): `m_footprints`, `m_tracks`, `m_zones`,
`m_drawings`, `m_groups`, `m_generators`, `m_markers`, `m_points`. The Yjs shape is still a
**flat uuid-keyed `Y.Array`** — `type` tells apply which container `BOARD::Add` routes to;
`m_itemByIdCache` resolves uuid→item in O(1).

## ChangeSource (emit)
`BOARD_LISTENER::OnBoardCompositeUpdate` → emit per-item JSON for added/changed (uuid+type+
fields) and uuid-only for removed. **Converter strategy: reflection for the bulk + native blob
for the long tail** — pcbnew uniquely has *both* generic mechanisms (general §3):
- (1) `BOARD_ITEM` is broadly `INSPECTABLE` (`board_item.cpp:427+`) → `PROPERTY_MANAGER`
  serializes most fields **write-once** with field-level merge.
- (2) `PCB_IO_KICAD_SEXPR::Format(const BOARD_ITEM*)` (`pcb_io_kicad_sexpr.h:351`, per-type
  `format(PCB_TRACK*/PAD*/ZONE*/…)`) gives a **free opaque blob** for any type reflection
  misses.

So: reflection-decompose the hot types you want field-level merge on (track width/endpoints,
position), blob everything else — **no hand-written per-type serializers**.

## apply — go through BOARD_COMMIT; recompute is MANDATORY
```cpp
BOARD_COMMIT commit( toolMgr );
// add:    item = deserialize(...); commit.Add(item)
// modify: item = board->GetItem(uuid); commit.Modify(item); …edit…
// remove: commit.Remove(board->GetItem(uuid))
commit.Push( "collab" );   // updates connectivity + recomputes ratsnest
```
`Push` updates `CONNECTIVITY_DATA` per item and calls `RecalculateRatsnest`. **Never** use
direct `BOARD::Add/Remove` for remote ops unless you also manually
`GetConnectivity()->Add/Update/Remove` + `RecalculateRatsnest()` + `OnRatsnestChanged()` —
the commit path does it correctly, so use it.

## Apply gotchas (enumerated)
- **Connectivity + ratsnest are mandatory** after any structural/net change — skipping
  corrupts net feedback. This is the single biggest difference from pl_editor.
- **Zones** are expensive — outline edits need a re-fill (not automatic).
- **Footprints** own child items (pads, fp text); their uuids live in `m_itemByIdCache` too —
  a footprint add/remove cascades (handled by `BOARD::Add`, `board.cpp:1239`).
- **Vias/teardrops/DRC** — drill changes ripple; `BOARD_COMMIT::Push` handles within commit.
- **Groups** — membership tracked by the commit.
- **Net settings** (`OnBoardNetSettingsChanged`) are board-global, not per-item — model as a
  separate doc field, not an items entry.

## Scale — the defining constraint
Real boards: 5k–20k items typical, 50k–500k for large designs. Implications:
- **Snapshot-on-change is non-viable** (per-commit serialization → MB; remote parse blocks UI).
  Granular deltas via the listener are **essential** here — never a whole-document approach.
- **Initial sync is itself heavy:** seeding a fresh `Y.Doc` from a 100k-item board must be a
  **batched, own-phase** operation (chunked transactions, possibly off the first paint), not a
  single emit. Flag as its own sub-task within the pcbnew commit.
- Prefer **opaque-blob** items to keep per-item payloads small and avoid a huge field-mapping
  surface across pcbnew's many types.