# Symbol/Footprint Source Contract (chip-fetcher ⇄ adom-symbol / adom-footprint)

How chip-fetcher's library folder is laid out, how multiple symbol/footprint
**sources** coexist, and the CLI/HTTP contract the apps use to render and switch
between them. This is the cross-app "wiring" for the provenance carat + the
adom-symbol layout studio.

## Library folder layout (`library/<mpn>/`)

| File | Produced by | Role |
|---|---|---|
| `<mpn>.kicad_sym` | vendor (snapeda / ultralibrarian / manufacturer …) | **canonical** symbol (the current thumbnail source) |
| `<mpn>.<method>.kicad_sym` | import (variant keeping) | a **per-source variant** kept so multiple methods coexist |
| `<mpn>-symbol.extracted.json` | **ds2sf** | datasheet-extracted pins + logical **groups** + per-pin **descriptions** |
| `<mpn>.kicad_mod` / `<mpn>.<method>.kicad_mod` | vendor / import | canonical + per-source footprint variants |
| `<mpn>-footprint.extracted.json` | **ds2sf** | datasheet-extracted pads + body dims |
| `<mpn>-symbol.svg` | chip-thumbnailer | canonical symbol thumbnail |
| `<mpn>-symbol.<method>.svg` | chip-fetcher (via `adom-symbol render` / `render-ds2sf`) | **per-source** symbol thumbnail (carat) |
| `<mpn>-footprint.svg` / `<mpn>-footprint.<method>.svg` | chip-thumbnailer / chip-fetcher | footprint thumbnails (canonical + per-source) |
| `<mpn>-3d-iso.png` | chip-thumbnailer (OCCT) | iso render — used as the centered 3D overlay in adom-symbol |
| `info.json` → `source_of_record` | chip-fetcher | per-extension provenance fallback (`kicad_sym`, `kicad_mod` → source slug) |
| `<mpn>-file-provenance.json` | import | per-file `discovery_source` / `content_origin` |

**`<method>` slug**: lowercase-alphanumeric of the content origin — `snapeda`,
`ultralibrarian`, `manufacturer`, `mouser`, `digikey`, `arrow`, `lcsc`,
`componentsearch`. `ds2sf` is reserved for the datasheet extraction.

## Provenance carat data (chip-fetcher `/api/library`)

Each chip exposes `symbol_sources` / `footprint_sources`:
```json
[{ "method": "snapeda", "label": "SnapEDA", "current": true, "thumb": true },
 { "method": "ds2sf", "label": "ds2sf · datasheet", "current": false, "thumb": true }]
```
- `current` — the variant currently rendered as the canonical thumbnail.
- `thumb` — a per-source thumbnail SVG exists (the carat shows it).
- Thumbnails served at `GET /thumb/<mpn>/symbol.<method>` (and `footprint.<method>`).

## Cross-app HTTP contract

**chip-fetcher → adom-symbol/footprint** (on tile/carat click → `POST /api/open`):
```
POST /api/open  { "mpn": "<mpn>", "kind": "symbol|footprint", "source": "<method>|auto|ds2sf|manufacturer" }
```
chip-fetcher resolves the chip dir and pushes it to the app:
```
POST /load  { "dir": "<abs path to library/<mpn>>", "mpn": "<mpn>", "source": "<initial source>" }
```
adom-symbol then **discovers** the sources in that folder (ds2sf extraction,
canonical `.kicad_sym`, and every `<mpn>.<method>.kicad_sym` variant) and renders
the requested/default one.

**Switching source/layout live** (the studio toolbar):
```
POST /relayout { "source": "auto|ds2sf|manufacturer|<method>",
                 "pinLayout": "left-right|all-sides", "grouped": true|false,
                 "refPos": "top|center|top-left|bottom-left", "show3d": true|false }
```
- `auto` / `ds2sf` → **generated** by our generator from the ds2sf extraction
  (logical groups, GPIO sub-split P0/P1/P2, balanced sides). `grouped`,
  `pinLayout`, `refPos` apply here.
- `manufacturer` / `<method>` → the vendor `.kicad_sym` rendered **verbatim**.

`GET /state` reflects `sources[]`, `source`, layout opts, pins (with ds2sf
descriptions merged), `isoPng`, etc.

## Render CLIs (chip-fetcher shells these to make per-source thumbnails)

```
adom-symbol    render        --file <.kicad_sym>             --out <svg>   # any symbol → themed SVG
adom-symbol    render-ds2sf  --file <-symbol.extracted.json> --out <svg> [--layout left-right|all-sides] [--sym <.kicad_sym>]
adom-footprint render        --file <.kicad_mod>             --out <svg>
adom-footprint render-ds2sf  --file <-footprint.extracted.json> --out <svg>
```
chip-fetcher's thumbnail pass (`chip-fetcher thumbnails --mpn <mpn> --force`)
calls these automatically for the ds2sf extraction and for every discovered
`<mpn>.<method>.kicad_sym/.kicad_mod` variant.

## Adding a new source

1. Import writes `<mpn>.<method>.kicad_sym` (variant kept alongside canonical).
2. Next thumbnail pass renders `<mpn>-symbol.<method>.svg`.
3. `symbol_sources` lists it → carat shows it with its thumbnail.
4. adom-symbol's studio Source segment offers it (rendered verbatim).

No code changes needed for a new vendor — only the `<method>` → label map in
`inventory.rs::source_label` (chip-fetcher) and `SRC_LABEL` (adom-symbol app.html)
for a pretty name; unknown slugs fall back to the slug itself.