Evan — Adom Molecule LED Nameplate

@@ -0,0 +1,161 @@+# adom-tsci: what broke and what the export skill should say++Found while publishing `adom/evan-led-nameplate` on 2026-08-20. Four issues,+roughly in order of how badly they bite.++## 1. `adom-tsci export-wiki` cannot upload any more (blocker)++```+$ adom-tsci export-wiki . --slug evan-led-nameplate --page-type molecules+OK: staged bundle at /tmp/adom-tsci-export-evan-led-nameplate+OK: tarball: /tmp/evan-led-nameplate-tsci-viewer.tar.gz (4.7 MB)+error: 'asset' is not an adom-wiki command+Error: adom-wiki upload failed+```++The CLI shells out to `adom-wiki asset upload --asset-type tsci-viewer`.+`adom-wiki` has no `asset` pillar today. Its file-bearing verbs are now+`repo push`, `release upload`, and `page attach`.++Everything up to the upload still works, and `--no-upload` produces a correct+bundle, so the staging half of the tool is fine. Only the last step is dead.++**Fix:** re-point the upload at `repo push` (see #2 for why that is the right+target anyway), or restore an `asset` shim in `adom-wiki`.++## 2. The documented publish shape no longer matches the live one++`export-wiki.md` says the wiki extracts the `tsci-viewer` asset to+`/static/<page-type-plural>/<slug>/tsci-viewer/<label-slug>/` and+**"auto-renders an iframe section on the page."**++That is not what the current pages do. `adom/alex-nameplate` (2026-08-07, the+newest one) has no auto-rendered section at all. It carries:++- `viewer/` as ordinary repo files, pushed with `repo push`+- a hand-written **`README.html`** that embeds the viewer itself++and the wiki renders `README.html` in preference to `README.md`. The guide+never mentions `README.html`, so following the guide gets you a page with no+viewer on it.++**Fix:** the guide should describe the README.html contract, and `export-wiki`+should scaffold one. The working pattern, verified end to end:++```html+<!-- click-to-load poster, so the page does not pull 15 MB on every visit -->+<div class="viewer" id="viewer">+  <button class="poster" id="viewer-load" type="button">+    <img src="https://wiki.adom.inc/<owner>/<slug>/render/docs/hero.png" alt="...">+    <span class="play"><b>Load interactive 3D viewer</b><i>Orbit, inspect, measure…</i></span>+  </button>+</div>+<script>+  document.getElementById('viewer-load').addEventListener('click', function () {+    var f = document.createElement('iframe');+    f.src = 'https://wiki.adom.inc/<owner>/<slug>/render/viewer/index.html';+    f.setAttribute('allow', 'fullscreen');+    var host = document.getElementById('viewer');+    host.innerHTML = ''; host.appendChild(f);+  });+</script>+```++Two non-obvious things the guide must call out, because both are silent+failures:++- **Static assets resolve through `https://wiki.adom.inc/<owner>/<slug>/render/<path>`.**+  Relative and root-relative paths do not work: the README is rendered in a+  null-origin iframe.+- **The README iframe does not know its own height** and clips everything below+  the viewer unless the page posts its height to the parent:+  `parent.postMessage({type:'readme-height', height: wrap.offsetHeight + 24}, '*')`,+  re-posted on load, resize, every `img`/`iframe` load, and from a+  `ResizeObserver`. Without it the BOM and everything under the viewer is+  unreachable. Alex's README.html has the reference implementation.++Also worth stating in the guide: **do not use `@font-face` in README.html.**+adom.inc's font files fail CORS from a null origin on every load.++## 3. The viewer bundle IS self-contained — this should be an asserted invariant++I checked this because a published page has to outlive the container that built+it. It holds today, but nothing enforces it.++Evidence: served the staged bundle from a throwaway static server and logged+every request the viewer made while rendering the board and running the+walkthrough:++```+5 GET /viewer/circuit.json          3 GET /viewer/js/tscircuit-alphabet.js+4 GET /viewer/js/adom-3d-viewer.min.js   3 GET /viewer/js/environmentSpecular.env+4 GET /viewer/index.html            3 GET /viewer/adom.css+3 GET /viewer/walkthrough.json      3 GET /viewer/3d.glb?t=1+1 GET /viewer/schematic.svg         1 GET /viewer/favicon.svg+```++Zero off-bundle requests. The only `localhost` strings left in the bundle are a+code comment in `index.html` and two dead Babylon internals (a WebXR HTTPS+check, the Inspector's default reflector host). Neither fires.++Two follow-ups:++- **`GET /viewer/runframe/` 404s** on every load. That is the "tsci live" tab,+  which only exists against a running dev server. On a published page it is a+  permanently dead tab plus a 404 in the console. Either drop the tab from the+  static export or grey it out.+- The about-popover still links `https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-tsci`+  rather than `https://wiki.adom.inc/adom/adom-tsci`.++**Suggested:** add a bundle self-containment test to `export-wiki` — grep the+staged bundle for absolute hosts and fail the export on anything that is not+same-bundle-relative.++## 4. `<Molecule>` makes `adom-tsci lint` unsatisfiable++With 141 components, tscircuit's schematic auto-layout emits one horizontal+strip that is unreadable at any zoom. `lint` passes it (nothing overlaps), so+the check does not catch the actual problem.++Giving every part explicit `schX`/`schY` fixes it — but note the all-or-nothing+rule, which cost me a build: **placing SOME parts disables auto-layout for the+rest and stacks them at the origin.** That deserves a line in the skill.++The unfixable part: `MP1`–`MP4` come from `<Molecule>`, and++```js+moleculeResult.machinePins.map((pt) =>+  jsx(MachinePin, { type: ..., name: pt.name, pcbX: pt.x, pcbY: pt.y }, pt.name))+```++passes no `schX`/`schY` and exposes no prop to supply them. `MachinePinProps`+in `@tsci/adom-inc.library` accepts them; `@tsci/adom-inc.molecule` just does+not plumb them through. So the four pins stack at the origin, and `lint` fails+the board with:++```+ERROR: schematic: 4 component(s) overlap — MP1 ⨯ MP2 (100% overlap) …+Hint: Parts emitted by <Molecule> (machine pins) default to the schematic+      origin — place them at the four corners of the schematic+```++The hint tells you to do something the API cannot do. `alex-nameplate` dodges+this by not using `<Molecule>` at all: it hand-rolls `<board>` plus explicitly+placed `MachinePin`s.++**Fix:** add a `machinePinSchPositions` prop (or auto-place the pins at the+schematic bbox corners) in `@tsci/adom-inc.molecule`. Until then, either lint+should special-case Molecule-emitted pins, or the skill should tell people to+hand-roll `<board>` when they care about the schematic.++## Smaller notes++- `--texture-resolution N` on `export-wiki` silently falls back to the 1024 px+  GLB with `Hint: no rebake-glb.mjs in cache; run 'adom-tsci start' once`. The+  4096 rebakes were sitting in `~/.cache/adom-tsci/rebakes/` the whole time;+  `export-wiki` just does not look there. Cache keys are content hashes, so+  matching one to the current board means loading each GLB and comparing+  geometry (`scripts/glb-inspect.mjs` in this project does that).+- `walkthrough-gen` auto-regenerates on every `export-wiki` because the stored+  walkthrough references `D0.pin1 ↔ R0.pin2`, a refdes form that does not exist+  in `circuit.json`. Harmless, but it prints a scary line every run.