---
name: wiki-component
description: >-
  How to publish a "component" page to the Adom Wiki — a single chip, a molecule,
  or a PCB that isn't a molecule. `component` is a real wiki page TYPE (peer to
  app/skill) with NATIVE rendering: set a `component` block in page.json + push the
  CAD files and the wiki auto-renders interactive symbol + footprint + 3D viewers,
  a downloads grid, and a datasheet section. The chip page is the rich case: a
  mini-datasheet-plus-CAD-hub built from Adom's own tools (chip-fetcher, ds2sf,
  adom-symbol/footprint/lbr, step2glb, chipfit, chip-thumbnailer), with PROVENANCE
  on every datapoint and an Open-in toolbar. Read before publishing any
  chip/molecule/board. Trigger words: publish a component, component page, chip
  page, publish a chip, component readme, symbol footprint 3d page, datasheet page,
  molecule page, pcb component, tape and reel, pin 1 orientation, pick and place,
  kicad altium orcad fusion library, parametric specs, mouser digikey price stock,
  provenance, prove the data, datasheet page citation, embed symbol footprint
  viewer, open chip in tool.
---

Parent skill: **adom-wiki-skillpack**

# Publishing a component (chip / molecule / PCB)

`component` is a first-class **wiki page type** (alongside `app` and `skill` — see
**wiki-api**). Structurally a component is usually the **Page** archetype; chip
families use the **Family** archetype (see **wiki-repo-styles**), e.g. an `stm32f4`
anchor with `stm32f405` / `stm32f407` children.

Three kinds, by what they are:

1. **Chip** — a single part / IC (MCU, MOSFET, sensor, passive, connector). The
   rich case; most of this skill.
2. **Molecule** — a reusable sub-circuit / breakout published via `adom-molecule`.
3. **PCB (non-molecule)** — a finished board not meant to be reused as a part.

> **Read [adom-ui-design](https://wiki.adom.inc/john/adom-ui-design) BEFORE you build
> the page UI.** A component page is a real Adom interface and must obey it:
> canonical color tokens, brand fonts (Familjen Grotesk / Satoshi / JetBrains Mono,
> never the system stack), **monochrome line-icon SVGs — NO emoji, anywhere**, **no
> em-dashes or en-dashes**, a 44px three-zone header, body-appended tooltips, 8/12/999
> radii. Lint with `adom-ui-linter`. This was learned the hard way: an emoji- and
> em-dash-ridden page reads as AI slop and engineers stop trusting it.

---

# How the page actually renders: two layers

There are two very different rendering paths. Know which you're using.

## Layer A — the wiki's NATIVE component rendering (the working path today)

This is what you get for free, and it is good. Set a **`component` block in
page.json** and push the CAD files; the wiki auto-renders:

- an **interactive 3D viewer** (Babylon) from the `.glb`,
- an **interactive schematic-symbol viewer** (SymView) from the `.kicad_sym`,
- an **interactive footprint viewer** (FpView, with layer toggles incl. solder
  blobs) from the `.kicad_mod`,
- a **datasheet** section, and a **CAD downloads grid** (typed icons per file).

These are served at `https://wiki.adom.inc/viewer/{3d,symbol,footprint}/component/<slug>`
and are genuinely interactive (drag, zoom, layer toggle). They embed anywhere
(the wiki dropped `frame-ancestors`), so you can `<iframe>` them into a custom page.

The `component` block:

```json
"component": {
  "mpn": "nRF52840-CKAA",            // REQUIRED — POST /pages rejects a component without it
  "manufacturer": "Nordic Semiconductor",
  "package": "aQFN-73 (7x7x0.85 mm, 0.5 mm pitch)",
  "pin_count": 73,
  "category": "Microcontroller",
  "subcategory": "Wireless MCU / Bluetooth LE SoC",
  "body_size": { "x_mm": 7.0, "y_mm": 7.0, "z_mm": 0.85, "pitch_mm": 0.5 },
  "parts": { "symbol": "x.kicad_sym", "footprint": "x.kicad_mod",
             "model_3d": "x.glb", "step": "x.step", "datasheet": "docs/x.pdf" },
  "distributor_links": { "mouser": "...", "digikey": "...", "jlcpcb": "..." }
}
```

Parts auto-detect by extension if you omit `parts` (first `.kicad_sym`/`.kicad_mod`/
`.glb`/`.step`/`.pdf` in the tree), but **declare them** so the right datasheet PDF
wins over the RoHS cert, etc.

## Layer B — the README / custom HTML (heavily constrained)

The Overview README is rendered through `marked` + **`sanitize-html` with a strict
allowlist**. It **strips `<style>`, `<script>`, `<details>`, `<iframe>`, and even
`style=` attributes.** So you **cannot** build a tabbed/accordion/toolbar custom
layout in the README — inline styles vanish, accordions collapse to nothing, scripts
never run. (Confirmed live: a hand-built toolbar rendered as plain text links.)
README HTML that survives: `h1-6, p, a, ul/ol/li, blockquote, pre, code, em, strong,
table/tr/th/td, span, div, img`, with `class` on a few. Use the README for prose +
images + tables that complement the native viewers — not for a custom app shell.

**To get the full custom layout** (tabs, accordions, panels, the Open-in toolbar,
provenance lightbox) you have two options:
1. **Ship a `readme.html`** (LIVE — verified 2026-07-15): put a self-contained
   `readme.html` in the publish tree and `pkg publish`. The wiki renders it as the
   page body in a sandboxed iframe (`sandbox="allow-scripts allow-downloads"`,
   served unsanitized from `/readme/<owner>/<type>/<slug>?variant=public`) —
   inline CSS AND `<script>` both work, so the full tabbed/accordion/toolbar/
   lightbox layout is the real page now. It fully shadows README.md on the page.
   No `allow-same-origin`: self-contain everything (base64-inline fonts/images or
   absolute `/blob/...` URLs; no wiki API calls from inside). See **wiki-readme**.
2. **Prototype it as a standalone page in the container** (for iterating before
   publishing): one self-contained HTML file, **base64-inline the fonts + images**,
   inline CSS + JS, embed the live `/viewer/...` iframes, then serve it with
   `python3 -m http.server <port>` and hand the user the proxy URL
   `https://<slug>.adom.cloud/proxy/<port>/`. The same file, once it looks right,
   drops in as `readme.html` unchanged.

   > **A reference data-driven generator ships with this skill** at
   > `component-page-generator/gen_chip.py` (+ `template.html`). Point it at a
   > chip-fetcher dir and it emits a compliant standalone page: it reads
   > `info.json` / `stock.json` / `*-symbol.extracted.json` /
   > `*-footprint.extracted.json` / `*-extraction.provenance.json` + the rendered
   > SVGs, **detects the component class** (MCU / MOSFET / op-amp / sensor / power /
   > passive) to pick the right Specs block, builds the **real Provenance** tab
   > (per-pin + per-dimension datasheet page citations, cropping the cited pages
   > with `pdftoppm`/ImageMagick into a click-to-enlarge lightbox), and enforces the
   > Adom-UI rules (tokens, brand fonts, monochrome icons, NO emoji / em-dashes,
   > 44px header, tooltips). Validated across 6 classes; adapt the absolute paths.
   > Use it as the blueprint for either a standalone preview or the shipped
   > custom-HTML `readme.html` page.

---

# The CHIP component page

A mini datasheet + CAD hub + sourcing desk. Canonical sections (tabs in the custom
layout; stacked panels + native viewers on the live page):

> **Overview · Symbol · Footprint · 3D · Pin map · Specifications · Sourcing ·
> Tape & reel · Manufacturer & resources · Variants · Related · Provenance · Open in**

## 0. Source every artifact from Adom's tools, and USE them (don't fake it)

Never ship a static screenshot where a live viewer belongs. Generate real artifacts
and **embed the live interactive viewers**.

| Artifact / capability | Tool | Command → output (verified) |
|---|---|---|
| STEP + KiCad sym/mod + Altium IntLib + Fusion .lbr + datasheet + stock | **chip-fetcher** | `chip-fetcher fetch <MPN>` → `library/<MPN>/` (⚠ may save a *product brief*, not the full datasheet — verify it has the pinout, see Provenance) |
| Pin descriptions + symbol/footprint extraction + **per-pin datasheet page citations** | **ds2sf** | `ds2sf extract <chip-dir> --pdf <full-datasheet.pdf>` → `*-symbol.extracted.json`, `*-footprint.extracted.json`, `*-provenance.json`. **Refuses a PDF with no pinout** (won't fabricate). |
| Interactive **SymView** | **adom-symbol** (service :8781 / wiki) | wiki route `/viewer/symbol/component/<slug>` (embed). CLI `adom-symbol render --file x.kicad_sym --out x.svg` for a static SVG. |
| Interactive **FpView** (layer toggles + solder blobs) | **adom-footprint** (service :8782 / wiki) | wiki route `/viewer/footprint/component/<slug>` (embed). CLI `render` for SVG. |
| Fusion/EAGLE **.lbr** generated on the fly | **adom-lbr** | `adom-lbr generate --sym x.kicad_sym -o x.lbr` (works standalone; lints) |
| STEP → web **GLB** | **step2glb** | `step2glb convert x.step -o x.glb` |
| pin-1 + seat-plane validation + pin-1-baked GLB | **adom-chipfit** | `adom-chipfit check --footprint x.kicad_mod --glb x.glb` |
| symbol/footprint SVGs + 3D iso PNGs + manifest | **chip-thumbnailer** | `chip-thumbnailer once <MPN>` |

### Generate the embeddable viewers FROM the apps — use `embed`

adom-symbol and adom-footprint ship a first-class **`embed`** command that exports a
**self-contained, interactive HTML package** (pan/zoom + pin info panel; pads +
courtyard + layer toggles) built for an iframe — no server, no external assets, one
portable `.html`. **This is the canonical way to get the symbol/footprint viewers.**

```bash
adom-symbol   embed --file <mpn>.kicad_sym --out symview.html   # interactive SymView
adom-footprint embed --file <mpn>.kicad_mod --out fpview.html   # interactive FpView
```

Then embed each same-origin: `<iframe src="symview.html">` / `<iframe src="fpview.html">`.
The footprint export includes a layers panel with an **"InstaPCB paste dots" toggle**
(the 300µm jetted-paste positions, off by default) plus Copper / Assembly /
Courtyard / Paste apertures — so the solder-paste view is built in. Pin 1 is marked.

> Use the freshly **built** binaries (`<app>/target/release/adom-symbol|adom-footprint`)
> — a stale `~/.local/bin` copy may predate `embed` (or be a stub). `embed` renders
> via service-kicad, which must be reachable.

Two fallbacks, only if `embed` isn't available:
- the JS generators `generateBrandedViewer(...)` / `generateFootprintViewer(...)`
  (pass a pre-rendered `svgContent` to skip service-kicad), or
- once the page is **published**, the wiki hosts the same viewer at
  `/viewer/{symbol,footprint,3d}/component/<slug>?embed=1` (the wiki runs these
  generators server-side) — fine for the live page.

The shipped `component-page-generator/` does this: `mkviewers.sh` runs
`adom-symbol embed` / `adom-footprint embed`; the page embeds `symview.html` /
`fpview.html`.

## 1. What goes in each section

- **Overview** — MPN, manufacturer, one-liner, lifecycle badge (Active / NRND /
  Obsolete), package, pin count, voltage, datasheet link. (Hero shows in the page
  header — never re-embed it, **wiki-hero**.)
- **Symbol** — embed the live SymView iframe. (Static SVG fallback below it.)
- **Footprint** — embed the live FpView iframe; the solder/paste layer is a real
  toggle there. Note pin-1 = square pad, top-left. Leaded vs lead-free + bridging
  feedback via Discussions.
- **3D** — embed the live Babylon viewer; show the chipfit verdict (pin-1, seat Δz).
- **Pin map** — pin list with descriptions (ds2sf per-pin, grouped POWER/IO/…) and
  symbol-pin ↔ pad map. **Cite the datasheet page per pin** (Provenance).
- **Specifications** — **class-aware** (render the block that fits): MCU (core,
  clock, flash, RAM, GPIO, peripherals, V, temp); MOSFET (channel, Vds, Id, Rds(on),
  Vgs(th), Qg, Ciss, Pd); passive (value, tol, V, dielectric/temp-co, EIA size);
  op-amp (channels, GBW, slew, Vos, Ib, V±).
- **Sourcing** — price-break table, stock, lifecycle, RoHS, MSL (1–6 + floor life),
  Mouser + DigiKey buy links. Date every snapshot.
- **Tape & reel** — packaging (CT/T&R/tube/tray), reel qty, MSL, EIA-481 pin-1
  quadrant. Authoritative orientation = the manufacturer's tape-and-reel drawing.
- **Manufacturer & resources** — the mfr product page + **every** supplemental doc
  (datasheet, errata, PCN, RoHS cert, app notes, reference designs, SDK, dev kits,
  CAD source). Don't just link the datasheet.
- **Variants** — symbol/footprint/3D/package variants, each with downloads.
- **Related** — molecules using this chip, family siblings (Family anchor), alternates.
- **CAD downloads** — per-tool: KiCad (`.kicad_sym`+`.kicad_mod`+STEP+WRL), Fusion/
  EAGLE (`.lbr`), Altium (`.IntLib`), OrCAD (`.olb`+`.dra`/`.psm`/`.pad`), universal
  STEP + GLB. (The native grid renders this automatically.)
- **Provenance** — see its own section below. Mandatory.
- **Open in** — see its own section below.

## 2. Pin-1 / pick-and-place orientation

The footprint pin-1, the 3D pin-1 corner, and the placement **zero orientation**
must agree or the part lands rotated 90/180°. IPC-7351: ICs pin-1 **top-left**;
polarized two-terminal pin-1 (+) **left**; positive rotation CCW. ⚠ IEC 61188-7 uses
**bottom-left** — call out which a library follows. Markers: SOIC dot/notch, QFP/QFN
chamfer, BGA A1 corner, footprint pin-1 = square pad. Polarity gotcha: SMD tantalum
stripe = +, SMD aluminum electrolytic stripe = −. Validate with **adom-chipfit**.

## 3. Tape & reel

Packaging (CT/T&R/tube/tray + custom Digi-Reel/MouseReel), reel qty, EIA-481 carrier
(pocket referenced to sprocket holes, 4.0 mm feed pitch; pin-1 conventionally
Quadrant 1), MSL 1→6. Defer to the mfr tape-and-reel drawing for orientation.

---

# Provenance — prove every datapoint

**Engineers don't trust AI yet, so prove the backing data.** Every datapoint on the
page must trace to a source, and the strongest claims must show the evidence.

- **Cite a source for everything**: identity/specs → datasheet page; price/stock →
  distributor + date; CAD → the source (e.g. Ultra Librarian deeplink); 3D → the
  STEP + the converter + the STEP sha256 (`features.json`); RoHS → the certificate.
- **For datasheet-derived data (ds2sf): show the PDF page number AND a cropped image
  of that page.** Render page crops with `pdftoppm`/ImageMagick/`gs` (all present in
  the container); `ds2sf` emits `*-provenance.json` with per-pin page citations, and
  `datasheet-parser` produces cropped diagram PNGs.
- **A Provenance section/tab is mandatory**: a table (Data → Source → Reference
  (page/version/date) → Evidence), with the cropped source-page images shown inline
  and click-to-enlarge (a simple lightbox), plus inline "Source: …" citations on the
  Specs and Pin-map sections.
- **ds2sf refusing a brief is the feature, not a bug.** It will not invent pin data
  from a PDF that lacks the pinout. ⚠ **chip-fetcher sometimes saves a 2-page product
  brief instead of the full Product Specification** (seen on nRF52840-CKAA — both
  "datasheet" files were the same 2-page brief). Always verify the datasheet has the
  pinout before relying on it; if ds2sf refuses, fetch the full datasheet (mfr site /
  desktop browser) and re-run.

---

# The "Open in…" toolbar

Let the user *act* on the part, not just read it.

| Target | Reached by | One-click from a web page today? |
|---|---|---|
| 3D / Symbol / Footprint viewer | wiki `/viewer/{3d,symbol,footprint}/component/<slug>` | ✅ links / embeds, any context |
| Download CAD | `/blob/component/<slug>/<file>` | ✅ `<a download>` |
| Buy (Mouser / DigiKey) | `distributor_links` | ✅ |
| adom-symbol / footprint / lbr / step / chipfit / chipsmith / chip-fetcher / service-kicad | container CLI / services | ❌ no page→container bridge → **paste-to-Claude prompt** |
| KiCad / Fusion on desktop | `adom-desktop kicad_open_* / fusion_open_*` | ❌ no page→desktop bridge → **paste-to-Claude prompt** |
| Altium / OrCAD on desktop | — | ❌ no adom-desktop verb → download + open manually |
| Send library → Downloads + open folder | `adom-desktop send_files` + reveal | ❌ paste-to-Claude prompt |
| "Component Ocean" | — | not an Adom tool (a distributor); no open verb |

Why prompts: a wiki page can't run JS (README sanitized) and there's no page→desktop
bridge. So the live `/viewer/...` routes are real link/embed buttons; everything else
copies a one-line Claude prompt (works in any context). Context (HD webview / native
/ pup) can't be detected at runtime yet, so the prompt is context-agnostic.

---

# Molecule pages

Published via **adom-molecule** (GLB + KiCad PCB + schematic + symbol/footprint JSON,
SKU `owner/name/version`). Show: 3D GLB, schematic, the pin map (`adom-pin-mapping` →
`MoleculePinMapping.md`), BOM, and Related (the chips it's built from, two-way links).

# PCB (non-molecule) pages

A finished board, not reused as a part. Overview + 3D/photos + schematic/board
downloads + BOM + assembly notes. Page archetype.

---

# Publishing

1. `page.json` with the **`component` block** (`mpn` required) + hero + tags +
   `discovery_triggers`.
2. Create the page: `POST /api/v1/pages` with `type:"component"` **and `component.mpn`
   in the body** (it's rejected otherwise).
3. Push all files (text plain, binaries base64, `User-Agent` header) in **<4MB
   batches** — GLB/STEP/PDF are big and a too-large batch returns **413**. Push a
   **complete `page.json` LAST** so the hero/title stay linked (**wiki-hero**,
   **wiki-publish-safely**). (No `adompkg publish` tarball is needed for a component.)
4. **Verify in pup**, and check `/viewer/...` routes return interactive content.
5. For chip families, apply the Family naming/title rules (**wiki-family**).

## 📋 Platform TODO (for Colby / adom-desktop) — fold these into build asks

- ~~**Custom-HTML page mode**~~ **SHIPPED** (verified 2026-07-15): a repo
  `readme.html` renders as the page body in a sandboxed iframe
  (`allow-scripts allow-downloads`, unsanitized) — see **wiki-readme**. Remaining
  gap: no `allow-same-origin`, so embedded viewers can't fetch the wiki API from
  inside the readme (next item).
- **Editable embedded viewers**: let the embedded SymView/FpView tweak + regenerate
  in place (needs same-origin fetch in the page sandbox).
- **page→desktop bridge** (`window.adomDesktop` / `adom://` / local endpoint) +
  **runtime context detection** + **adom-desktop endpoint & installed-app
  enumeration** + a **reveal-folder** verb + **Altium/OrCAD open verbs**, to make the
  Open-in toolbar one-click.
- **Live price/stock** widgets (vs dated `stock.json`); **leaded/lead-free paste
  switch + bridging heatmap** in FpView; **auto "molecules using this chip" backlink
  index**; a **per-class spec schema** the page fills structurally.
- **chip-fetcher**: don't save a product brief as the datasheet — verify the PDF has
  the pinout (so ds2sf can extract).

> ⏳ This skill records the live constraints as of its writing (README.md is
> sanitized, but `readme.html` custom pages SHIPPED — verified 2026-07-15; still
> no page→desktop bridge). Re-verify and update when the bridge ships.