---

name: 3d-viewer-design
description: >
Design rules for any 3D viewport Claude generates inside Adom — CAD,
EDA, mechanical, PCB, component preview, schematic 3D, molecule
viewer, any WebGL canvas. The headline rule: always use the Adom
Babylon viewer at gallia/viewer/ as the baseline — don't rebuild
from scratch, extend it. Covers engine choice (Babylon, never Three),
canonical-viewer reuse + upstream contribution workflow, background
color (gradient, never pure black/white), HDRI + hemispheric
lighting, PBR material fixups, ArcRotateCamera defaults including
zoom-to-mouse AND Shift+Alt+Click orbit-center recentering
(Fusion 360 / Onshape style), ViewCube / view presets, world-
origin axis helpers (always on — critical because origins are
where every Adom 3D integration bug hides), measurement markers,
and AI-drivability hooks. Read this BEFORE you pick
scene.clearColor, import any 3D library, or design any camera
interaction. Trigger words: 3D viewer, 3D viewport, scene
background, clear color, Babylon scene, adom 3d viewer, adom
babylon viewer, canonical viewer, CAD background, PCB viewer,
component viewer, GLB viewer, STEP viewer, 3D preview, viewport
design, 3D scene setup, 3d bg color, HDRI, environmentSpecular.env,
bottom light toggle, camera limits, zoom to mouse, zoom to cursor,
orbit center, recenter rotation, shift alt click, fusion 360 orbit,
onshape orbit, ViewCube, view cube, view presets, axis helper,
axes helper, origin axes, show origin, world origin, mesh origin,
coordinate system, xyz gizmo, measurement marker, Babylon vs
Three.js.

3D Viewer Design

The rules every 3D viewport across Adom should follow. Engineers look
at CAD/EDA 3D all day, and every wrong default silently wrecks the
experience: pure-black viewports hide dark parts, pure-white viewports
blow out highlights, brand-colored backgrounds tint every material,
one-light rigs kill half the silhouette, default camera limits
gimbal-lock the moment anyone tries to look under a chip, zoom-to-
origin teleports users away from what they were inspecting, and a
fixed orbit center makes every rotation on a large assembly feel like
flying blind. Everything below is either (a) a rule Claude keeps
getting wrong from first principles or (b) a goodie the team already
baked into the canonical Adom Babylon viewer at gallia/viewer/ that
deserves to be the default everywhere.

---

1. Engine choice — always Babylon.js, never Three.js

The rule: every 3D viewer Claude builds for Adom uses Babylon.js.
No Three.js. No react-three-fiber. No @react-three/drei. No
three-bundle, RGBELoader, GLTFLoader-from-three, OrbitControls, or any
other Three.js module.

Why Babylon over Three.js, even though Three.js is the default Claude reaches for

Most LLMs — including Claude — default to Three.js because Three.js
has more training data: more Stack Overflow answers, more GitHub
stars, more tutorials, more "how do I…" blog posts. That is the only
reason, and it is not a reason that matters for our use case.

• Material system. Babylon's PBRMaterial + environment texture
  pipeline is more correct and more tunable than Three's
  MeshStandardMaterial. HDRI reflections on gold/chrome/anodized
  aluminum look photorealistic in Babylon with a two-line setup.
• GLB loader fidelity. Babylon's glTF 2.0 loader handles KHR
  extensions (draco, meshopt, variants) more consistently than
  Three's GLTFLoader, which has long-standing edge cases on
  KiCad-exported GLBs.
• First-class ArcRotateCamera. Babylon ships an orbit camera
  with radius/alpha/beta + soft behavior limits + zoomToMouseLocation
  built for inspection workflows. Three's OrbitControls is an
  add-on with a different coordinate model.
• Post-process pipeline. Babylon's DefaultRenderingPipeline
  (FXAA, bloom, SSAO, tone mapping) is one flag away.
• Scene inspector. Babylon's built-in Inspector
  (scene.debugLayer) is a debugger's dream for material and lighting
  issues. Three has no equivalent shipped with the engine.
• Consistency with the canonical viewer. gallia/viewer/ — see
  §2 — is Babylon. One engine ecosystem-wide means every Adom
  viewer inherits every improvement for free.

Claude will feel pulled toward Three. Resist it. If you find yourself
writing import * as THREE from 'three' or new THREE.Scene(), stop
and rewrite against @babylonjs/core.

Exception: none. Not even "quick prototypes."

---

2. Use the canonical Adom Babylon viewer as the baseline — extend, don't fork

The rule: every new Adom app that needs 3D starts from the
canonical Adom Babylon viewer at gallia/viewer/. Not from a blank
Babylon new Scene(). Not from a Babylon playground snippet. Not
from a fresh create-babylon-app. From the canonical viewer.

The canonical viewer already solves — or is the right place to solve —
every problem in this skill. If you build a new viewer from scratch
for your new app, you are either (a) re-implementing what already
exists and drifting, or (b) solving it wrong and shipping regressions
the canonical viewer would have caught.

2a. What the canonical viewer gives you for free

Out of the box, gallia/viewer/ ships with:

• Babylon engine + environmentSpecular.env HDRI already bundled
  (gallia/viewer/babylon-bundle.min.js, viewer/js/environmentSpecular.env).
• ArcRotateCamera with soft limits (§6b) and behavior strip
  (3d.html:293).
• ViewCube / view presets — front / back / left / right / top /
  bottom / isometric buttons wired to the correct Z-up
  alpha/beta angles (see §7). Click a face, camera tweens.
• World-origin axis helper — R/G/B X/Y/Z gizmo at (0,0,0) visible
  by default so the user can always see which way is up and where
  the scene's origin lives (see §8). Toggleable but default-on.
• Bottom-light toggle for PCB under-chip inspection (§4b).
• GLB loader with Y-up → Z-up handling (§11) and
  applyGlbZUpTransform(viewer, glbSource) helper.
• Measurement tool with vertex snapping + auto-scaled markers (§9).
• Cinematic camera tour (auto-play on model load, 11-phase
  choreographed reveal).
• AI-drivability surface — window.Adom3DViewer global +
  postMessage protocol + console forwarding (§10).
• Shadow ground mesh (shadowGround) for soft contact shadows.
• MCP tool integration — callable as av_3d_display /
  av_basic_3d_display from any Claude agent.

Reuse path: embed the viewer in your app, or use the Basic3dView
entry point (gallia/viewer/3d-viewer-standalone.ts) as your starter,
or call the MCP tool to open the viewer in Hydrogen. Pick whichever
matches your app's surface — but start from this base.

2b. The upstream-first workflow for new best practices

When you discover a best practice the canonical viewer is missing —
the gradient background in §3 is the flagship current example, but
so is zoom-to-mouse (§6a), orbit-center recentering (§6c), or
anything else that lands in this skill — the workflow is:

1. Add it to the canonical viewer first. Land a PR in
   gallia/viewer/ that adds the feature as a baseline default.
   Include a toolbar toggle if it's opinionated.
2. Update this skill to reflect that the canonical viewer now
   supports it (move from "known migration debt" to "you get this
   for free").
3. Delete workarounds from downstream apps. If a downstream app
   copy-pasted a hack to fix the missing behavior, remove it — the
   app should inherit from the canonical viewer now.
4. Roll out via the Adom update pipeline. All consumers get the
   new default automatically on their next adom update or workspace
   refresh. No per-app migration required.

2c. Do NOT do any of these

• Do not fork the viewer into your app's repo. Forks drift. A
  feature added to the canonical viewer never makes it into your
  fork, and a bug fixed in your fork never makes it back.
• Do not write a parallel mini-viewer to "just show a GLB
  quickly." Basic3dView already exists for that use case
  (basic-3d-viewer skill). Use it.
• Do not ship app-local workarounds for viewer bugs. File them
  against gallia/viewer/ and fix them there.
• Do not re-implement ViewCube, measurement, HDRI loading, or
  bottom-light-toggle per-app. Inherit from the canonical viewer.

2d. Current canonical-viewer debt — improve it, don't route around it

The canonical viewer predates some of the rules in this skill. As
of 2026-04-24:

• Clear color is flat near-black Color3(0.05, 0.06, 0.08)
  (fp-to-3d.js:~1642) — should be the gradient in §3. Fix
  upstream per §2b.
• cam.zoomToMouseLocation is not explicitly set on all camera
  construction paths — audit and set it on every ArcRotateCamera
  (§6a).
• Orbit-center recentering (§6c) doesn't exist yet — add as a new
  feature to the canonical viewer, not as a per-app hack.
• Mesh-local axis helpers (§8b) and the screen-space corner triad
  (§8c) don't exist yet — audit and add upstream. The world-origin
  helper (§8a) may or may not be present; verify and make it
  default-on if missing.

These are the next PRs for gallia/viewer/. None of them is more
than a ~20–40-line change.

2e. How to extend — the 5-tier layering decision matrix

"Extend, don't fork" (§2c) is the rule. Layering is the
implementation. There are five tiers, ordered from most-embedded
(preferred) to least-embedded (rare, last resort). Pick the highest
tier that works for your app.

Tier 1 — Pure embed in a Hydrogen webview or AV panel (90%+ of apps)

You write zero viewer code. Your app opens the canonical viewer in a
Hydrogen tab (or the AV panel), passes a GLB path + a few config
knobs, and drives it via postMessage. Every future improvement to
the canonical viewer (brightened gradient, axis helpers, new
toolbar buttons) shows up in your app automatically on the next
adom update. Default to this tier. Apps like shotlog,
parts-search, library-review, chipfit, 3d-component-creator, and
adom-tsci all belong here. If you're tempted to leave this tier,
prove it to yourself first by listing exactly what the canonical
viewer can't do and asking whether adding it upstream (§2b) would
serve everyone.

Tier 2 — MCP tool call (simplest path)

av_3d_display({ glb_path, title, ... }) or
av_basic_3d_display({ glb_path, title }) from the Claude side. No
browser code in your app at all. Use this when your "app" is
fundamentally an AI pipeline that ends in "show this to the user" —
a one-shot display, a generated preview, a datasheet render. Same
inherited behavior as Tier 1.

Tier 3 — Import Basic3dView into your own canvas host

gallia/viewer/3d-viewer-standalone.ts exposes
window.Adom3DViewer.init(canvasEl, opts). You host the canvas in
your own DOM (for layout reasons — you want the viewer inside your
app's workspace tab instead of a separate panel), but Babylon scene
setup, HDRI, camera defaults, GLB loader, Y-up→Z-up transform, axis
helpers, pivot sphere, and bottom-light toggle are all inherited.
This is the sweet spot when you need a 3D tab inside your app's
workspace rather than a separate panel.

Tier 4 — Canonical viewer + extension hooks (plugin-style)

When you need one or two custom pieces — an app-specific toolbar
button, a custom scene.onBeforeRender observer, a scene-graph
annotation your app owns, a net-highlight overlay for PCB routing —
you add the extension points upstream first (§2b workflow), then
use them from your app. The canonical viewer becomes an extensible
host, not a closed box. If it doesn't expose the hook you need,
land the hook upstream before your app ships. Don't let missing
hooks push you to Tier 5 unless there's genuinely no way to
generalize them.

Tier 5 — Roll your own, but still Babylon, still inherit helpers (last resort)

Very rare. When justified, you still import @babylonjs/core, still
call applyGlbZUpTransform, applyAdomViewportDefaults,
applyAdomCameraDefaults, the axis helper functions, the
pivot-sphere wiring, the CSS gradient. Every §1–§15 rule still
applies. You're rolling your own scene orchestration, not your
own rendering stack.

2f. Three-question decision flow

1. Is your app's 3D "view this model / scene data"? → Tier 1
   or 2 embed. Stop here. If you're thinking "but I need a custom
   layout," re-ask #1 — most custom-layout needs are "I want my own
   panel chrome around a standard viewer," which is an embed with a
   styled wrapper, not a custom viewer.
2. Does your app need the canvas inside its own DOM / workspace
   tab? → Tier 3 (Basic3dView import). You still inherit
   everything; you just get to pick the canvas parent.
3. Do you need custom scene behavior the canonical viewer can't be
   taught? → Tier 4. Add the hook upstream, then use it. Only
   jump to Tier 5 if you're certain the behavior doesn't generalize.

2g. Signals you should NOT roll your own

• "The canonical viewer doesn't have feature X" → add X upstream
  (§2b). If it generalizes, everyone benefits; if it doesn't, it
  probably shouldn't be in a shared viewer anyway.
• "I need a custom toolbar." → the canonical viewer's toolbar can
  be extended. Add the extension point upstream if it isn't there.
• "I need different default materials." → set them via
  tweak_scene postMessage (§10b) or on init. Not a rolling reason.
• "I want my own layout around the canvas." → Tier 3 import lets
  you own the layout without forking the scene.
• "Three.js has a library that does X." → see §1. No.

2h. Signals you might legitimately roll your own

• Render-to-texture pipelines — ML training data generation,
  simulation frames streaming, deterministic render farms. The
  canonical viewer is a UI; you need a renderer-as-service.
• Hybrid 2D+3D canvases with custom layout math where 3D is
  incidental (e.g. a schematic tool where 3D is a hover preview).
• Realtime streaming / headless rendering — WebRTC pipeline,
  cloud-rendered output, server-side render.
• Fundamentally different rendering model — ray tracing demo,
  Monte Carlo renderer, shader-education tool, game engine.
• Your app's primary purpose IS 3D in a way PCB/CAD viewing
  isn't a use case (physics sim, generative art tool). Here the
  canonical viewer is just the wrong primitive.

Even in these cases, §1 (Babylon) and the §2a helper-function
imports still apply. Don't abandon the pattern library — just the
specific entry point.

2i. One-line summary

Embed if you can, import if you must, roll if you're sure — and
never leave the canonical viewer's pattern library behind,
regardless of tier.

---

3. Background color — the one every Claude gets wrong

3a. Never pure black, never pure white, never a saturated brand color

• Pure black (#000): dark materials (black plastic, solder mask,
  anodized aluminum, dark silicon) vanish into the void. Ambient
  occlusion cannot read — shadows cannot be darker than the background.
• Near-black (rgb(0.05, 0.06, 0.08)): current canonical viewer
  default — almost as bad as pure black. Migration target per §2d.
• Pure white (#fff): white silkscreen, white plastic, chrome
  blow out. Retinal fatigue after 10 minutes. Clashes with Adom's
  dark UI chrome.
• Saturated brand color (e.g. Adom teal #00B8B1): tints every
  material through environment reflection. A silver chip on teal
  gets a teal rim and stops looking like silver.
• Flat mid-gray (#808080): fine but dead. No "up/down" cue.

3b. The Adom default: subtle vertical gradient

Both ends of the gradient are deliberately brighter than the dark
chrome tokens, because two prior attempts (v1.0 reused #21262d
at the top, v1.1 brightened the top to #3e4a5c but kept the bottom
at #0d1117) both shipped viewers that lost black chips against
the background. The v1.1 mistake was assuming "dark parts stay in
the upper half of the frame" — but a single chip centered in the
viewport at default framing lands in the lower half, where the
near-black bottom made it invisible all over again. Field feedback
(2026-04-24, second pass) forced brightening both ends.

Position	Color	Rationale
Top (~20% of viewport)	#5a6b7e	Medium steel blue-gray, ~37% luminance. Black-chip-on-sky reads with strong contrast.
Bottom (~80%)	#2a3340	Darker steel, ~20% luminance. Black chip at ~10% luminance still shows a clear ~10-point step; chrome / silver / white materials pop against this end.

Vertical, lighter-top-to-darker-bottom. Five things happen at once:

1. Black models stay visible everywhere in the frame — including
   in the lower half where they land by default. This is the reason
   the bottom was bumped from #0d1117 to #2a3340. Do not
   darken the bottom back.
2. White / chrome models stay visible. Even at #5a6b7e the top
   is still clearly darker than white silkscreen / silver pins / gold
   contacts — they still pop.
3. Implicit horizon. Lighter top reads "sky", darker bottom "ground".
4. Neutral enough for any material. Both ends are cool-toned
   steel, so colored parts (green PCBs, red LEDs, blue capacitors)
   aren't fighting a strong-tinted background.
5. Still on-brand for Adom's dark theme. We're not at "CAD light
   gray" levels (Fusion 360 tops out around #a8b0b8) — this is
   still a dark viewport, just not a dark-materials-disappear one.

Trade-off: loses perfect chrome-continuity with --bg. v1.1's
bottom #0d1117 matched the --bg panel-chrome token so the
viewport faded seamlessly into surrounding UI. v1.2 gives up that
perfect continuity — there's a small but visible tonal step where
the canvas meets the panel border. Black-chip visibility wins.
If a specific app needs perfect chrome continuity more than
black-chip visibility, document the exception per-app and use
#3e4a5c → #0d1117.

Acceptance test, non-negotiable. Load a black matte IC body
(e.g. a TQFP64) centered at default framing. The chip body must
read clearly at every vertical position as you orbit the model. If
the body disappears in any zone, the gradient is regressed — bump
the bottom color, don't work around it.

3c. Adom-branded touches go on top of the neutral gradient

• Soft teal ground contact shadow beneath the model —
  rgba(0, 184, 177, 0.04) center fading to transparent.
• Teal rim light (§4) picks out silhouettes without affecting
  base color.
• Accent-colored gizmo / HUD uses #00b8b0 teal for active state,
  #30363d for resting.

Do not tint the background teal, do not add a teal wash, do not
use #003C3F as the base.

---

4. Lighting — HDRI + hemispheric is the production default

4a. Primary rig: HDRI + hemispheric (what the canonical viewer uses)

scene.environmentTexture = CubeTexture.CreateFromPrefilteredData(
  '/js/environmentSpecular.env', scene);
scene.environmentIntensity = 0.8;

const hemi = new HemisphericLight('hemi', new Vector3(0, 1, 0), scene);
hemi.intensity = 0.6;
hemi.diffuse     = Color3.FromHexString('#e6edf3');
hemi.groundColor = new Color3(0.2, 0.18, 0.15);

HDRI handles specular reflections + ambient bounce; hemispheric
adds global fill so matte plastics don't crush to black. Reuse
Adom's bundled neutral studio HDRI at
gallia/viewer/viewer/js/environmentSpecular.env. Don't use outdoor
or dramatic HDRIs — they fight the neutral gradient.

4b. Bottom-light toggle — the PCB-inspection goodie

The canonical viewer ships a toolbar toggle that boosts the
hemispheric's groundColor to warm (3d.html:1112), simulating
bench-bounce illumination for under-chip inspection:

function setBottomLight(enabled) {
  if (enabled) {
    hemi.groundColor = new Color3(0.7, 0.65, 0.55);
    hemi.intensity   = Math.max(hemi.intensity, 1.5);
  } else {
    hemi.groundColor = new Color3(0.2, 0.18, 0.15);
    hemi.intensity   = 0.6;
  }
}

Every PCB viewer MUST have this toggle exposed. Every mechanical /
component viewer SHOULD. Costs nothing, solves the "I can't see
what's under the chip" complaint permanently.

4c. Fallback rig: three-light studio (only when HDRI unavailable)

Light	Direction (Z-up)	Color	Intensity
Key (top-front)	(0.4, 0.5, 0.8) norm	#ffffff	1.0
Fill (opposite, below)	(-0.5, -0.4, 0.2) norm	#e6edf3	0.4
Rim (back, teal-tinted)	(0.0, -1.0, 0.3) norm	#00b8b0	0.25

Plus ambient at 0.15. Never ship one directional light.

---

5. Materials — PBR by default, don't nuke what the GLB gave you

5a. Default material class is PBRMaterial, always

The rule: when you create a material in an Adom 3D viewer, it is
a BABYLON.PBRMaterial. Not StandardMaterial. Not MultiMaterial.
Not BackgroundMaterial. PBR.

Why: Babylon is built around PBR. The environmentSpecular.env HDRI
pipeline from §4a only lights PBR materials correctly — reflections,
metallic response, and the BRDF lookup texture all live on PBR. Drop
a StandardMaterial into an HDRI-lit scene and you get flat, dead
lighting regardless of environment intensity. Chrome looks like grey
paint, gold looks like tan plastic, anodized aluminum looks like cardboard.

Boilerplate for a new material:

import { PBRMaterial, Color3, Texture } from '@babylonjs/core';

const mat = new PBRMaterial('partBody', scene);
mat.albedoColor       = Color3.FromHexString('#1a1a1a'); // matte black IC body
mat.metallic          = 0;           // plastic
mat.roughness         = 0.45;        // slightly glossy, not mirror
mat.environmentBRDFTexture = scene.environmentBRDFTexture; // inherit HDRI BRDF

For metals (pins, contacts, pads):

const pinMat = new PBRMaterial('pinMetal', scene);
pinMat.albedoColor = Color3.FromHexString('#c8ccd1'); // tin-lead-ish
pinMat.metallic    = 1.0;
pinMat.roughness   = 0.25;

For gold (connector contacts, ENIG pads):

const gold = new PBRMaterial('gold', scene);
gold.albedoColor = Color3.FromHexString('#c9a04c');
gold.metallic    = 1.0;
gold.roughness   = 0.22;

StandardMaterial only belongs in two places: the laser-etch
overlay technique (§5c, where emissiveColor + zOffset is the
point and PBR would over-complicate), and legacy code paths you
haven't migrated yet.

5b. Don't nuke what the GLB gave you

Adom viewers load GLB files from tscircuit, KiCad, Fusion 360,
Blender, and user uploads. Each authoring tool bakes different
material assumptions. Do not reset incoming materials. Detect
and tweak:

scene.meshes.forEach(mesh => {
  const mat = mesh.material;
  if (!mat) return;

  if (mat.getClassName() === 'PBRMaterial') {
    // Keep PBR — just ensure env reflections apply.
    mat.environmentBRDFTexture = scene.environmentBRDFTexture;
  } else if (mat.getClassName() === 'StandardMaterial') {
    // Convert to PBR so it picks up HDRI reflections consistently.
    // See `3d.html:389–454` for the full conversion pattern
    // (copy albedoColor from diffuseColor, guess metallic/roughness
    //  from shininess, preserve texture slots).
  }
});

Loaders that write StandardMaterial by default (older Blender
exports, some KiCad export paths) should be upgraded to PBR on
load — the HDRI scene lighting depends on it.

5c. Laser etch / silkscreen overlay technique

const tex = new DynamicTexture('etch', { width: 512, height: 512 }, scene, true);
ctx.fillStyle = 'rgba(210, 212, 215, 0.8)'; // silverish, NOT pure white
const mat = new StandardMaterial('etchMat', scene);
mat.diffuseTexture  = tex;
mat.emissiveColor   = new Color3(0.82, 0.83, 0.84); // self-illuminates
mat.zOffset         = -2;                           // no z-fight with body

---

6. Camera — zoom-to-mouse, soft limits, and Fusion/Onshape-style orbit-center recentering

6a. Zoom-to-mouse is non-negotiable

Every professional CAD/EDA tool (Fusion 360, SolidWorks, Onshape,
KiCad, Altium) zooms toward the cursor, not toward the camera target.
Default Babylon ArcRotateCamera zooms toward the orbit target —
which means every scroll-in teleports the user away from whatever
they were inspecting. Flip the switch:

cam.zoomToMouseLocation = true; // Babylon >= 5.0, the magic line

One-line change, single biggest usability win on the viewer.

6b. Soft camera limits — strip behaviors first

while (cam.behaviors && cam.behaviors.length > 0)
  cam.removeBehavior(cam.behaviors[0]);
cam.useFramingBehavior = false;      // framing fights manual camera state
cam.zoomToMouseLocation = true;      // §6a
cam.lowerRadiusLimit = 0.1;          // zoom to 0.1 mm detail
cam.upperRadiusLimit = 200;          // zoom out to full assembly
cam.lowerBetaLimit   = 0.01;         // near-top-down, no gimbal lock
cam.upperBetaLimit   = Math.PI - 0.01; // rotate under-chip, no flip
cam.wheelPrecision   = 50;
cam.pinchPrecision   = 200;
cam.panningSensibility = 1000;
cam.minZ = 0.01;                     // never clip 0.1 — eats solder mask
cam.maxZ = 1000;

6c. Orbit-center recentering — Shift+Alt+Click (the massive UX upgrade)

Default ArcRotateCamera orbits around a fixed target. On a small
PCB that's fine. On a large assembly (full board, enclosure, multi-
board system) it's brutal: the user wants to inspect a connector in
the corner, rotates the camera, and the connector swings off-screen
because the orbit center is in the middle of the board. They pan,
lose orientation, pan more, give up.

Professional CAD tools solve this by letting the user re-declare
the orbit center on demand. Fusion 360: middle-click to set pivot.
Onshape: Alt+Click to recenter. Adom uses Shift+Alt+Click —
distinct from any existing Babylon gesture, easy to chord, doesn't
interfere with normal left-drag orbit / right-drag pan / scroll
zoom. After a recenter, the camera tweens its target to the new
point over ~200ms while keeping alpha / beta / radius
identical — the user's viewpoint is preserved, but subsequent
rotations orbit around what they just clicked.

The feature is free on small boards (user never feels the need to
recenter) and transformative on large ones. Always ship it.

Implementation:

import { Animation, CubicEase, EasingFunction, Vector3, Plane } from '@babylonjs/core';

function attachOrbitCenterRecenter(scene, cam, canvas) {
  canvas.addEventListener('pointerdown', (e) => {
    // Shift+Alt+LeftClick only — leaves all other gestures untouched
    if (e.button !== 0 || !e.shiftKey || !e.altKey) return;
    e.preventDefault();

    const pick = scene.pick(scene.pointerX, scene.pointerY);
    let newTarget;

    if (pick.hit && pick.pickedPoint) {
      // Common case: cursor is over a mesh — recenter on the surface point.
      newTarget = pick.pickedPoint.clone();
    } else {
      // Fallback: cursor is over empty space. Project the pick ray onto a
      // sensible fallback plane so the recenter still works.
      //
      // Priority order for the fallback plane:
      //   1) Horizontal plane through the current target (Z = cam.target.z).
      //      Keeps the user near where they were already looking.
      //   2) Ground plane Z=0 (last resort).
      const ray = scene.createPickingRay(scene.pointerX, scene.pointerY,
                                          null, cam);
      for (const planeZ of [cam.target.z, 0]) {
        // Ray-plane intersection with plane Z = planeZ
        const t = (planeZ - ray.origin.z) / ray.direction.z;
        if (t > 0 && t < 10000) {
          newTarget = ray.origin.add(ray.direction.scale(t));
          break;
        }
      }
      if (!newTarget) return; // ray is parallel to both planes — bail
    }

    // Tween cam.target over 200ms. alpha/beta/radius stay identical,
    // so the user's viewpoint is preserved — only the pivot moves.
    const ease = new CubicEase();
    ease.setEasingMode(EasingFunction.EASINGMODE_EASEINOUT);
    Animation.CreateAndStartAnimation(
      'orbitRecenter', cam, 'target',
      60,            // fps
      12,            // 12 frames @ 60fps = 200ms
      cam.target.clone(), newTarget,
      Animation.ANIMATIONLOOPMODE_CONSTANT,
      ease
    );
  });
}

UX polish bits that matter:

• Show the teal pivot sphere during EVERY left-drag rotate, not
  just after a recenter. This is the single most important part
  of making Shift+Alt+Click discoverable. The instant the user
  starts left-dragging, a small teal sphere (#00b8b0, ~1% of
  scene extent, semi-transparent α≈0.7) appears at cam.target.
  Fades out ~400 ms after pointer-up. Over time — after the user
  has seen the sphere appear-during-drag dozens of times — they
  form an unshakeable mental link: teal sphere = rotation center.
  Once that association is built, they intuitively understand what
  Shift+Alt+Click does the first time they try it: "oh, that chord
  moves the teal sphere." Without this persistent visual training,
  Shift+Alt+Click is a hidden power-user gesture nobody ever finds,
  and users get frustrated ("why does this thing keep swinging
  off-screen when I rotate?"). Not showing the sphere during
  drag-rotate is working against the user's training.

  // Pseudocode wiring — attach to the same canvas as §6c
  let pivotSphere = null;
  function showPivot() {
    if (!pivotSphere) {
      pivotSphere = MeshBuilder.CreateSphere('pivot',
        { diameter: sceneExtent * 0.01 }, scene);
      const m = new StandardMaterial('pivotMat', scene);
      m.emissiveColor = Color3.FromHexString('#00b8b0');
      m.alpha = 0.7;
      m.disableLighting = true;
      pivotSphere.material = m;
      pivotSphere.isPickable = false;
      pivotSphere.renderingGroupId = 2; // draw on top
    }
    pivotSphere.position.copyFrom(cam.target);
    pivotSphere.setEnabled(true);
  }
  function hidePivot(delayMs = 400) {
    setTimeout(() => pivotSphere && pivotSphere.setEnabled(false), delayMs);
  }
  canvas.addEventListener('pointerdown', e => {
    if (e.button === 0 && !e.shiftKey && !e.altKey) showPivot();
  });
  canvas.addEventListener('pointerup', () => hidePivot(400));
  // Also update pivotSphere.position each frame while rotating so it
  // tracks cam.target exactly (Babylon: scene.onBeforeRenderObservable).
  

• Use the SAME teal sphere for the Shift+Alt+Click recenter
  flash. Don't introduce a different marker — it's the same
  object, just lingering ~600 ms after the recenter tween completes
  instead of the 400 ms fade used during drag. Consistent visual
  language: one sphere, one meaning. The recenter gesture literally
  looks like "move the teal sphere to here," which is exactly the
  mental model we want.

• Sphere size scales with scene extent. sceneExtent * 0.01
  keeps it readable without dominating — on a 30 mm PCB that's a
  0.3 mm dot, on a 200 mm assembly that's a 2 mm dot.

• Keep the keybind discoverable. Toolbar tooltip on the
  orbit/rotate button: "Left-drag to orbit (teal sphere shows the
  rotation center). Shift+Alt+Click to move the rotation center to
  what you clicked."

• Do not recenter on empty space without a fallback plane. If
  the ray doesn't hit anything AND the fallback planes don't
  intersect (ray parallel to Z), just silently do nothing — do not
  teleport the target to Vector3.Zero() or some default, that's
  more disorienting than not recentering.

• Keep normal orbit untouched. Left-drag without the chord still
  orbits around the current (possibly recentered) target. Users
  learn the chord; they don't have to use it.

Ship this in the canonical viewer first (§2b), delete it from any
downstream workaround.

6d. Defaults

• Initial view: isometric (alpha: π/4, beta: π/3 on Z-up) — see
  §8f for why this specific sign on alpha (operator-side octant).
• Initial radius: bounding sphere × 1.3. Model fills ~70% of
  viewport.
• FOV: 35–40°.

---

6e. The DIY trap — "I'll just build my own viewer" costs more than it saves

This is for you, Claude. Future you. Me. Every time this skill gets
updated it's because someone re-implemented the canonical viewer from
scratch and then had to be told — feature by painful feature — about
every rule in this document. Gradient background. Bottom-light toggle.
Zoom-to-mouse. Shift+Alt+Click recenter. Pivot sphere during drag.
Axis helpers. Depth-testing on those helpers. Corner triad with labels.
The Adom/CNC coordinate convention (§8f). View-preset alpha/beta
table. None of it is obvious up-front. All of it already exists —
correct, tested, consistent — in gallia/viewer/.

The rationalization Claude will make: "the canonical viewer is heavy
and my app's use case is narrow, so copy-pasting Babylon init is
faster." Then the user spends three to five rounds pointing out that
black chips vanish into the background, the chip is on-edge because
the Z-up transform was skipped, the rotation pivot floats above solid
geometry, the Top view is rotated 180° from the CNC convention, and
the iso view looks in from the wrong octant. Each round costs a bump,
a rebuild, a wiki re-publish, and the user's time. The perceived
"savings" from skipping §2 are −10× over the next week.

Rule: if you catch yourself about to write new BABYLON.Scene()
or new BABYLON.Engine() in a new Adom app, stop. Start from
gallia/viewer/ per §2. If the canonical viewer is genuinely missing
the feature you need, take the upstream-first path (§2b) — land the
fix in gallia/viewer/ first, then delete the downstream workaround.
Do not rationalize a parallel implementation because it feels quicker.

Documented 2026-04-24 after step2glb's preview viewer hit every single
one of the above pitfalls one by one through four point releases.

---

7. ViewCube / view presets

The canonical viewer ships a ViewCube-style panel: clickable faces
for front / back / left / right / top / bottom, plus a dedicated
isometric button. Clicking a face tweens the camera to the preset
alpha / beta over ~300 ms with a cubic ease. See
gallia/viewer/viewer/3d.html for the reference implementation and
the basic-3d-viewer skill for the full Z-up preset angle table.

Rules for ViewCube in any new Adom viewer:

• Reuse the canonical viewer's ViewCube. Don't redraw one in your
  app. Embed the viewer, or if you must roll your own, use identical
  preset angles so view memory transfers between apps.
• Always include "isometric" as a separate button — users expect
  it next to the six orthogonal faces, not buried in a menu.
• Tween, don't snap. 300 ms cubic-ease tween between presets. A
  hard snap disorients users who briefly lose track of which way is
  up.
• Respect the current orbit center. ViewCube sets alpha/beta
  only — leave cam.target alone. The user's recentered pivot from
  §6c should survive a view-preset click.
• Monochrome icon for the ViewCube button, per the brand skill's
  icon rule. Active face highlighted in teal #00b8b0.

---

8. Axis helpers — always show where the origin is (non-negotiable)

Origins are where every Adom 3D integration bug hides. A chip's GLB
was exported with origin at its centroid, but the footprint's origin
is at pad-1. A Fusion 360 export used Y-up, a KiCad export used
Z-up, and the chip lands sideways. A molecule's 3D model baked the
origin 3.2 mm above the board surface, and now nothing stacks
correctly. Without a visible origin, neither the user nor the AI
can spot the misalignment — you just see parts floating in the
wrong place, with no way to tell whether the chip is wrong, the
footprint is wrong, or the Z-up transform skipped a mesh.

Showing where (0, 0, 0) is — and where each loaded mesh's local
origin is — is how you turn a "something's off, I can't tell what"
bug into a "oh the chip's local +Z is pointing sideways" fix in
one glance. This is mandatory in every Adom 3D viewer.

The rule: every Adom 3D viewer ships with a world-origin axis
helper visible by default. It is a toolbar toggle ("Show axes"),
not a hidden feature you only enable when debugging.

8a. World-origin axis helper — default ON

At world origin (0, 0, 0), draw an axis gizmo:

• X axis red, Y axis green, Z axis blue — standard RGB
  convention. Every 3D tool on earth uses R/G/B for X/Y/Z. Do not
  brand-color these (no Adom teal, no purple). Same rationale as
  "don't tint the background teal" (§3a): conventions that let users
  from any CAD/DCC tool instantly read the scene outrank brand
  consistency here.
• Length = 15% of current scene bounding-sphere radius. Scales
  with the model — a fixed length either dominates small scenes
  (chip preview) or disappears in large ones (full assembly).
• Labels X / Y / Z at each tip, billboarded so they always
  face the camera, in #e6edf3 (primary text color).
• Position: world (0, 0, 0). Even after a Shift+Alt+Click recenter
  (§6c), the helper stays at world origin — that is the whole point.

Babylon implementation:

import { AxesViewer } from '@babylonjs/core';

function addWorldAxesHelper(scene, sceneExtent) {
  const axes = new AxesViewer(scene, sceneExtent * 0.15);
  // AxesViewer positions at (0,0,0) world by default and uses R/G/B.
  scene.__worldAxes = axes;
  return axes;
}

function toggleWorldAxes(scene, visible) {
  const axes = scene.__worldAxes;
  if (!axes) return;
  [axes.xAxis, axes.yAxis, axes.zAxis].forEach(m => m.setEnabled(visible));
}

8b. Mesh-local axis helpers — toggleable, default OFF

For every loaded GLB root (a chip, a footprint, a molecule, a
sub-assembly), the user needs a way to reveal that mesh's local
origin on demand. Nine out of ten misalignment bugs come from the
local origin not being where anyone thought it was — centroid vs
pad-1, top-of-body vs seat-plane, bounding-box-corner vs ref-des
anchor.

Toolbar button: "Show mesh origins". When on, each loaded root
mesh gets a smaller axis helper parented to it, so the helper moves
and rotates with the mesh:

function addMeshOriginAxes(rootMesh, scene) {
  const r = rootMesh.getBoundingInfo().boundingSphere.radius;
  const axes = new AxesViewer(scene, r * 0.4);
  // Parent so the helper follows the mesh — shows the LOCAL origin.
  [axes.xAxis, axes.yAxis, axes.zAxis].forEach(m => m.parent = rootMesh);
  rootMesh.__localAxes = axes;
  return axes;
}

This is when the bugs become obvious. User toggles "Show mesh
origins", sees a chip's local +Z pointing sideways → Y-up→Z-up
conversion got skipped on that loader path (§11). Sees a footprint's
origin sitting at the bounding-box corner instead of pad 1 → bad
export from the library tool. Sees a chip hovering 3.2 mm above the
board because its local origin is at the seat plane of the
package body instead of the bottom of the pins → wrong convention
from the CAD author. None of these are obvious without the helper,
and all of them look identical ("chip is just floating wrong")
without it.

8c. Screen-space corner triad — always on

Fusion 360, Blender, SolidWorks, Onshape, and every serious DCC tool
pin a small three-axis widget in a screen corner that rotates with
the camera but stays fixed to the viewport, so the user always knows
which way is up regardless of orbit state. It complements §8a — the
world helper shows where origin is in scene space, the corner
triad shows where the axes point in screen space.

Implement via a Babylon UtilityLayerRenderer with a secondary
ArcRotateCamera that mirrors the main camera's alpha and beta
(but uses a fixed radius). Pin the layer's viewport to the
bottom-left ~8% of the screen. Label X / Y / Z, same R/G/B
colors as §8a. No scene-space position — it lives in overlay space.
Lightweight, never interferes with interaction, saves constant
"which way is up?" moments. Default ON, no toggle.

8d. Why this is mandatory, not a "nice to have"

• Y-up vs Z-up conflicts. World-origin helper immediately shows
  which axis is "up" so the user can verify the Z-up transform (§11)
  landed. A mis-rotated board looks identical to a correctly-rotated
  one in isolation — until you stack something on it.
• Chip origins vary wildly. STEP exports from Fusion 360 often
  put origin at centroid; KiCad's .kicad_mod origin is at pin 1;
  tscircuit bakes at different points depending on footprint.
  Mesh-local helpers make the difference visible on load.
• Footprint origins vary too. Some libraries anchor at pad 1,
  some at bbox centroid, some at a ref-des anchor. When a chip's
  3D model doesn't line up with its footprint pads, first check
  the two origins — and you can only check them if they're drawn.
• AI-assisted debugging only works when the user can describe
  what they see. "Something's off" is unhelpful; "the chip's local
  +Z arrow is pointing toward me instead of up" is a sentence the
  AI can act on. Axis helpers turn vague misalignment into
  describable geometry.
• This is a free upgrade. Showing the origin costs nothing — no
  perf impact, no visual clutter at 15% of scene extent, toggleable
  if it ever does get in the way. No downside, massive debugging
  upside. Default ON.

8e. Keybinds + AI-drivability

• Keyboard: A toggles world axes. Shift+A toggles mesh-local
  axes. Corner triad stays on (no toggle needed).
• window.Adom3DViewer.toggleAxes(target, enabled) where target
  is 'world' | 'mesh-local' | 'corner-triad'.
• postMessage: { type: 'toggle_axes', target, enabled } (see §10b).
• Toolbar tooltip on "Show axes": "Always show the world origin.
  Useful when debugging alignment of chips, footprints, and
  molecules whose local origins may differ."

8f. Adom/CNC coordinate convention + view-preset angle table

Adom is a CNC-forward ecosystem. The coordinate convention is fixed,
is not optional, and every Adom 3D viewer follows it. The reason this
has its own section: view-preset math is tied to the convention, and
anyone picking preset angles without this in front of them will get
Top or Iso rotated by 90° or 180° and waste the user's time.

The convention:

Axis	Direction	Mnemonic
+X	East (operator's right as they face the machine)	"X goes to your right hand"
+Y	North (away from the operator, toward the back of the machine)	"Y goes away"
+Z	Up (out of the table surface, toward the ceiling)	"Z is up"

The operator stands at -Y and faces +Y. Every view preset below is
derived from that mental model:

Preset	Camera position	Screen-right	Screen-up	Mental model
Top	(0, 0, +r)	+X	+Y	Looking straight down at the machine bed
Bottom	(0, 0, -r)	+X	-Y	Looking up through the bed (mirror of Top)
Front	(0, -r, 0)	+X	+Z	Operator's natural view — walking up to the machine
Back	(0, +r, 0)	-X	+Z	Looking at the machine from behind
Right	(+r, 0, 0)	-Y	+Z	Standing to the east of the machine
Left	(-r, 0, 0)	+Y	+Z	Standing to the west of the machine
Iso (home)	(+r, -r, +r) (operator-side, above)	—	—	Operator's 3/4 view from their own side of the machine

Babylon alpha/beta that produce those positions — for
ArcRotateCamera with upVector = (0, 0, 1):

position.x = target.x + r * sin(β) * cos(α)
position.y = target.y - r * sin(β) * sin(α)     // ← note the MINUS
position.z = target.z + r * cos(β)

The sign on alpha is reversed vs standard spherical coordinates. A
confident-looking -Math.PI/2 will actually put the camera at +Y,
not -Y. Every new viewer's first-attempt preset table gets at least
one preset rotated 180° because of this. Verify every preset you
compute with a console.log(cam.position.asArray()) before shipping.

The canonical preset table (Z-up, right-handed Babylon with the alpha
convention above):

const VIEW_PRESETS = {
  top:    { alpha:  Math.PI / 2, beta: 0.01           },
  bottom: { alpha:  Math.PI / 2, beta: Math.PI - 0.01 },
  front:  { alpha:  Math.PI / 2, beta: Math.PI / 2    },
  back:   { alpha: -Math.PI / 2, beta: Math.PI / 2    },
  right:  { alpha:  0,           beta: Math.PI / 2    },
  left:   { alpha: -Math.PI,     beta: Math.PI / 2    },
  iso:    { alpha:  Math.PI / 4, beta: Math.PI / 3    },
};

Iso home view gotcha. The "obvious" iso angle — alpha: -π/4 —
lands the camera in the (+X, +Y, +Z) octant, which is behind the
operator. That's Blender's / VRay's / Maya's default iso, but it's
wrong for CNC. The correct Adom iso is alpha: +π/4, which puts the
camera in (+X, -Y, +Z) — on the operator's own side of the machine.

Acceptance test. Snap to Top, eyeball the corner triad (§8c):

• Y label MUST be at the top of the triad.
• X label MUST be on the right.
• Z MUST be the dot at the center (coming toward the viewer).

If any of the three is wrong, your preset table is wrong. Do not ship.

8g. Why this convention is non-negotiable

CAD/DCC tools outside CNC use wildly inconsistent conventions — Blender
is Z-up but its default iso looks from the back; Maya is Y-up with Y
pointing out of the monitor; SolidWorks is Y-up; Fusion 360 lets each
user pick. Adom standardizes on CNC-operator conventions specifically
so every tool in the ecosystem — chipfit, adom-tsci, basic-3d-viewer,
InstaPCB preview, step2glb, and any future 3D surface — matches the
physical machine the user will actually be operating. A board seen in
step2glb's Top view is the same orientation the user will see when
they put that board on the CNC bed. A component seen in chipfit's Iso
view shows pin 1 in the same corner as when the operator approaches
the machine from the front. Consistency across viewers is how a board
goes from the screen to the bed without the user mentally rotating
anything. Break the convention in your viewer and every downstream
user has to re-learn your orientation.

This section exists because someone will be tempted to use Blender's
default iso "because it shows more of the model." Don't. Pick a
different default camera distance or angle elevation if you want more
material visible; keep the alpha in the operator-side octant.

---

9. Measurement / picking helpers

9a. Snap to vertex, not to ray-hit

function snapToVertex(pickResult) {
  const mesh = pickResult.pickedMesh;
  let worldVerts = measureVertexCache.get(mesh.uniqueId);
  if (!worldVerts) {
    const local = mesh.getVerticesData(VertexBuffer.PositionKind);
    const m = mesh.getWorldMatrix();
    worldVerts = [];
    for (let i = 0; i < local.length; i += 3) {
      worldVerts.push(Vector3.TransformCoordinates(
        new Vector3(local[i], local[i+1], local[i+2]), m));
    }
    measureVertexCache.set(mesh.uniqueId, worldVerts);
  }
  return worldVerts.reduce((best, v) =>
    Vector3.DistanceSquared(v, pickResult.pickedPoint) <
    Vector3.DistanceSquared(best, pickResult.pickedPoint) ? v : best);
}

9b. Auto-scale markers to scene extent

const size = Math.max(Math.min(sceneExtent * 0.03, 0.001), 0.0003);
// 3% of scene diagonal, clamped to 0.3–1 mm

---

10. AI-drivability — every 3D viewer is AI-controllable

10a. Window-global API

window.Adom3DViewer = {
  init, setCamera, setBottomLight, recenterOrbit, tweakScene,
  measure, snapToVertex, dumpMeshes, testPbr,
  BABYLON: { Vector3, Color3, StandardMaterial, PBRMaterial, ... }
};

10b. postMessage protocol

window.addEventListener('message', (e) => {
  const { type } = e.data;
  if (type === 'set_camera')       { /* { alpha, beta, radius, targetX/Y/Z } */ }
  if (type === 'set_bottom_light') { /* { enabled } */ }
  if (type === 'recenter_orbit')   { /* { x, y, z } — same tween as §6c */ }
  if (type === 'view_preset')      { /* { preset: 'iso'|'front'|... } */ }
  if (type === 'toggle_axes')      { /* { target: 'world'|'mesh-local'|'corner-triad', enabled } — see §8 */ }
  if (type === 'tweak_scene')      { /* { envIntensity, hemiIntensity } */ }
  if (type === 'measure')          { /* { pointA, pointB } */ }
});

10c. Console forwarding

Forward console.log/warn/error via postMessage so Claude can read
scene-state from CLI without opening devtools.

Rule

Every toolbar button + every keyboard shortcut must have a
corresponding entry in at least one of these three channels.
Shift+Alt+Click (§6c)? There's a recenter_orbit message. ViewCube
face click (§7)? There's a view_preset message. Every UI affordance
round-trips through an AI-drivable surface.

---

11. Y-up → Z-up coordinate handling

The Adom ecosystem is Z-up. GLB spec is Y-up. The canonical viewer's
applyGlbZUpTransform(viewer, glbSource) handles this on every
loader path. See the basic-3d-viewer skill for the recipe.

---

12. Presets & escape hatches

Preset	Top	Bottom	When to use
Studio (default)	#5a6b7e	#2a3340	99% of use cases
Dark flat	#0d1117	#0d1117	Dark-bg docs screenshots
Light flat	#e6edf3	#e6edf3	Print, light-theme exports

Persisted per app; never force-reset on reload.

---

13. Babylon snippet — full viewport defaults

import { Scene, Color3, Color4, Vector3, CubeTexture,
         HemisphericLight } from '@babylonjs/core';

export function applyAdomViewportDefaults(scene, engine) {
  // Background — transparent clearColor, CSS gradient on canvas parent
  scene.clearColor = new Color4(0x0d/255, 0x11/255, 0x17/255, 0);
  engine.getRenderingCanvas().parentElement.style.background =
    'linear-gradient(180deg, #5a6b7e 0%, #2a3340 80%)';

  // Lighting — HDRI + hemispheric (§4a)
  scene.environmentTexture = CubeTexture.CreateFromPrefilteredData(
    '/js/environmentSpecular.env', scene);
  scene.environmentIntensity = 0.8;

  const hemi = new HemisphericLight('hemi', new Vector3(0, 1, 0), scene);
  hemi.intensity = 0.6;
  hemi.diffuse     = Color3.FromHexString('#e6edf3');
  hemi.groundColor = new Color3(0.2, 0.18, 0.15);

  return { hemi }; // wire to setBottomLight (§4b)
}

export function applyAdomCameraDefaults(cam, scene, canvas) {
  // Strip behaviors first (§6b)
  while (cam.behaviors && cam.behaviors.length > 0)
    cam.removeBehavior(cam.behaviors[0]);
  cam.useFramingBehavior = false;

  cam.zoomToMouseLocation = true;          // §6a
  cam.lowerRadiusLimit = 0.1;
  cam.upperRadiusLimit = 200;
  cam.lowerBetaLimit   = 0.01;
  cam.upperBetaLimit   = Math.PI - 0.01;
  cam.wheelPrecision   = 50;
  cam.pinchPrecision   = 200;
  cam.panningSensibility = 1000;
  cam.minZ = 0.01;
  cam.maxZ = 1000;

  attachOrbitCenterRecenter(scene, cam, canvas); // §6c — Shift+Alt+Click
}

CSS fallback for the gradient:

.viewer-3d-canvas-wrapper {
  background: linear-gradient(180deg, #5a6b7e 0%, #2a3340 80%);
}
.viewer-3d-canvas-wrapper canvas { background: transparent; }

---

14. Pitfalls checklist

• Engine is Babylon.js. No import * as THREE from 'three'.
• Starts from the canonical Adom Babylon viewer at
  gallia/viewer/, not from a blank Babylon scene.
• New best-practices were added to the canonical viewer first
  (§2b), not as downstream hacks.
• Background is vertical gradient #5a6b7e → #2a3340 (v1.3
  field-fix pass — both ends brightened after v1.1's "brighten
  only the top" still lost black chips in the lower half), not
  pure black / white / brand-colored / v1.1's #3e4a5c → #0d1117
  / v1.0's #21262d → #0d1117.
• Black, white, AND chrome models all clearly visible in the
  default view (test all three — this is THE acceptance test).
• HDRI environment loaded; bottom-light toggle in toolbar for
  any PCB viewer.
• Default material class for any new material is PBRMaterial,
  not StandardMaterial — HDRI lighting depends on it (§5a).
• World-origin axis helper visible by default (R/G/B X/Y/Z,
  15% of scene extent, §8a). Toolbar toggle "Show axes" present.
• Mesh-local axis toggle ("Show mesh origins") present (§8b).
• Screen-space corner triad pinned bottom-left, always on (§8c).
• cam.zoomToMouseLocation = true is set.
• Teal pivot sphere visible during EVERY left-drag rotate
  (§6c), not just after recenter. Same sphere used for the
  Shift+Alt+Click recenter flash (consistent visual language).
• Shift+Alt+Click orbit-center recentering wired up, with
  surface-projection fallback + brief teal pivot-marker flash.
• ViewCube / view presets reuse the canonical viewer's
  component and tween (not snap) between presets.
• Camera behaviors stripped before limits applied; soft limits
  set; zoom / pinch / pan precision tuned.
• Incoming GLB materials detected (PBR vs Standard). Standard
  converted to PBR on load (§5b). Env BRDF texture attached to
  every PBR material.
• No hard grid by default. Soft shadow catcher under the model.
• Default camera fills ~70% of viewport with the model.
• Studio / Dark flat / Light flat bg presets in toolbar,
  persisted per-app.
• AI-drivability: every toolbar button + every keyboard chord
  (Shift+Alt+Click, every ViewCube face, every axis toggle, A
  and Shift+A shortcuts) reachable via window.* API,
  postMessage, or console-forwarded command.
• Screenshot the viewer with a black chip, a white chip, and a
  chrome chip side-by-side. All three read cleanly? If any
  disappears against the background, §3b is regressed — bump
  the top gradient color, do not work around it.

---

15. Why this skill exists — frozen in time

Came up 2026-04-24 while discussing viewer UX. The observation:
Claude makes many ad-hoc 3D viewers, each re-inventing the
background, lighting, camera setup, and — worst — whether to use
Babylon or Three. Without a shared rule, some ship with pure black
(dark parts invisible), some with brand-teal backgrounds (every
material tinted), most default to Three (fighting the canonical
viewer's Babylon ecosystem), almost none set zoomToMouseLocation,
and zero ship Fusion/Onshape-style orbit-center recentering. This
skill consolidates the "one right answer" — Babylon, start from the
canonical viewer, gradient bg, HDRI + hemispheric, bottom-light
toggle, zoom-to-mouse, Shift+Alt+Click recenter, ViewCube reuse,
soft camera limits, vertex snapping, PBR fixups, AI-drivability —
so every new viewer starts on-brand, engineer-friendly, and
consistent with the canonical viewer's DNA.

Changelog

• 1.3.0 (2026-04-24) — Second-pass gradient fix + absorbed
  upstream learnings from step2glb's preview viewer.
  • Brightened both ends of the gradient. Top #3e4a5c →
    #5a6b7e, bottom #0d1117 → #2a3340. v1.1 had only
    brightened the top on the assumption that black chips sit in
    the upper half; field test with a TQFP64 showed the chip body
    lands in the lower half at default framing, where the
    near-black v1.1 bottom made it invisible again. Fix: bring
    both ends into the "dark theme but not near-black" band.
    Trade-off: we lose perfect --bg chrome-continuity; visibility
    wins. §3b now carries the non-negotiable acceptance test:
    "load a black TQFP64, orbit, verify visibility at every
    vertical position."
  • Landed §6e "The DIY trap" (from the step2glb thread) —
    direct Claude-to-Claude warning about re-implementing the
    canonical viewer from scratch, with real incident evidence.
  • Landed §8f + §8g (from the step2glb thread) — the
    Adom/CNC coordinate convention (operator at -Y facing +Y) and
    the canonical alpha/beta view-preset table, with the
    sign-reversal gotcha (cam.position.y = target.y - r*sin(β)*sin(α)
    — the MINUS sign puts the Back view at -Math.PI/2, not the
    obvious +Math.PI/2). Plus the "obvious iso" warning
    (Blender/Maya's default -π/4 puts the camera behind the
    operator — wrong for CNC).
• 1.2.0 (2026-04-24) — Added §2e–§2i 5-tier layering decision
  matrix. "Extend, don't fork" was the rule since v1.0 but had no
  guidance on how to extend in practice — Claudes consistently
  asked "what does layering look like tier-by-tier?" The new section
  covers Tier 1 pure embed (default, 90%+ of apps), Tier 2 MCP call,
  Tier 3 Basic3dView import (canvas in your own DOM), Tier 4
  extension hooks upstream, Tier 5 roll-your-own (last resort, still
  Babylon + still inheriting helpers). Plus a three-question
  decision flow, signal lists for "don't roll your own" vs
  "legitimate reasons to roll your own," and the one-liner: "Embed
  if you can, import if you must, roll if you're sure."
• 1.1.0 (2026-04-24) — Field feedback from the first shipped
  viewer using this skill forced two fixes and two additions:
  • Brighter background top (#3e4a5c instead of #21262d) —
    black IC bodies were still invisible against the old near-black
    top. §3b.
  • Explicit PBR-default rule (§5a) — the prior version implied
    PBR but didn't call it out as the mandatory default material
    class. Shipped viewers were creating StandardMaterial by habit,
    breaking HDRI lighting on chrome / gold / anodized parts.
  • Axis helpers (§8) — entire new section. World-origin helper
    default-on, mesh-local helpers toggleable, screen-space corner
    triad always on. Rationale: origins are where every Adom 3D
    integration bug hides (chip vs footprint, Y-up vs Z-up, centroid
    vs pad-1), and the user + AI can only debug misalignment if
    they can see where each origin actually lives.
  • Pivot sphere during every drag-rotate (§6c) — the teal
    sphere now appears the instant the user starts left-dragging,
    not just after a Shift+Alt+Click recenter. Trains the user to
    associate the teal sphere with "rotation center," which makes
    Shift+Alt+Click intuitively discoverable instead of a hidden
    gesture nobody finds.
• 1.0.0 (2026-04-24) — Initial publish.

When rules here are wrong — they will be, eventually — update this
file AND land the fix upstream in gallia/viewer/. Every 3D viewer
reads from here.