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.

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.

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.

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°.

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.

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

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.

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; }

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.