---
name: adom-layout-viewer
description: "Use when the user asks to view, open, preview, or inspect a PCB layout or .kicad_pcb board; to highlight a net or trace; to see which pads are on a net; to look up a part on the board (stock, price, MPN, wiki page); or to embed an interactive PCB view inside another app or web page. Also trigger for questions like 'show me the board', 'what net is this pad on', 'make the PCB preview clickable', or 'replace the board image with something interactive'."
---

# adom-layout-viewer

Interactive PCB layout viewer for `.kicad_pcb`. The visual is the EDA's OWN
render (authentic silkscreen, trace widths, theme colours); an invisible overlay
parsed from the board file adds net/trace/pad interactivity on top of it.

## Architecture

```
adom-layout-viewer (single Rust binary, no Node, no local KiCad)
  |
  +-- visual base      per-layer SVG from service-kicad
  |                    POST /kicad/pcb/export/svg?layers=<L>   (KICAD_SERVICE_API)
  |                    one <g class="adom-layer-*"> per layer, KiCad theme colours
  |
  +-- interaction      .kicad_pcb parsed in Rust -> pads / traces / vias / zones
  |   overlay          carrying data-net, data-ref, data-pad, data-side
  |                    drawn INVISIBLY in the same board-mm coordinate system
  |                    (no Y-flip, no offset) so the two align exactly
  |
  +-- enrichment       GET /enrich?mpn=&lcsc=  (non-blocking: returns
                       {"pending":true} and warms in a background thread)
                         adom-parts-search search <mpn>          -> stock, price
                         adom-wiki discover search --json        -> wiki, popularity
```

If service-kicad is unreachable it falls back to a self-render, so the app still
works — it just looks less like KiCad.

## Quick start

```bash
# self-contained interactive HTML for embedding in another app
adom-layout-viewer embed --file board.kicad_pcb --out board.html

# composed interactive SVG (+ board.meta.json)
adom-layout-viewer render --file board.kicad_pcb --out board.svg --meta

# live app
adom-layout-viewer serve --file board.kicad_pcb --port 8790
```

## Commands

| Command | Description |
|---|---|
| `embed --file F [--out O]` | One self-contained interactive HTML file (no external assets) |
| `render --file F --out O [--meta]` | Composed interactive SVG, optional `<out>.meta.json` |
| `serve [--file F] [--port P]` | Live app server (default :8790) |

## Server routes (serve)

| Route | Purpose |
|---|---|
| `GET /state` | Current SVG + metadata (frontend poller) |
| `POST /load` | Push a new `.kicad_pcb` |
| `GET /enrich?mpn=&lcsc=` | Stock / price / wiki for a part (async, cached) |
| `POST /eval`, `GET /console` | AI-drivable UI channel |
| `POST /shutdown` | Stop the server |

## Interactions

- **Click** a pad, via, trace or zone fill -> the whole net highlights in its own
  copper colour, everything else dims. The net list stays in sync.
- **Hover** a pad or via -> pad number, size, shape, side, net + live stock,
  price, wiki page, popularity for the parent part.
- **Layers** toggle independently; Top/Bottom mirrors the board and brings that
  side's stack to the front.

## Embedding in another app

`embed` inlines SVG + metadata + viewer JS into one file, so an iframe is enough:

```html
<iframe src="/board-view/<slug>/pcb" style="border:0;width:100%;height:100%"></iframe>
```

An embed has no server, so its `fetch("enrich")` is RELATIVE — it resolves
against whoever serves the page. A host app can answer that route to give the
embedded card live stock/price (adom-nucleus does exactly this). If
nothing answers, the card degrades to identity only.

The side panels auto-hide below 620px width, so a small embedded pane shows just
the board and a fullscreened one shows the full chrome.

## Environment

| Variable | Purpose |
|---|---|
| `KICAD_SERVICE_API` | service-kicad base URL (default: the shared container) |

## Notes

- KiCad today. The overlay architecture is EDA-agnostic by design; Altium and
  Fusion exports are the planned next step.
- Sibling app: **adom-schematic-viewer** (same idea for `.kicad_sch`).