--- name: adom-hardware-component-publish description: > The one-stop-shop for publishing a HARDWARE COMPONENT (or molecule/board) to the Adom Wiki — everything you need in one place. Covers the whole lifecycle: what a component page is made of, the clone→edit→preview→push loop and its hard rules, how to make a great hero image (Hero Component Studio: a lit part on a procedural PCB or a molecule on a shadow ground, 16:10, overlay-safe, datasheet-backed), the animated 3D composite model, the interactive 3D viewer, ct thumbnails (symbol + footprint + 3D icons), the datasheet-accuracy audit, and every wiki push/pull gotcha we have hit. Use whenever someone wants to publish, update, or improve a component/molecule/board page on wiki.adom.inc. Trigger words: publish component, publish hardware, publish to wiki, component page, molecule page, board page, wiki page, hero image, component thumbnail, card art, 3d composite, insertion.glb, interactive viewer, ct thumbnails, datasheet audit, wiki push, wiki clone, page hero, set hero, land pattern, footprint viewer. PRIVATE — Adom only. metadata: type: reference --- # Publishing a Hardware Component to the Adom Wiki **The single place to look when you want to put a hardware component on the wiki and have it look right.** "Component" here means any physical thing that gets a wiki page: a discrete part (resistor, MLCC, LED, inductor, connector, IC), a **molecule** (an assembled sub-board), or a full **board**. The recipe is the same shape for all of them; the differences are called out inline. > **Living document.** When you hit a new wiki issue or find a better recipe, add it to the right > section, bump the version, and open a PR against `adom/adom-hardware-component-publish`. Never > re-solve a problem that's already written here. > **Private / Adom-only.** Published under the `adom` org, visibility private. > **First decide which kind of page you're making** — a single **COMPONENT** (Path A) or a full > **BOARD / MOLECULE** (Path B). The required contents differ (see "Two kinds of page" below). On a > component page, the 3D viewer + cited datasheet content **stand in for the datasheet**: every fact > is datasheet-accurate and **traceable to a specific figure/table/page** (cite your sources). A board > page is the author's presentation of how their board works, not a cited datasheet. --- ## The lifecycle at a glance ``` 1. Gather inputs datasheet (electrical + packing/tape&reel), CAD (STEP/GLB), KiCad sym/fp 2. Build the assets 3D composite (datasheet-accurate) · ct thumbnails · timeline viewer 3. Make the hero Hero Component Studio → 16:10, overlay-safe, datasheet-backed (§3) 4. Assemble ONE page README.html = datasheet content + full-page timeline viewer, self-sizing (§5.0) 5. Preview RENDERED preview via the readme-frame harness through the container proxy 6. Snapshot + approve save the pre-change files; get an explicit human go-ahead 7. Push clone fresh → README.html + viewer-config.json + hero → rm retired files 8. Verify live commit at HEAD · blobs 200 · /readme 200 · hero set · hard-refresh (cache) ``` Everything a page needs is below, section by section. If you only touch one thing (e.g. "make the hero better"), jump to that section — but the **hard rules (§0)** and **push gotchas (§8)** apply to every push. --- ## Two kinds of page — pick your path FIRST A **single component** (a part: an LED, resistor, MLCC, IC, connector) and a **full board or molecule** (an assembled sub-board) are different deliverables with different required contents. Decide which you're publishing, build the required contents for that path, then use the shared mechanics (hero §3, composite §4, viewer §5, wiki push §2/§8) to assemble and ship it. **Both paths end as the one seamless full-page README (§5.0).** ### Path A — a COMPONENT page (a single part) · required contents 1. **Datasheet information — the whole point, and it must be COMPLETELY datasheet-accurate.** This is the former "characterization page", merged into the wiki page. **The datasheet PDF itself MUST be stored in the page repo** (Adom standard — every component page has a datasheet); it's the source of truth and every citation links to it. **Every single data point must be traceable to a specific place in that datasheet** — cite the revision + page/table/figure, linked into the stored PDF (e.g. "VF 2.1 V typ · 2.6 V max — [IN-S42AT V1.1 p.3]", "2θ½ 130° — [p.3 fig.4]"). See §7/§7a for the citation format, §7b for the "datasheet changes ⇒ citations change" rule AND the mandatory **datasheet revision+date line near the top of the page**, and §7c for how to read a datasheet. Charts are *redrawn to the datasheet curve*, not invented. If a value isn't in the datasheet, it does not go on the page — flag the gap, never estimate. (See [[feedback_never-fabricate-data]], [[feedback_characterization-pages-are-datasheets]].) 2. **Interactive viewer** (§5), with the modes the part warrants: - **Static** — the seated part with the standard Layers. If the component *does* something — a visual behaviour like emitting light or actuating — show it **cleanly and datasheet-backed** (e.g. an LED's glow colour from its λD, its FOV cone from 2θ½). - **Timeline** — a visual replacement for the *visually-explainable parts of the datasheet* (power-on, optical cone, reflow, tape & reel). Everything shown is datasheet-backed; the captions cite the datasheet (§5a datasheet-vs-measured rule). - **Pick & Place** — a **datasheet-accurate carrier tape & reel**, with either the standard drop-in **ghost nozzle** or a specific nozzle the user chooses. 3. **Solder joints** — either the default fillets, or (preferably) **the placement/shape the user specifies** (where and how the solder sits on the pads). 4. **The geometry carries the facts** — the viewer shows the real **pad size**, the **chip model**, and the correct **orientation** (cathode/pin-1), all datasheet-accurate. 5. **Symbol + footprint** — the schematic symbol and PCB footprint (inline `ct/` SVGs, since interactive symview/fpview iframes are sandbox-blocked, §8k). ### Path B — a BOARD / MOLECULE page · required contents 1. **Interactive viewer** (§5) — this is the centrepiece; a board/molecule is not a datasheet part, so it has **no characterization / tape&reel / pick-and-place** requirement. A board viewer has exactly **TWO modes** (an earlier draft split assembly/walkthrough/operation into three tabs — that was redundant; drop-in and explanation are ONE story, and an "operation" reel took the camera away from the user): - **Assembly — the groupings drop in together, and the caption explains each as it lands.** The board starts bare with an overview caption; then each functional grouping's parts **fall in as one beat** (all members of the power grouping together, then all the connectors, …) in the author's order, while a data-card caption (eyebrow / head / rows / note) explains what that grouping is and does. Camera frames each grouping — but **any drag/wheel yields it to the user for 5 s, then it eases back** (the exact convention of the single-component Timeline viewer; the viewer must never fight for control). If the board uses **molecules**, each drops in already populated and seats like a single component. Scrubber ticks mark group starts. - **Static — the seated board, and the camera is entirely the user's.** No timeline, no scripted moves, no caption sequence — hover tooltips, the section legend (click to isolate), section labels, and any **author-specified visual functions** as *toggles* (e.g. a "Power" button lighting the rail LEDs). Behaviours here are the author's call and must be labelled author-specified (§7B); nothing is invented. For rich animated behaviour (blink patterns, a scanning row, a display) use the LED-lighting / animated-emission method (`adom-basic-part-page-upgrade`, Caleb's playbook) — still as a user-triggered toggle, never a camera-stealing reel. - **ASK THE AUTHOR — this is their presentation, so collect (don't invent) exactly:** 1. **The groupings** — which parts belong together. Default straight from the schematic sheets (§5c.4 derives sheet membership automatically — e.g. the MCU sub-sheet is a grouping, Power is a grouping); the author refines via `blocks.json` (split a sheet, merge two, name them). 2. **How each grouping should be explained** — the caption content per group (what it is, the key parts/values, why it's there), plus the drop **order**. 3. **Static behaviours** — should anything light up or move? Which LEDs, what states, what the toggle is called. Explicitly ask; "none" is a fine answer. - **Choreography convention (the config, `adom-board-viewer-config/0.2`):** the **grouping is the unit of authorship**. `blocks[]` (id, label, colour, one-liner) + `modes.assembly{ order[], timing{fall_s, stagger_s, dwell_s, rest_s, drop_height_mm}, intro{caption}, captions{: {eyebrow, head, rows, note, d?}} }` + `modes.static{ blurb, functions{...author-specified toggles} }`. Per-group `d` overrides the default dwell. The author's whole input is one small JSON file; the geometry does the rest. Worked example: the feeder-reader mock's `viewer-config.json`; runnable viewer: `scripts/board-viewer-template.html`. - **PACE — the first cut is always too slow.** A caption you have already read is dead air, and a viewer that feels slow gets abandoned before the last grouping lands. Author the timeline **1.5× faster than feels right on the first pass** — i.e. divide every *duration* by 1.5 (`drop_height_mm` is a distance, leave it). Use these as the **starting defaults**, not the numbers you slow down from: | Key | Value | Why | |---|---|---| | `fall_s` | **0.47** | the drop reads as a snap, not a float | | `stagger_s` | **0.027** | members of one grouping land as a beat | | `dwell_s` | **6.3** | enough to read eyebrow + head + rows, not to re-read | | `rest_s` | **4.0** | the closing look at the finished board | | per-group `d` | **4** for short captions (intro, mounting) | 2–3 rows do not need a full dwell | Tune a group UP only when its caption genuinely has more rows to read — never tune the whole reel down. (Verified on `adom/feeder-reader`: the original 0.7 / 0.04 / 9.5 / 6.0 pass read as sluggish; these values are that reel at 1.5×.) 2. **Provenance per §7B** — every table generated from the design files, DNP honoured, and every claim labelled generated / author-asserted / illustrative. 3. **Schematic + layout come from the two Adom viewer apps — do NOT hand-roll them.** Earlier drafts of this skill invented their own board maps (`scripts/kicad_board_map.py`) and leaned on the wiki's plain `render/sheet-*.svg` images. Both are superseded: there are real, maintained apps that render the **EDA's own output** and add live interactivity, so a board page embeds those instead of static pictures. | Need | App | Command | |---|---|---| | Schematic (`.kicad_sch`, every sheet) | [`adom/adom-schematic`](https://wiki.adom.inc/adom/adom-schematic) | `adom-schematic embed --file .kicad_sch --out sch-.html` | | PCB layout (`.kicad_pcb`) | [`adom/adom-2dboard`](https://wiki.adom.inc/adom/adom-2dboard) | `adom-2dboard embed --file .kicad_pcb --out layout.html` | - `embed` emits **one self-contained interactive HTML file** (SVG + metadata + viewer JS inlined, no external assets) — which is exactly what the wiki's sandboxed readme frame can host, and it keeps working on a **private** page with no cap plumbing at all (see §8k-vii). - What you get over a flat image: schematic — hover a symbol for KiCad-style highlight plus live MPN / stock / price / LCSC / wiki link, click to pin the card, and a component list linked to the drawing. Layout — click any pad/via/trace/zone to highlight the **whole net** while the rest dims, hover for pad number/size/shape/side/net + live part data, independent layer toggles and Top/Bottom mirroring. - **Pass `--sheet-dir` or you silently publish a one-sheet schematic.** `embed --file root.kicad_sch` alone reports `0 child sheets bundled` **even when the sub-sheets sit right beside the root** — hierarchical children are only pre-rendered when you point at their directory: `adom-schematic embed --file .kicad_sch --sheet-dir --out sch.html` → `3 child sheets bundled`, and the embed's SHEET selector switches between them instantly with no reload. One embed covers the whole hierarchy, so you do NOT need one iframe per sheet. (On `adom/feeder-reader` the root holds 25 of 138 parts — without the flag the MCU, Power and CS sheets were simply absent and the page looked complete.) - **Get the sources from the design machine**, not from whatever copy is lying around the container: pull with `adom-desktop pull_file '{"filePaths":[...],"saveTo":""}'` and **sha256-compare the root sheet + board against what the page already publishes** before using them. Stale local checkouts of the same project are common and differ silently (a Jul-10 copy had 18 root symbols against the published 45). - The layout embed needs only the `.kicad_pcb`; side panels auto-hide below 620 px, so give each frame real height. - Install: `adom-wiki pkg install adom/adom-schematic adom/adom-2dboard`. Both need `KICAD_SERVICE_API` (service-kicad) for the authentic render; the layout viewer self-renders if it can't reach it (and looks less like KiCad, so prefer having it up). 4. **`page.json` mapping for a board** (the schema is component-shaped; use this convention): `component.mpn` = the KiCad project name, `component.manufacturer` = the org (e.g. `Adom`), `component.category` = `board`, `component.model_3d_path` = the baked board GLB. Mandatory files: the **board GLB**, the **KiCad source** (or a pointer to where it lives), and the two **viewer embeds** from item 3. 5. **NO DATASHEET on a board or molecule page.** A board is not a catalogue part — it has no manufacturer datasheet, and a page that shows one is asserting a document that does not exist. Concretely: **ship no PDF in the repo.** The wiki auto-scans any PDF into a "Datasheet" section and *there is no manifest opt-out* (molecule-publish, page-polish rules), so a stray `.pdf` silently grows a datasheet section nobody authored. The schematic and layout viewers of item 3 ARE the board's documentation — they replace both the datasheet and the "Symbol & Footprint" slot (a board has no schematic symbol either). If a board genuinely needs long-form docs, put them on a dedicated docs page or attach them as **release assets**, never as a PDF in the page repo. (Path A component pages are the opposite — there the datasheet is mandatory and every number cites it, §7.) 6. **Any additional information the user wants to add** — a board page is theirs to compose. Everything else — publishing mechanics, the **hero image and grid thumbnail** (§3), the wiki clone→push loop (§2), and every gotcha (§8) — is **shared** by both paths and applies to each. --- ## The gold-standard page — what "done" looks like The reference build is **`aravk/in-s42atr`** (Inolux red 0402 LED) — the **COMPONENT** (Path A) gold standard. A **board/molecule** (Path B) shares the same *shape* (one seamless full-page README, the viewer as the hero, the ADOM hero image + grid thumbnail) but its content is the viewer-as-presentation plus whatever the author adds — not a cited datasheet. Aim a component page at this shape: - **ONE seamless full-page.** The `README.html` IS the page. It is a single sandboxed iframe (`#readme-frame`) that grows to fit its content (§8k-0b) — no boxed 600px widget, no "click through to the datasheet". A visitor lands on the full-page 3D viewer and scrolls down through the entire datasheet in one continuous document. - **The interactive 3D viewer is the hero of the page**, full-bleed and viewport-tall at the top (§5). Below it flows **everything a datasheet has**: spec cards, electrical table, operating conditions, package & land-pattern dims, the emission/IV/derating/brightness charts (redrawn to the datasheet), a live resistor calculator, environmental/handling, the symbol + footprint, pricing, and document links. The 3D viewer + these facts **replace the PDF for everyday reference**. - **There is no separate characterization page.** The old `.html` char blob is **merged into the README** and deleted — one canonical page, not two. (On in-s42atr the merge pulled the char content in and removed `IN-S42ATR.html`.) - **Everything datasheet-backed**, tooltips split datasheet-vs-measured (§5), hero rendered in Hero Component Studio at 16:10 (§3). The rest of this skill is how to build each piece. If you're making a new page, this is the target; §5.0 is the assembly recipe for the single-page README. --- ## 0. Hard rules (never skip — this is why pages don't get clobbered) 1. **Always pull fresh before editing.** Someone else may have pushed since you last looked. `adom-wiki repo clone / --dir ` immediately before you edit. 2. **Snapshot before push.** Copy the pre-change files to a timestamped dir and **print the path**, so revert is a one-liner. (`adom-wiki repo clone` is NOT a git repo — see 8j; copy files by hand.) 3. **Preview before push, then get explicit human approval.** A *rendered* preview (pup/Hydrogen screenshot, or the served HTML), **NOT** `curl 200`. No preview → no push. Ever. 4. **Only push the files you changed** (`--files a b c`), and **only the page you're editing.** Never touch another page. 5. **Everything must trace to the datasheet.** Every electrical number, every hero glow colour, every tape/reel dimension, every chart curve. Cite the datasheet page. If it's a guess, remove it or flag it explicitly — never invent. Characterization pages ARE datasheets (§7). 6. **Real changelog required** (`WIKI_STRICT_AUTH` is on): `-m "<≥2 words, ≥10 chars, specific>"`. Placeholders (`update`, `release v1`) are 400-rejected. --- ## 1. Anatomy of a component page A component page is a small file repo at `/`. Typical contents: | File | What it is | Required? | |---|---|---| | `page.json` | metadata: `slug`, `type`, `description`, `component{mpn,manufacturer,category,model_3d_path}`, `hero{type,path}`, `dependencies` | **yes** | | `README.html` | **the whole page** — the merged single-page document (viewer + full datasheet content), served in the self-sizing readme-frame (§5.0, 8k-0b). `.html` wins over `.md`; `.md` strips iframes. Keep a short `README.md` in the repo as source-of-record | **yes** | | `screenshots/hero.png` | the **hero image** — one 16:10 image used for BOTH the page header and the grid card (§3) | **yes** | | `-datasheet.pdf` | the **datasheet** — MANDATORY on every component page (§7); source of truth + citation target | **yes (component)** | | `viewer-config.json` | the timeline viewer's captions / tooltips / chapters config (§5) — push it alongside the README so the embedded viewer's text loads | interactive pages | | `.glb` | the canonical 3D model the viewer loads **by name** (see 8b) | for anything 3D | | `.insertion.glb` | the animated composite (part drops onto its footprint) — what the timeline viewer loads | composite pages | | `-viewer.html` | the **interactive 3D viewer** source (the timeline viewer, §5). Its content is inlined as `srcdoc` into the README; keep the file as the editable source | interactive pages | | `adom-3d-viewer.min.js` | Colby's shipped viewer bundle (the viewer fetch-injects it by absolute URL) | interactive pages | | `.kicad_sym` / `.kicad_mod` | KiCad symbol / footprint source | if it has EDA | | `ct/` | thumbnail bundle: 3D icons + **symbol SVG + footprint SVG** (used inline in the page, since interactive symview/fpview iframes are sandbox-blocked) + manifest (§6) | standard | > **Note:** the standalone `.html` characterization blob and the `-symview/-fpview.html` > iframe viewers are **retired** in the gold-standard build — the char content merges into the README > and the symbol/footprint become the static `ct/` SVGs (interactive `src=` iframes are blocked in the > readme sandbox, §8k). Old pages may still have them; new pages should not. **`type`** in `page.json` is `component` for discrete parts and molecules alike (the BME690 and USB3-Ethernet molecules both use `type: component`, category `Sensor` / `board`). There isn't a separate "molecule" page type — a molecule is a component whose model happens to be a whole board. **Served asset URL (memorise):** `https://wiki.adom.inc/blob/component//`. This is what the page HTML and the 3D viewer fetch. It's also the URL your browser loads the hero from — not the `/api/pages/...` path (see 8m). --- ## 2. The wiki CLI + publish lifecycle One CLI over the whole git-wiki API: `adom-wiki`. Every call takes `--json`. > **Prefer the runnable module** `scripts/publish_wiki_page.py` — stdlib-only wrappers around every > step (`ensure_author`, `find_page_owner`, `clone_page`, `snapshot`, `push_files`, `set_hero`, > `verify_asset`, `publish_new_package`) with the gotchas baked in. Read it top-to-bottom to learn > the flow, or import it to drive a publish. The raw commands below are the ground truth. ```bash # identity (once per container) — WIKI_STRICT_AUTH needs a real author + changelog adom-wiki whoami adom-wiki set-author # SSO your Adom identity into the wiki # find the page and its OWNER (owner is not always `adom` — see 8a) adom-wiki discover search -q "" --limit 5 adom-wiki page stats / # 404 => not under that owner # --- EXISTING page: clone → edit → preview → snapshot → approve → push --- adom-wiki repo clone / --dir # ...edit locally, RENDERED preview, snapshot, get approval... adom-wiki repo push / --files -m "" adom-wiki repo log / --limit 5 # confirm ONLY your commit landed # --- HERO (page card image) — takes a REPO-RELATIVE path, not a local file (see §3 / 8n) --- adom-wiki repo push / --files screenshots/hero.png -m "hero: " adom-wiki page hero / --image screenshots/hero.png # NOTE: no --changelog on this verb # --- NEW page: scaffold + publish --- adom-wiki pkg init --type component adom-wiki pkg publish --org adom --private -m "" # from the pkg dir ``` **Verify a pushed asset authenticated** (private pages 403 unauthenticated — see 8h): ```bash curl -s -H "Authorization: Bearer $(cat ~/.config/adom-wiki/token)" \ "https://wiki.adom.inc/blob/component//" -o /tmp/x -w "%{http_code} %{size_download}\n" ``` The authoritative confirmation a push landed is `adom-wiki repo log` (your hash at HEAD); then cross-check the served **byte count** equals what you pushed (a stable URL means HTTP 200 alone doesn't prove the *new* bytes are live). --- ## 3. THE HERO IMAGE — do this well, it's the first thing anyone sees Every browsable object gets **exactly one hero**: a single picture that lets a human identify the thing in a fraction of a second, without reading the title. If you can't tell ten of these apart at a glance in the grid, the design is broken. The hero is used in **two** places from **one** file — the page header AND the landing-grid card. There is **no separate thumbnail asset** (`page.hero_thumbnail` is always null; the grid renders the hero file directly). ### 3.1 Use Hero Component Studio `~/project/hero-component-studio` (the `hero-component-studio` skill). A small web app + CLI that frames a component in a studio scene, lets you tune every variable live, and renders headlessly at full quality. **Every function has a CLI verb** — you never have to click. ```bash hero-component-studio serve --detach # starts on 8872 hero-component-studio show # opens the Hydrogen webview tab hero-component-studio mode component|molecule # pick the scene hero-component-studio set part # or: set molecule hero-component-studio list # every setting: value, range, what it does hero-component-studio save # save a preset; load to reuse hero-component-studio render --width 1344 --height 1200 # writes out/-hero.png ``` **Two scene modes:** - **component** — one part standing on a **generated circuit board** (routed traces, flat under-mask vias, scattered scenery chips, a keep-out around the hero). This is the LED/passive path. - **molecule** — a **finished assembly on its own**, no invented circuitry (a molecule IS a real board), sitting on an invisible shadow-catching ground. Getting your own model in (validated + de-Draco'd on ingest): ```bash hero-component-studio add-part ./.glb hero-component-studio add-molecule ./.glb # wiki molecule: adom-wiki repo clone, point at its render/board.glb ``` ### 3.2 The rules that make a hero good (each cost real iteration) - **16:10 aspect, rendered natively — never scaled to fit.** The wiki grid slot is 16:10; a 1200×630 image **letterboxes** with bars top and bottom on the card. Render at **1920×1200** (canonical) — or the image panel at **1344×1200** if you composite a text block over the left 30% (see 3.3). If you must reshape an existing render, **crop, don't stretch**: `background-size:cover` scales uniformly and crops the overflow; scaling one axis distorts the part. The canonical hero-image spec (`adom/adom-wiki-hero-image`) actually wants **1600×1000 @ deviceScaleFactor 2 = 3200×2000** for retina crispness — render there if you want it razor sharp. - **Shoot from the ISO view.** The hero camera is the classic isometric three-quarter: `camAzimuth` ≈ ±45–55°, `camElevation` ≈ 30° — the angle that shows the subject's top AND two sides at once, the way every CAD tool's "ISO" button frames a part. Straight-down reads like a board map, edge-on hides the body; the iso view is the standard for both component and board heroes (the feeder-reader hero is azimuth −52° / elevation 29°). - **Overlay-safe framing.** The finished hero draws a title block over the lower band. Framing on the part's *centre* puts half of it under that band, clipping the pads. `autoClearOverlay` (on by default) **pans** the camera (never rotates — your angle survives) until the lowest projected corner of **body + pads** clears `overlayCutoff` (default 0.345 = bottom 34.5%). Hit the **Band** button to draw the reserved zone in the viewport. - **Centre on the VISUAL mass, not the bounding box.** A board with pins hanging below reads "high" even when its bbox is perfectly centred. Measure the **luminance centroid** and correct with `panX` / `panY` (in units of the subject radius; right-click-drag in the viewport writes them). On the BME690 the bbox was centred to 0.6% but the visual centroid was off by ~3.7% vertically. - **The hero renders at TRUE scale; the scenery is what you size.** In component mode the hero part is always 1:1 — the camera fits to it, so it dominates through framing (`fov` / `margin`), not by being scaled up. **`chipScale` sizes the scenery chips as real packages** (by body length: 0.6 = 0201, 1.0 = 0402, 1.6 = 0603, 2.0 = 0805) — so pick scenery that reads right next to your hero's package (a 0402 hero looks natural amid 0201–0603 scenery). `keepout` is the clear radius around the hero. - **Every scenery component has a trace in AND out** (enforced in the generator). A chip with no routing reads as a part that does nothing; the router guarantees both terminals of every scenery chip connect outward to two different nodes. Vias and the hero's own pads join nearby nets too. - **Everything datasheet-backed** (§0.5). An emitter's glow colour comes from its dominant wavelength λD (RGB → white; every other LED → its own λD colour), the FOV cone from 2θ½. Never reuse another part's numbers. - **Mouse ⇄ sliders.** Orbit (left-drag) writes `camAzimuth/camElevation`, pan (right-drag) writes `panX/panY`, zoom (wheel) writes `margin` — so a view you find by dragging survives Save and renders identically. Save a look as a **preset** (`save ` / `load `); the browser clipboard is blocked in the webview, so there's no "copy", only presets. - **The render is NOT a screenshot.** It renders at 2× with SSAA + 4× MSAA and downsamples — that's what removes jagged edges. (`EffectComposer` silently discards the renderer's `antialias:true`, so the composer needs its own multisampled target — already handled in the app.) - **Preview aids never render.** The light guide (`showLightHelper`) and the overlay band are tuning overlays; the renderer forces them off, so they never bake into the image. ### 3.3 The compositor (title block + branding) The bare render is a part on a dark background. To get the ADOM-branded card (wordmark, title, MPN + manufacturer, badge on a dark gradient), composite it through the Hero Studio compositor (`hero-studio-local`, the local Node compositor in the led-hero scratchpad): - Add a record to `hero-studio-local/data/components.json`: `name` (big title), `spec` (subtitle = MPN), `mfr` (trails the MPN), `badge` (**`ADOM BASIC PART`** for parts, **`ADOM MOLECULE`** for molecules), `family`, `owner`, `slug`. **All copy comes from the wiki `page.json` + README — never invent a title.** - The compositor places the render panel in the right 70%, fades its left edge under the gradient, and draws the text block over the left 30%. Type is all in `cqw`, so it holds at 2000×1250. - **Gotcha — `displayEntry()` drops unknown fields.** The compositor rebuilds a fresh object from the record; a new field (e.g. `badge`) won't reach the overlay until you thread it through `displayEntry()`. Symptom: your change to the data does nothing. - The compositor **caches `components.json` at startup** — restart its Node server after editing data. - Output at **1920×1200**; it verifies the bottom-third text column stays text-free. ### 3.4 Setting the hero on the page `page hero --image` takes a **repo-relative path**, not a local file. So: clone fresh → copy the PNG to `screenshots/hero.png` → `repo push --files screenshots/hero.png` → `page hero --image screenshots/hero.png`. The wiki **warns** if the aspect isn't 16:10 ("crops left/right on the grid"). **Caching:** the served hero carries `cache-control: max-age=86400`. After a re-push the origin is correct immediately (confirm with a cache-busted `curl ...?cb=$(date +%s)`), but a browser holds the old image for 24 h — a **hard refresh** (Ctrl/Cmd+Shift+R) is the fix; closing/reopening a tab is not. The page loads the hero from `/blob/component//screenshots/hero.png`, so verify *that* URL, not the `/api/pages/...` one. ### 3.5 Sharing a hero for review To send a render to a teammate for feedback, `adom-google` DMs it as **you** (better than the `adom-gchat` webhook, which only posts to shared spaces). Caveats learned the hard way: a human account **cannot send a Chat card** (bot-only) and **`driveDataRef` attachments silently drop** — so upload the PNG to Drive (`api --upload-file`, `--content-type image/png`), share it anyone-with-link reader, and DM the **Drive link** as text (durable, unlike the container proxy URL which dies when the container sleeps). --- ## 4. The 3D model / animated composite (`.glb` / `.insertion.glb`) The centrepiece of a characterization page: the component drops onto its own footprint with a smooth insert animation and a Layers toggle. See `scripts/build_composite_led.py` (LED, 3 materials + light) and `scripts/build_composite_cap.py` (cap, 2 materials) for full worked builders. Key facts: - **All metres, Z-up, 1:1 scale** (matches the wiki viewer + `machinecontactmedium`). - **Node names the viewer recognises as Layers:** `fr4_board`, `pad_top`, `silk`, `solder_top`, plus `` (the part). Board/pads/solder/silk are built from the part's `.kicad_mod`. - **Insert animation** = translation channel on the `` node, LINEAR, keyframes `[0, 1.2, 3.0, 4.2, 6.0]` s, Z `[0, 0, LIFT, LIFT, 0]`. **LIFT = 3 × the component's measured height** (`z.max − z.min` from geometry) — auto-scales per part. - **Layers menu = FIXED vocabulary.** The shared viewer only turns a node into a toggle if its name is in a hardcoded map (`fr4_board, pad_top, pad_bottom, solder_top, solder_bottom, paste_top, paste_bottom, silk, silk_top, silk_bottom, barrel, pin1_marker`). Custom nodes (`LED_lit`, a FOV cone) and the part body do **not** appear — no `extras` escape hatch (only `extras.tooltip` is read). Custom toggles need the viewer owner (**Colby**) to add a key. Design GLBs to **degrade gracefully** when the toggle doesn't exist (e.g. the LED renders lit). - **Real lights:** embed via `KHR_lights_punctual`. At mm scale, point-light intensity must be tiny (~4e-5) — inverse-square blows the board white at 0.3. Parent the light to `` so it rides the animation. Red light on a green FR4 board reads warm/orange (green absorbs red — physics). - **Emissive brightness:** boost with `KHR_materials_emissive_strength`. - **Side embossing (part number/value):** cadquery boolean-cut the text into the STEP; auto-fit the font to the measured width×height taper so the whole string fits off the terminations. - **Colouring a re-tessellated (embossed) mesh:** transfer material per-triangle by **densified nearest-neighbour** from the original colour GLB (a plane split only works for a clean 2-material boundary; 3-material parts need densified NN or you get zigzag artifacts). - **Translucent overlays** (FOV cone, keep-out): build in world coords as their own top-level node, double-sided `BLEND` material, added to the insert animation's translation channel. Drive dimensions from a datasheet spec. Not in the fixed Layers vocabulary → renders always-on until Colby adds a toggle. - **Height correction:** apply a node `scale=[1,1,h_target/h_model]` to `` (and any glow node) to match a datasheet height — avoids re-plumbing the emboss/NN pipeline. --- ## 5. The interactive 3D viewer — the model somewhat *replaces* the datasheet The single most valuable thing on a **single-component** page. The idea: a person should be able to learn the part from the 3D viewer without opening the PDF. That only works if **every datasheet-accurate fact is baked into the model and its tooltips** — the body dims, the pad/land pattern, the optical cone, the tape & reel, the electricals — each either measured live off the geometry or shown as a datasheet-cited row. If a number isn't in the model or a tooltip, it isn't in the viewer, so put it there (§4 builds the geometry; the tooltips below carry the rest). > **Both paths use Timeline, but they mean different things** (this supersedes an earlier note that > said Timeline was component-only): > - **Component (Path A) Timeline** = the *part's* visual datasheet story — power on → optical cone → > lift → solder reflow → tape & reel. Every beat is datasheet-backed. This is what the `viewer-config.json` > captions/tooltips below describe. > - **Board/molecule (Path B) Timeline** = the *author's presentation of the board* — a walkthrough of > its functional sections the user defines (power: ESD → fuse → LDO; user input: buttons; …). It's a > narrative, not a fixed lifecycle. It also has **no tape&reel / pick-and-place** (a board isn't reeled). > Its Static mode is components (and pre-populated molecules) dropping into place, choreographed by the > author. ### 🛑 START HERE — never write a viewer from scratch The viewer is **not** re-invented per page. Every page's viewer is the SAME base plus a config file. Rebuilding it freehand is how pages drift, and it is the single easiest way to waste a day. **The base is Colby's shipped bundle** — `adom-3d-viewer.min.js`, exposing `window.Adom3DViewer` (the same engine as the wiki's own native viewer). It is used **UNMODIFIED**: all our behaviour is host-page code layered on top, so it stays purely additive and can be offered back upstream. Do not fork it, patch it, or vendor a different three/Babylon build. **Copy the template that matches your path, then edit only its config:** | Path | Template to copy | Live page to compare against | |---|---|---| | A — component | `adom-basic-part-page-upgrade` → `assets/viewer-template.html` | `aravk/in-s42atr` | | B — board/molecule | this skill → `scripts/board-viewer-template.html` | `adom/feeder-reader` | **The layer cake — know which layer you are allowed to touch:** | Layer | What it is | Do you edit it? | |---|---|---| | `adom-3d-viewer.min.js` | Colby's engine — scene, camera, picking, GLB load | **NEVER** | | `*-viewer.html` template | our host page: modes, captions, legend, tooltips, timeline | rarely — fix bugs upstream in the template, not per page | | `viewer-config.json` | **the per-page authoring surface** — blocks, order, timings, captions, static toggles | **YES — this is the file you write** | | `.glb` + `board-index.json` | the geometry and its refdes→section index (§5c) | generated, never hand-edited | So the actual per-page job is: bake the GLB (§5c) → write `viewer-config.json` (Path B item 1) → drop in the template unchanged. If you find yourself writing scene/camera/animation code, stop — that belongs in the template, and if the template can't express it, extend the template once so every page gets it. **Why this matters beyond tidiness:** the template already encodes the load-sequence fixes (§5b), the sandbox/storage shims, the cap plumbing for private pages (§8k-vii), the camera-yield convention, and Colby's exact ground/sky. A from-scratch viewer silently loses all of it and the failures look like "the viewer is broken on the wiki" rather than "we re-derived it wrong". The full worked reference is the `adom-basic-part-page-upgrade` skill (`assets/viewer-template.html`). ### 5.0 Assembling the single-page README (the gold-standard build) The whole page is one `README.html` = the datasheet content with the viewer as a full-page `srcdoc` at the top. To build (or rebuild) it: 1. **Start from the characterization content** (the spec cards / tables / charts / calculator). If a standalone `.html` exists, its body is the base; then **delete `.html`** (one canonical page). If not, author the content directly. 2. **Embed the timeline viewer as a full-bleed `srcdoc`** at the top (§5a below). Full-width (break out of the text column), viewport-tall. 3. **Convert every nested `src=` iframe** — they are sandbox-blocked (§8k): the 3D viewer → the `srcdoc` viewer; symbol/footprint viewers → inline **`ct/` SVG ``s**; any molecule/board viewer → a link. 4. **Absolute-URL everything the srcdoc fetches** — the bundle, the GLB, `viewer-config.json`, and any `` — to `https://wiki.adom.inc/blob/component//…` (relative 404s in the readme sandbox). 5. **Fix stale URLs** — old pages often reference a dead host (`wiki-ufypy5dpx93o.adom.cloud/static/ libraries/…`); rewrite to the current blob host. 6. **Add the self-sizing script** (§8k-0b): size the viewer to `screen.availHeight − ~200`, then `parent.postMessage({type:"readme-height", height: document.documentElement.scrollHeight}, "*")` on load/resize so the readme-frame grows to fit — no box-in-box scrollbar. 7. **Push together:** `README.html` + `viewer-config.json` + `screenshots/hero.png`. Then `repo rm` the retired `.html` / `-symview.html` / `-fpview.html`. Preview by mirroring the wiki's readme-frame + resize handler locally and loading through the container proxy (headless puppeteer in the container reaches `127.0.0.1`; pup can't). Verify the frame grows and the viewer renders before pushing. ### 5a. Timeline mode + the config-driven text (viewer-cli) > **The Timeline viewer is the PRIMARY, canonical viewer — and it is under active development.** > Not the old Static/PnP-only one. It lives in a work dir (`/home/adom/project/in-s42atr-work/…` for > in-s42atr). **Pull it FRESH before every embed/push** — the copy on the wiki goes stale the moment > it's edited. Never re-embed a cached copy. Regeneration is mechanical (steps 4→7 above); the viewer > already ships the sandbox storage shim + bundle fetch-inject, so no other adaptation is needed. The viewer has three modes via a segmented control: **Timeline** (a ~56 s narrated explainer reel — chapters: the part → powered on → viewing angle → lift off → solder → tape & reel → rest), **Static** (inspect the seated part), and **Pick & Place** (a nozzle lifts the part from a datasheet-exact carrier tape and seats it). Every scripted camera move, caption, and tooltip is **data**, not code: - **`viewer-config.json`** is the editable source of truth for the Timeline **captions** (the data-point cards + `t0/t1` timing = when each appears), the **hover tooltips**, the **chapter marks**, and the swappable **tape/nozzle** GLBs. The viewer merges it over built-in defaults, so it works standalone but every bit of text is authorable. - **`./viewer-cli`** authors it (adom-cli conventions — `OK:/ERROR:/Hint:` + `--json`): `caption list|set|add|rm`, `tooltip list|set|add|rm|enable|disable`, `chapter list|set`, `assets set-tape|set-nozzle`, `verify` (headless load + config⇄viewer check), `doctor`. It validates timing (`t0` it): blob `.js` is `application/octet-stream + nosniff` → refused as a script src. `fetch().text()` → inline `