The web viewer draws Blender's glTF in three.js on GitHub Pages
Decided with Cansin on 2026-11-01, spec #180; tickets #181 (the page and the Pages workflow) and #182 (the GLBs). Follows ADR 0007: MuJoCo simulates, Blender draws, and now Blender also authors what the browser shows. Amended 2026-11-01 (#194): three.js replaces
<model-viewer>so the page shows style B, the pictures’ look. Amended 2026-11-01 (#211): the key light casts shadows, lines scale with the canvas. Amended 2026-11-01 (#225, ADR 0009): the viewer moved to yellowpine.com/noggin/viewer/, the site’s docs took the root. Amended 2026-11-01 (#221): a PR touchingmodel/,eyes/orweb/bakes and tests the GLBs too; every run reuses the last GLBs built from the same inputs. Amended 2026-11-01 (#268): the site serves three.js itself; the page runs scripts from the site alone. Amended 2026-11-01 (#271): the camera frames the Stage as the hero GIF does, and lines follow its size on screen. Amended 2026-11-01 (#281): the viewer is a page of the docs site at /viewer/, in its theme (header, search, nav); docs pages can drop in a small one per Stage. Amended 2026-11-01 (#333, ADR 0013): the page is an Astro page (site/src/pages/viewer.astro) and the module lives beside it insite/src/viewer/, loaded by the site’s footer on any page with a viewer; Vite bundles three.js and its addons from npm, the Draco decoder is copied from three’s package, and vendored.py, the import map and the page’s own CSP are gone (the site’s one CSP covers it). Amended 2026-11-02 (#468, spec #467): the landing page opens with a viewer of Stage 3, the hero GIF its poster until it loads (on scroll into view; on a phone on a “Play in 3D” tap), and the gesture GIFs are gone: the viewer’s buttons are the one gesture picker, and each click keeps the address the deep link,/viewer/?stage=<n>&gesture=<g>. Amended 2026-11-02 (#482, spec #467): an Explode button moves Stage 3’s sub-assemblies apart and back by the offsets the exploded render used (model/render/pictures.py EXPLODE, through macros.json), and&explode=1opens it so; the exploded render is gone. Amended 2026-11-02 (#482): the controls are one bar under the viewer: Stage a segmented 1 · 2 · 3, the gestures Title Case chips with the Tour (every clip in turn) in place of hero, and Explode a toggle; under it one line says what the gesture is and which Claude Code event plays it, from the behaviour table’s code (macros.json). Deep links are unchanged. Amended 2026-11-02 (#538, #496): the viewer is built in the Checks workflow’sBlenderjobs, and a red build fails its requiredChecksgate, not asitecheck. Amended 2026-11-02 (#547): “Built in CI” describes the Checks workflow and Site Deploy, not the Pages workflow. Amended 2026-11-02 (#640, ADR 0019): the viewer is off the site and CI bakes no GLB until the clean-room Mech;just webbakes them locally. Amended 2026-11-02 (#649, ADR 0019): the viewer is back on the site at /viewer/ for the Next Mech alone (next-mech.glb, baked by Checks’Blenderjob); it is still, so its GLB has no clips and the page no gesture bar. Amended 2026-11-02 (#642): a GLB per Base candidate (next-mech-a.glb,next-mech-b.glb), one viewer each. Amended 2026-11-02 (#686): a GLB per head variant (next-mech-back.glb,-crown,-split) in their place, its button in the ranking’s order, marked with what it fails. Amended 2026-11-02 (#712): Back alone (next-mech-back.glb), Cansin’s pick; its one button keeps the ranking’s order and marks, so a later variant comes back beside it. Amended 2026-11-02 (#704, ADR 0020): Back twice, its Skeleton as Bones (“Back”) and plain (“Back plain”,next-mech-back-plain.glb), a button each. Amended 2026-11-03 (#805, ADR 0022): the look switch is the Skeleton switch, Realistic and Mechanical (next-mech-back-mechanical.glb), each GLB in its Theme’s colours. Amended 2026-11-03 (#806, ADR 0022): the header’s Theme bar picks the Skeleton for every page, the viewer’s GLB too, in place of the viewer’s own Skeleton switch. Amended 2026-11-03 (#819, ADR 0022): the bar picks a Preset; the viewer draws its Skeleton shape’s GLB, one per Shape, and paints each Colour group’s material in the Preset’s Palettes in the browser, or in its own mix from a select per axis (Shapes and Palettes), kept in the address. Amended 2026-11-03 (#795): Checks’Deployjob deploys the site, in place of Site Deploy. Amended 2026-11-03 (#811): Explode is a segmented Assembled · Sub-assemblies · Parts, each step animated, and&explode=<0|1|2>opens it so (1as before); at Parts each part slides out along its Assembly direction on its sub-assembly’s offset (model/render/pictures.py offsets, the pictures’ one function). Each GLB node carries its offsets in its extras (web/build.py explode), as the look is carried: they need the parts’ meshes, which the site’s build lacks, so macros.json no longer has them. Amended 2026-11-03 (#839): the viewer is the Mech’s one motion: pages embed it several times, each its own deep link (data-link, e.g.gesture=wink&explode=1&preset=morty, on itsdata-stage) repeating its gesture, the address the deep link of the /viewer page’s alone. One WebGL renderer a page draws every viewer, each copied into its own canvas; each GLB loads once, every viewer of it a clone; a viewer loads only once scrolled into view, a still (its Stage’s isometric panel) in its place until then, and of those on screen the three that came into view or were touched last animate, the rest holding their last frame. The README’s and the home’s stills link to the viewer deep-linked to their Stage, Explode level and Preset. The poster’s camera of #597 is gone. Amended 2026-11-03 (#883): the /viewer page’s viewer alone has the bar (Stage, gestures, Explode, the mix); one in a page shows its Stage and motion with no control. With no Preset picked, every viewer opens on the bare realistic Skeleton in the anatomical Palette (ADR 0022). Amended 2026-11-04 (#894, ADR 0024): the embed link gainsview=(front, side, isometric; the default framing without it) andpart=(that part alone at full look, every other ghosted). Every embed holds a plain link to its deep link (“Open … in the viewer”), which GitHub shows and the viewer replaces. Every viewer opens on the hero loop in the Default build (ADR 0022), unless its link names a gesture; a Stage with noheroclip plays Rest. Every viewer but the /viewer page only rotates (no zoom, no pan: the wheel and a pinch scroll the page past it), with one reset icon, labelled for screen readers, that appears once the reader turned it and brings the camera back to the view it opened on; /viewer keeps its bar, zoom and pan. The black Skeleton’s lift (a charcoal whose ramp, highlight and lines still read) is one look number Blender writes into the GLB’s extras, so the viewer holds none of its own.
The README’s stills and GIFs show the Mech from fixed angles. The web viewer is a public page on GitHub Pages (yellow-pine.github.io/noggin, linked from the README) where anyone can orbit and zoom a Stage, play each gesture and watch the hero loop.
- Baked, not simulated, in the browser. Motion is MuJoCo’s baked servo trajectories (#179), the same source as the
GIFs and the hero. Blender keys every part’s world pose per frame and exports one Draco-compressed GLB per Stage,
with one named glTF animation per gesture plus
hero(actions stashed so the exporter includes each). - three.js draws it in style B (MIT, one pinned version, served by the site; see the last paragraph of this bullet):
MeshToonMaterialwhose gradient map is the pictures’ light per N.L (the two-step toon ramp mixed with the satin, sampled from Blender’s numbers) and one highlight band, black outlines on silhouettes (an inverted hull) and crease lines where faces meet at more than 60 degrees, the key light riding at the camera’s upper right and casting shadows as Eevee’s sun does (#211 measured the pictures’ two tones to be these cast shadows). On load and on a Stage switch the camera frames the Stage as the hero GIF does (its view, 15 degrees to the right and up, every vertex in frame with the pictures’ 1.06 margin). Lines follow the Stage’s size on screen as the GIFs’ do:line_pxwhen it is as big as in a 4:3 frameline_at(640) px wide, through every zoom and resize, never under 1 px nor over twiceline_px. Orbit and zoom areOrbitControls, gestures and the hero play throughAnimationMixer, the Stage switch loads the other GLB. The viewer is one module,site/src/viewer/viewer.mjs, its framing module (frame.mjs) and its deep link, caption and explode offsets (state.mjs), both tested with Vitest, bundled by the site’s build. It draws every<div class="noggin-viewer" data-stage="stage1">on a page, with a button per clip under it: the viewer’s page (site/src/pages/viewer.astro, in Starlight’s theme with no table of contents) adds the Stage buttons, and any page can drop in a small one. A browser test (Playwright in Chrome,site/smoke.pw.mjs) loads Stage 1 on the built site with no error and no request to another host but GitHub’s repo facts in the header. three.js and its addons come from npm, bundled by the site’s build, and the Draco decoderDRACOLoaderfetches is copied from the same package; the lockfile’s integrity hashes pin them (ADR 0013). The site’s CSP lets scripts from the site alone run (plus the decoder’s WASM inDRACOLoader’s Blob worker). - One source for the look. Blender’s export writes the look numbers (line width, crease angle, the light ramp, highlight, key light) into the GLB scene’s glTF extras and each part’s colour into its glTF material; the page reads them and holds no look numbers of its own. The canvas is see-through: the background is the page’s own, in either theme.
- Built in CI, deployed with GitHub’s own Pages actions. The Checks workflow (
checks.yml) builds the viewer on PRs and on main: aBlenderjob bakes the trajectories and runsjust webin our Blender image, which holds the pinned Blender Linux tarball (sha256-checked; re-pinned weekly byblender-updates.yml), when what the viewer is made from changed (scripts/inputs.py), else the gate restores the last viewer built from the same inputs. TheChecksgate puts it in the site and plays it in Chrome, and a red build fails that required gate (#245, #496). Checks’ last job,Deploy, deploys main’s site artifact once the gate passed, with no rebuild; a red build on main leaves the last site up. Pages’ source is GitHub Actions, so nothing built is committed. - Eyes gestures only for now. Head and jaw gestures come with the second Core; Stages 2 and 3 show the eyes gestures and the hero loop.
Considered options
Section titled “Considered options”- Live MuJoCo in the browser (the WASM build): rejected, physics per viewer for motion that is already baked, and a second look beside Blender’s.
- Google’s
<model-viewer>(the first page, #181): rejected in #194. It covers orbit, zoom and named animations with no code, but it draws glTF’s PBR materials only: no toon ramp, no outlines, no crease lines, so the page did not look like the GIFs. Freestyle lines and Eevee’s Shader-to-RGB ramp have no glTF form. - three.js’s
OutlineEffectfor the silhouettes: rejected, it pushes along a unit normal in model units and our GLBs are in metres (docs/research/2026-11-01-web-toon.md). - Committing the GLBs (or deploying from a branch): rejected, binaries in history on every model change.
noggin v0.2.26-6-g09bf9b7 · 09bf9b7