Adom TSCI - Tscircuit Board Viewer

@@ -0,0 +1,241 @@+# adom-tsci/export-wiki — publishing a tscircuit molecule to the Adom Wiki++**Read this before running `adom-tsci export-wiki` on any project.**+The CLI is deliberately opinionated: it ships the interactive 3D+viewer, the source bundle, the plan.md, AND a comprehensive body+markdown to the wiki page in one shot. Skipping any of those pieces+makes the page useless to a future viewer (human or AI) — the goal+is "another agent can pick up exactly where this one left off" with+nothing missing.++## What the CLI does, in order++```+adom-tsci export-wiki [<project>] --slug <wiki-slug> \+    --page-type molecules \+    --label "Live 3D viewer" \+    [--rebuild] [--texture-resolution N] [--no-upload]+```++1. **Confirms `dist/lib/index/circuit.json` exists.** Skip-rebuild is+   the default — `bunx tsci build` can take 10 minutes on dense+   boards. Pass `--rebuild` to force.++   **Fallback-dist search** (1.3.91+): if the in-place dist is missing,+   the CLI looks for an existing dist at known parallel locations+   before erroring out. Order: `~/project/adom-tsci-projects/<basename>/dist`,+   `~/project/adom-tsci/examples/<basename>/dist`,+   `~/project/tscircuit-projects/<basename>/dist`. Picks the freshest+   by `circuit.json` mtime. Many canonical molecules live in two+   places (the example-library copy and the local scratch-build+   copy); only one has a fresh dist at any given moment, and there's+   no reason to spend 10 minutes rebuilding when the other copy is+   already there.++   **The reflex when a build seems missing:** `ls+   ~/project/adom-tsci-projects/<name>/dist/lib/index/circuit.json`+   FIRST. Only rebuild if neither copy has a fresh dist. The CLI does+   this automatically now, but the same rule applies to any AI helper+   debugging "why doesn't this project have a dist?" — search before+   rebuilding.+2. **Resolves the GLB.** Default = `dist/lib/index/3d.glb` (1024-px+   texture). Pass `--texture-resolution N` to rebake at higher res+   (4096 typical for 100–200 mm boards; first bake ~75 s, cache hit+   ~190 ms).+3. **Stages the viewer bundle** at `/tmp/adom-tsci-export-<slug>/`:+   - `index.html` — `shell.html` rewritten for static hosting (fetch+     monkeypatch, walkthrough autoplay, all `glb`-style URLs+     remapped to relative paths).+   - `js/adom-3d-viewer.min.js`, `js/tscircuit-alphabet.js`,+     `js/environmentSpecular.env`, `adom.css`, `favicon.svg` —+     embedded into the binary, copied out at staging time.+   - `3d.glb`, `circuit.json`, `walkthrough.json`, `pcb.svg`,+     `schematic.svg` — the project's build artifacts.+4. **Tarballs the viewer bundle** as+   `<slug>-tsci-viewer.tar.gz`. Uploads via `adom-wiki asset upload+   --asset-type tsci-viewer`. The wiki extracts to+   `/static/<page-type-plural>/<slug>/tsci-viewer/<label-slug>/` and+   auto-renders an iframe section on the page.+5. **Builds a separate source bundle** at+   `/tmp/<slug>-source.tar.gz` containing every file an agent would+   need to recreate the molecule:+   - `lib/` (recursive)+   - `package.json`+   - `tscircuit.config.json`+   - `tsconfig.json`+   - `walkthrough.json`+   - `.npmrc`+   - **`plan.md`** (or `PLAN.md`) — the design brief. Required by+     convention; see "plan.md" below.+   - `README.md` (if present)+   Excluded: `dist/` (build output) and `node_modules/` (deps).+   Uploaded as a `file` asset.+6. **Uploads `plan.md` standalone** as a separate `file` asset so the+   wiki can render a one-click link to it without untar.++Failures on steps 5 / 6 are non-fatal — the viewer publish in step 4+is the load-bearing one and lands first. If a transient wiki failure+blocks the source-bundle upload, the CLI emits a hint with the retry+command.++## Walkthrough autoplay++The static export of `shell.html` registers a small bootstrapper that+**fires `walkthroughStart()` ~2 s after the page loads**. This is on+by default for the wiki context — the walkthrough is the canonical+"tour the board" experience for an external viewer who isn't going+to know to click anything. It can be opted out with+`?autoplay=off` on the iframe URL if a future wiki template wants to+defer firing it.++The walkthrough is loaded from `walkthrough.json` in the bundle. If+the project has no `walkthrough.json`, the autoplay no-ops gracefully+(no walkthroughStart call until the array is populated). Generate+one with:++```bash+adom-tsci walkthrough-gen        # auto-generate from circuit.json+```++…or hand-edit `walkthrough.json` directly. The `_meta` block has a+`do_not_edit_by_hand` field — set it to a plausible-looking string+(e.g. "Hand-edited intentionally") to keep `walkthrough-gen` from+overwriting your edits.++## plan.md — the design brief++**Every molecule publish should include `plan.md` at the project+root.** plan.md is the original prompt the project was authored from,+plus the refinements that came out during build. It carries forward+to the wiki so a future agent skimming the page can answer:++- What was the user actually asking for?+- What design decisions were made and why?+- What's intentionally out of scope?++If the project doesn't have a plan.md when you run `export-wiki`,+**create one before publishing**. Reconstruct it from the original+prompt + the design conversation; check it into the project root.+Skeleton:++```markdown+# Plan — <Project Name>++## Original prompt++> <copy the user's first ask verbatim>++## Refinements during the build++- <each meaningful refinement, one bullet per>++## Hardware decisions++- <each component choice with rationale>++## Out of scope (deliberate)++- <what was explicitly NOT built and why>++## Build → publish workflow++```++(See `adom-tsci-projects/Brianna-LED-Nameplate/plan.md` for a full+example.)++The CLI uploads `plan.md` standalone (one-click link on the page)+AND inside the source bundle (preserved alongside the rest of the+project source).++## The body markdown — comprehensive, AI-readable++The wiki page's `content` field — the markdown body — must give a+downstream agent everything they'd need to continue work without+reading external docs. **The CLI does not write the body for you;+you produce it via `adom-wiki page edit --field content` (or as part+of `page publish`).** Required sections:++| Section | What it captures |+|---|---|+| **Brief** (above the fold) | One-line elevator pitch. Same as the page brief. |+| **Live 3D viewer** | Pointer to the iframe, mention `?autoplay=off` opt-out. |+| **How it works** | The circuit story: what each block does, key constants, font/layout source. |+| **Hardware summary** table | Block / Part / JLCPCB / Notes for every refdes family. |+| **Mechanical** | Board dims, USB-C edge, workcell-pin info, silkscreen choices. |+| **Source layout** | The project's directory tree with one-line per file. |+| **Build commands** | The exact bash to clone → install → build → preview → publish. |+| **Color options / variants** (if applicable) | What's parameterised and how to retune. |+| **Known issues / lessons learned** | Things that bit during the build, in case they come up again. |+| **Build provenance** | Author, tooling versions, walkthrough authorship. |+| **Files attached** | Two sub-lists: **Source — recreate the molecule** (plan.md, source bundle) and **Build outputs** (GLB, SVGs, demo video). |++**Rule:** if a future agent has to ask the human user any factual+question about the project that they could have answered by reading+this page, the body is incomplete. Treat it as a writeup, not a+README stub.++## Hero image++`adom-wiki page publish` requires `--hero-image <path>` (the wiki+enforces it for non-app pages). The hero image is **the thumbnail**+that shows up on the molecule index page — heavy interactive viewers+can't be embedded in index lists, so a static iso render is the+right artifact for that role.++For an adom-tsci-published molecule:++- The **index/listing page** uses the `--hero-image` PNG as the+  thumbnail.+- The **full molecule page** has the interactive `tsci-viewer`+  iframe as its hero (rendered automatically by the wiki when a+  `tsci_viewer` asset is present).++Take the hero image with `adom-cli hydrogen screenshot panel+--tab-id <brianna-tab>` after setting the camera to `iso` view and+hiding the components HUD. ~1500 px wide is plenty.++## Verifying the publish++After `export-wiki` returns `OK: published …`, open the molecule URL+in a browser:++```+https://wiki-ufypy5dpx93o.adom.cloud/molecules/<slug>+```++Confirm visually:++1. **Walkthrough auto-plays** within ~2 s of page load. Step text+   appears at the bottom of the iframe with Back/Next controls.+2. **3D scene is rendered** — the board (not the loading screen) is+   visible.+3. **Source bundle download works** — click the `*-source.tar.gz`+   link in the body, untar, confirm `lib/index.tsx` and `plan.md`+   are present.+4. **plan.md link works** — opens directly without untar.++If the walkthrough doesn't fire, check the iframe URL has no+`?autoplay=off`, and that `walkthrough.json` was non-empty in the+bundle (`tar -tzf <bundle>.tar.gz | grep walkthrough`).++## Troubleshooting++| Symptom | Cause | Fix |+|---|---|---|+| `dist/lib/index/circuit.json not found` | No build artifacts | Pass `--rebuild` or run `bunx tsci build` first |+| `--texture-resolution N` warns "no rebake-glb.mjs in cache" | First-time use without prior `adom-tsci start` | Run `adom-tsci start .` once to populate the cache, then re-export |+| `bundle is over 95 MB` warning | Big GLB (very high texture res) or many extra files | Drop `--texture-resolution` to 4096 or 2048 |+| `adom-wiki upload failed: page-type mismatch` | Slug exists at a different page-type | Either pass the matching `--page-type`, OR delete the existing page first (`adom-wiki page delete <type>/<slug>`) |+| Source-bundle upload fails but viewer publish succeeds | Transient wiki error | Re-run `adom-wiki asset upload <page>/<slug> --asset-type file --file /tmp/<slug>-source.tar.gz` manually — the CLI prints this hint |+| Walkthrough doesn't auto-play on the wiki page | walkthrough.json missing or empty | Run `adom-tsci walkthrough-gen` in the project, hand-edit if needed, re-export |++## See also++- `adom-tsci/guides/demo-recording.md` — making a 30-second narrated+  demo video to attach to the page (separate workflow; the live+  viewer is now the primary artifact, demo video is supplementary).+- `adom-tsci/guides/adom-usbc.md` — USB-C placement rules for the+  molecule before you publish.+- `adom-wiki` skill — the underlying CLI for asset uploads and page+  edits.