fix: spin voxel creatures around their own center, not the world origin

The live turntable rotated `mesh.rotation.y`, but the mesh sits at the
world origin while the camera aims at the bounding-box center. Asymmetric
archetypes (e.g. the horse, whose long body + front-protruding head puts
its centroid at z~2) orbited the origin as they spun and slid off-frame —
visibly jamming the horse against the right edge of its stage.

Wrap the mesh in a pivot Group at `center` with the mesh offset by
-center, and rotate/scale the pivot in all three render paths (live
turntable, reveal pop, static thumbnail). The creature now spins and
pops in place around its own center.

Also add wiki/voxel-rendering.md documenting the voxelizer, the
bounds-driven camera, the turntable pivot rule, and the thumbnail
shared-renderer context cap; link it from the wiki index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/buddy_fusion/voxel_embed.py

@@ -198,11 +198,21 @@ async function setupVoxel(root) {
   scene.add(new THREE.HemisphereLight(0xffffff, 0x404060, 1.1));
   const key = new THREE.DirectionalLight(0xffffff, 1.4); key.position.set(6, 12, 8); scene.add(key);
   const cells = voxelsFromGenome(cfg.genome);
-  const mesh = voxelBuildMesh(THREE, cells); scene.add(mesh);
+  const mesh = voxelBuildMesh(THREE, cells);
   // frame the whole creature (incl. legs/horns) with padding from its bounds.
   const bb = new THREE.Box3().setFromObject(mesh);
   const center = bb.getCenter(new THREE.Vector3());
   const radius = bb.getSize(new THREE.Vector3()).length() * 0.7 + 3;
+  // Spin/scale around the creature's OWN center, not the world origin. Most
+  // archetypes are asymmetric in the horizontal plane (the horse's long body +
+  // front-protruding head puts its centroid well off z=0); rotating the mesh
+  // about the origin would orbit that centroid and slide the creature off-frame.
+  // A pivot at `center` with the mesh offset by -center keeps it centered.
+  const pivot = new THREE.Group();
+  mesh.position.sub(center);
+  pivot.position.copy(center);
+  pivot.add(mesh);
+  scene.add(pivot);
   // 3/4 top-down isometric-ish angle, Crossy-Road style.
   cam.position.set(center.x + radius * 0.85, center.y + radius * 0.62, center.z + radius * 0.85);
   cam.lookAt(center);
@@ -212,7 +222,7 @@ async function setupVoxel(root) {
     // One WebGL context per thumbnail would blow past the browser's ~16-context
     // cap as the family tree grows and silently blank the oldest stages; a
     // single shared context keeps the total flat regardless of tree size.
-    mesh.rotation.y = 0.7;
+    pivot.rotation.y = 0.7;
     const shared = voxelThumbRenderer(THREE);
     shared.setSize(W, H);
     shared.render(scene, cam);
@@ -236,9 +246,9 @@ async function setupVoxel(root) {
   function loop(now) {
     if (!root.isConnected) { renderer.dispose(); if (renderer.forceContextLoss) renderer.forceContextLoss(); return; }
     const dt = Math.min(0.05, (now - t0)/1000); t0 = now;
-    mesh.rotation.y += dt * 0.5;
-    if (reveal < 1) { reveal = Math.min(1, reveal + dt*1.1); mesh.scale.setScalar(0.15 + 0.85*voxelEaseReveal(reveal)); }
-    else { mesh.scale.setScalar(1); }
+    pivot.rotation.y += dt * 0.5;
+    if (reveal < 1) { reveal = Math.min(1, reveal + dt*1.1); pivot.scale.setScalar(0.15 + 0.85*voxelEaseReveal(reveal)); }
+    else { pivot.scale.setScalar(1); }
     controls.update();
     renderer.render(scene, cam);
     requestAnimationFrame(loop);

wiki/index.md

@@ -16,6 +16,8 @@ See [README](README.md) for how this wiki works.
   design bet, components, data flow, deployment, and hard-won gotchas.
 - [local-dev-runtimes](local-dev-runtimes.md) - Fake vs real runtime boundary,
   which mode exercises what, and the local CPU caveat.
+- [voxel-rendering](voxel-rendering.md) - The Three.js voxelizer: recipe→cells,
+  bounds-driven camera, turntable/reveal pivot, and the thumbnail context cap.
 
 ## Integrations
 

wiki/log.md

@@ -2,6 +2,13 @@
 
 ## 2026-06-14
 
+### Voxel rendering page + turntable centering fix
+
+- Added `voxel-rendering.md` documenting the voxelizer, bounds-driven camera,
+  the thumbnail shared-renderer context cap, and the turntable pivot rule.
+- Recorded the fix where the turntable rotated about the world origin instead of
+  the creature's centroid, sliding asymmetric archetypes (horse) off-frame.
+
 ### Ported AI/dev tooling from build-a-buddy-hf
 
 - Added `CLAUDE.md` (workflow rules: English-only, never-auto-push to the Space,

wiki/voxel-rendering.md

@@ -0,0 +1,91 @@
+---
+title: Voxel Rendering (the Three.js voxelizer)
+tags: [architecture, debugging, frontend, three-js, rendering]
+last_updated: 2026-06-14
+confidence: high
+sources:
+  - src/buddy_fusion/voxel_embed.py
+related_pages:
+  - gradio-embed-integration.md
+  - system-overview.md
+---
+
+# Voxel Rendering (the Three.js voxelizer)
+
+## Summary
+
+How a genome becomes the cube creature on screen, and the rendering invariants
+that keep it readable and centered. The voxelizer lives entirely in
+`VOXEL_SETUP_JS` inside `src/buddy_fusion/voxel_embed.py` (delivered via
+`js_on_load`; see [gradio-embed-integration](gradio-embed-integration.md) for how
+the embed boots and re-inits). Read this before touching archetype geometry, the
+camera, the turntable, or the reveal animation.
+
+## Key Details
+
+- **Recipe → geometry, never raw voxels.** The model only picks the recipe
+  (`archetype` + `parts` + `palette`). `voxelsFromGenome(g)` turns that into a
+  flat list of `{x, y, z, color}` cells. `VOXEL_ARCH` holds the per-archetype
+  body-plan templates (body/legs/head dims, `headMode`, `feat`); `g.parts` layer
+  extra/mutated features (leg/horn/wing/tail/arm/eye/second-head) on top.
+- **Cell coordinate convention.** `box(cx,cy,cz,w,h,d,color)` centers a block on
+  `(cx, cz)` in the horizontal plane (`x - (w-1)/2`, `z - (d-1)/2`) but grows
+  **up** from `cy` (`cy + y`, no vertical centering) — y=0 is the ground, legs
+  start there, `bodyY = legLen`. Keep this convention when adding parts or the
+  feature will float / sink.
+- **One InstancedMesh per creature.** All cells render as instances of a single
+  `BoxGeometry(0.96³)` + `MeshStandardMaterial` (the 0.96 leaves a seam so cubes
+  read as discrete). Per-instance color via `setColorAt`. This keeps a creature
+  to one draw call regardless of voxel count.
+- **Camera framing is bounds-driven.** After building the mesh, a
+  `Box3.setFromObject` gives `center` + `radius`; the camera sits at a fixed 3/4
+  top-down isometric offset (`center + radius·(0.85, 0.62, 0.85)`) and
+  `lookAt(center)`. So the framing auto-fits any creature size without per-archetype
+  tuning.
+- **Reveal animation.** `voxelEaseReveal` is an ease-out-back (overshoots past
+  1.0 then settles) driving `scale` from 0.15→1 for the "pop" when a spliced
+  child appears (`autoplay_reveal=True`).
+
+## Failure Modes
+
+- **Turntable must spin around the creature's own center, not the world origin.**
+  The bug (fixed 2026-06-14): the live stages rotate the creature as a turntable.
+  Rotating `mesh.rotation.y` spins about the mesh's local origin, which is the
+  **world origin (0,0,0)** — but most archetypes are asymmetric in the
+  horizontal plane (e.g. `horse` has `body:[4,4,7]` plus a `headMode:"front"`
+  head + snout protruding to z≈7, so its centroid sits around z≈2, well off the
+  origin). Spinning an off-origin centroid makes it **orbit** the origin and
+  slide out of frame — the horse visibly jammed to the right edge while the more
+  symmetric chick stayed put. The camera aims at the fixed initial `center`, so
+  the drift is purely the rotation pivot.
+  **Fix:** wrap the mesh in a pivot `Group` positioned at `center`, offset the
+  mesh by `-center`, and rotate/scale the **pivot** instead of the mesh. The
+  geometry then spins (and the reveal scales) in place around its own center.
+  Apply it in all three render paths — the live turntable rotation, the reveal
+  scale, and the static thumbnail frame (`pivot.rotation.y = 0.7`).
+  Detection: watch a tall/long archetype (horse, hippo, dog) through a full
+  turn; if it swings toward an edge at some angles instead of rotating in place,
+  the pivot is at the origin, not the center.
+- **WebGL context cap (~16) — thumbnails must share one renderer.** Each live
+  stage holds a `WebGLRenderer`/context; the family tree grows one node per
+  creature, so a live context per thumbnail would blow the browser cap and blank
+  the oldest stages. Thumbnails (`voxel_html(thumb=True)`) render through one
+  shared offscreen renderer (`window.__voxelThumbRenderer`,
+  `preserveDrawingBuffer:true`) and snapshot to an `<img>` — flat context count
+  regardless of tree size. Only the two ancestor stages + the child stage keep a
+  live context. See [gradio-embed-integration](gradio-embed-integration.md).
+- **Detached live stages leak a context if not disposed.** The animation loop
+  guards on `root.isConnected`; when a stage leaves the DOM it calls
+  `renderer.dispose()` + `forceContextLoss()` and stops the RAF. Skipping this
+  leaks a context per re-render and eventually trips the cap above.
+
+## Sources
+
+- `src/buddy_fusion/voxel_embed.py` (`VOXEL_ARCH`, `voxelsFromGenome`,
+  `voxelBuildMesh`, `setupVoxel`, the pivot-centering fix, the shared thumbnail
+  renderer)
+
+## Related Pages
+
+- [gradio-embed-integration](gradio-embed-integration.md)
+- [system-overview](system-overview.md)