# 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) ```js 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: ```js 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: ```js 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 ```js 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:** ```js 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.* ```js // 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 ```js 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 ```js 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 ```js 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: ```css .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.