@project-skymap/library 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import * as THREE4 from 'three';
+import * as THREE5 from 'three';
 import { forwardRef, useRef, useImperativeHandle, useEffect } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
@@ -129,14 +129,14 @@ var init_constellations = __esm({
 });
 function lookAt(point, target, up) {
   const zAxis = target.clone().normalize();
-  let xAxis = new THREE4.Vector3().crossVectors(up, zAxis);
+  let xAxis = new THREE5.Vector3().crossVectors(up, zAxis);
   if (xAxis.lengthSq() < 1e-4) {
-    xAxis = new THREE4.Vector3().crossVectors(new THREE4.Vector3(1, 0, 0), zAxis);
+    xAxis = new THREE5.Vector3().crossVectors(new THREE5.Vector3(1, 0, 0), zAxis);
   }
   xAxis.normalize();
-  const yAxis = new THREE4.Vector3().crossVectors(zAxis, xAxis).normalize();
-  const m = new THREE4.Matrix4().makeBasis(xAxis, yAxis, zAxis);
-  const v = new THREE4.Vector3(point.x, point.y, point.z);
+  const yAxis = new THREE5.Vector3().crossVectors(zAxis, xAxis).normalize();
+  const m = new THREE5.Matrix4().makeBasis(xAxis, yAxis, zAxis);
+  const v = new THREE5.Vector3(point.x, point.y, point.z);
   v.applyMatrix4(m);
   v.add(target);
   return { x: v.x, y: v.y, z: v.z };
@@ -217,7 +217,7 @@ function computeLayoutPositions(model, layout) {
           const radiusAtY = Math.sqrt(1 - y * y);
           const x = Math.cos(midAngle) * radiusAtY;
           const z = Math.sin(midAngle) * radiusAtY;
-          const labelPos = new THREE4.Vector3(x, y, z).multiplyScalar(radius);
+          const labelPos = new THREE5.Vector3(x, y, z).multiplyScalar(radius);
           uDivision.meta.x = labelPos.x;
           uDivision.meta.y = labelPos.y;
           uDivision.meta.z = labelPos.z;
@@ -233,7 +233,7 @@ function computeLayoutPositions(model, layout) {
           const theta = startAngle + t * angleSpan;
           const x = Math.cos(theta) * radiusAtY;
           const z = Math.sin(theta) * radiusAtY;
-          const bookPos = new THREE4.Vector3(x, y, z).multiplyScalar(radius);
+          const bookPos = new THREE5.Vector3(x, y, z).multiplyScalar(radius);
           const labelPos = bookPos.clone();
           labelPos.y += radius * 0.025;
           labelPos.setLength(radius);
@@ -244,7 +244,7 @@ function computeLayoutPositions(model, layout) {
           if (chapters.length > 0) {
             const territoryRadius = radius * 2 / Math.sqrt(books.length * 2) * 0.7;
             const localPoints = getConstellationLayout(bookKey, chapters.length, territoryRadius);
-            const up = new THREE4.Vector3(0, 1, 0);
+            const up = new THREE5.Vector3(0, 1, 0);
             chapters.forEach((chap, idx) => {
               const uChap = updatedNodeMap.get(chap.id);
               const lp = localPoints[idx];
@@ -263,10 +263,10 @@ function computeLayoutPositions(model, layout) {
     testaments.forEach((t) => {
       const children = childrenMap.get(t.id) ?? [];
       if (children.length === 0) return;
-      const centroid = new THREE4.Vector3();
+      const centroid = new THREE5.Vector3();
       children.forEach((c) => {
         const u = updatedNodeMap.get(c.id);
-        centroid.add(new THREE4.Vector3(u.meta.x, u.meta.y, u.meta.z));
+        centroid.add(new THREE5.Vector3(u.meta.x, u.meta.y, u.meta.z));
       });
       centroid.divideScalar(children.length);
       if (centroid.length() > 0.1) {
@@ -330,11 +330,18 @@ vec4 smartProject(vec4 viewPos) {
     vec2 projected = vec2(k * dir.x, k * dir.y);
     projected *= uScale;
     projected.x /= uAspect;
-    float zMetric = -1.0 + (dist / 2000.0);
+    float zMetric = -1.0 + (dist / 15000.0);
+    
+    // Radial Clipping: Push clipped points off-screen in their natural direction
+    // to prevent lines "darting" across the center.
+    vec2 escapeDir = (length(dir.xy) > 0.0001) ? normalize(dir.xy) : vec2(1.0, 1.0);
+    vec2 escapePos = escapeDir * 10000.0;
+
     // Clip backward facing points in fisheye mode
-    if (uBlend > 0.5 && dir.z > 0.4) return vec4(10.0, 10.0, 10.0, 1.0);
+    if (uBlend > 0.5 && dir.z > 0.4) return vec4(escapePos, 10.0, 1.0);
     // Clip very close points in linear mode
-    if (uBlend < 0.1 && dir.z > -0.1) return vec4(10.0, 10.0, 10.0, 1.0);
+    if (uBlend < 0.1 && dir.z > -0.1) return vec4(escapePos, 10.0, 1.0);
+    
     return vec4(projected, zMetric, 1.0);
 }
 `;
@@ -357,7 +364,7 @@ float getMaskAlpha() {
 });
 function createSmartMaterial(params) {
   const uniforms = { ...globalUniforms, ...params.uniforms };
-  return new THREE4.ShaderMaterial({
+  return new THREE5.ShaderMaterial({
     uniforms,
     vertexShader: `
             ${BLEND_CHUNK} 
@@ -371,8 +378,8 @@ function createSmartMaterial(params) {
     transparent: params.transparent || false,
     depthWrite: params.depthWrite !== void 0 ? params.depthWrite : true,
     depthTest: params.depthTest !== void 0 ? params.depthTest : true,
-    side: params.side || THREE4.FrontSide,
-    blending: params.blending || THREE4.NormalBlending
+    side: params.side || THREE5.FrontSide,
+    blending: params.blending || THREE5.NormalBlending
   });
 }
 var globalUniforms;
@@ -382,7 +389,248 @@ var init_materials = __esm({
     globalUniforms = {
       uScale: { value: 1 },
       uAspect: { value: 1 },
-      uBlend: { value: 0 }
+      uBlend: { value: 0 },
+      uTime: { value: 0 },
+      // Atmosphere Settings
+      uAtmGlow: { value: 1 },
+      uAtmDark: { value: 0.6 },
+      uAtmExtinction: { value: 4 },
+      uAtmTwinkle: { value: 0.8 },
+      uColorHorizon: { value: new THREE5.Color(2768476) },
+      uColorZenith: { value: new THREE5.Color(132104) }
+    };
+  }
+});
+var ConstellationArtworkLayer;
+var init_ConstellationArtworkLayer = __esm({
+  "src/engine/ConstellationArtworkLayer.ts"() {
+    init_materials();
+    ConstellationArtworkLayer = class {
+      root;
+      items = [];
+      textureLoader = new THREE5.TextureLoader();
+      hoveredId = null;
+      focusedId = null;
+      constructor(root) {
+        this.root = new THREE5.Group();
+        this.root.renderOrder = -1;
+        root.add(this.root);
+      }
+      getItems() {
+        return this.items;
+      }
+      setPosition(id, pos) {
+        const item = this.items.find((i) => i.config.id === id);
+        if (item) {
+          item.mesh.position.copy(pos);
+        }
+      }
+      load(config, getPosition) {
+        this.clear();
+        const basePath = config.atlasBasePath.replace(/\/$/, "");
+        config.constellations.forEach((c) => {
+          let center = new THREE5.Vector3();
+          let valid = false;
+          let radius = 2e3;
+          const arrPos = getPosition(c.id);
+          if (arrPos) {
+            center.copy(arrPos);
+            valid = true;
+            if (c.anchors.length > 0) {
+              const points = [];
+              for (const anchorId of c.anchors) {
+                const p = getPosition(anchorId);
+                if (p) points.push(p);
+              }
+              if (points.length > 0) {
+                radius = points[0].length();
+              }
+            }
+          } else if (c.center) {
+            center.set(c.center[0], c.center[1], c.center[2]);
+            valid = true;
+          } else if (c.anchors.length > 0) {
+            const points = [];
+            for (const anchorId of c.anchors) {
+              const p = getPosition(anchorId);
+              if (p) points.push(p);
+            }
+            if (points.length > 0) {
+              for (const p of points) center.add(p);
+              center.divideScalar(points.length);
+              const len = center.length();
+              if (len > 1e-3) {
+                radius = points[0].length();
+                center.normalize().multiplyScalar(radius);
+              }
+              valid = true;
+            }
+          }
+          if (!valid) return;
+          const normal = center.clone().normalize().negate();
+          const upVec = center.clone().normalize();
+          let right = new THREE5.Vector3(1, 0, 0);
+          if (c.anchors.length >= 2) {
+            const p0 = getPosition(c.anchors[0]);
+            const p1 = getPosition(c.anchors[1]);
+            if (p0 && p1) {
+              const diff = new THREE5.Vector3().subVectors(p1, p0);
+              right.copy(diff).sub(upVec.clone().multiplyScalar(diff.dot(upVec))).normalize();
+            }
+          } else {
+            if (Math.abs(upVec.y) > 0.9) right.set(1, 0, 0).cross(upVec).normalize();
+            else right.set(0, 1, 0).cross(upVec).normalize();
+          }
+          const top = new THREE5.Vector3().crossVectors(upVec, right).normalize();
+          right.crossVectors(top, upVec).normalize();
+          new THREE5.Matrix4().makeBasis(right, top, normal);
+          const geometry = new THREE5.PlaneGeometry(1, 1);
+          let size = c.radius;
+          if (size <= 1) size *= radius;
+          size *= 2;
+          const texPath = `${basePath}/${c.image}`;
+          let blending = THREE5.NormalBlending;
+          if (c.blend === "additive") blending = THREE5.AdditiveBlending;
+          const material = createSmartMaterial({
+            uniforms: {
+              uMap: { value: this.textureLoader.load(texPath) },
+              // Placeholder, updated below
+              uOpacity: { value: c.opacity },
+              uSize: { value: size },
+              uImgRotation: { value: THREE5.MathUtils.degToRad(c.rotationDeg) },
+              uImgAspect: { value: c.aspectRatio ?? 1 }
+              // uScale, uAspect (screen) are injected by createSmartMaterial/globalUniforms
+            },
+            vertexShaderBody: `
+                    uniform float uSize;
+                    uniform float uImgRotation;
+                    uniform float uImgAspect;
+                    
+                    varying vec2 vUv;
+                    
+                    void main() {
+                        vUv = uv;
+                        
+                        // 1. Project Center Point (Proven Method)
+                        vec4 mvCenter = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+                        vec4 clipCenter = smartProject(mvCenter);
+                        
+                        // 2. Project "Up" Point (World Zenith)
+                        // Transform World Up (0,1,0) to View Space
+                        vec3 viewUpDir = mat3(viewMatrix) * vec3(0.0, 1.0, 0.0);
+                        // Offset center by a significant amount (1000.0) to ensure screen delta
+                        vec4 mvUp = mvCenter + vec4(viewUpDir * 1000.0, 0.0);
+                        vec4 clipUp = smartProject(mvUp);
+                        
+                        // 3. Calculate Horizon Angle
+                        vec2 screenCenter = clipCenter.xy / clipCenter.w;
+                        vec2 screenUp = clipUp.xy / clipUp.w;
+                        vec2 screenDelta = screenUp - screenCenter;
+                        
+                        float horizonAngle = 0.0;
+                        if (length(screenDelta) > 0.001) {
+                             vec2 screenDir = normalize(screenDelta);
+                             horizonAngle = atan(screenDir.y, screenDir.x) - 1.5708; // -90 deg
+                        }
+                        
+                        // 4. Combine with User Rotation
+                        float finalAngle = uImgRotation + horizonAngle;
+                        
+                        // 5. Billboard Offset
+                        vec2 offset = position.xy;
+                        
+                        float cr = cos(finalAngle);
+                        float sr = sin(finalAngle);
+                        vec2 rotated = vec2(
+                            offset.x * cr - offset.y * sr,
+                            offset.x * sr + offset.y * cr
+                        );
+                        
+                        rotated.x *= uImgAspect;
+                        
+                        float dist = length(mvCenter.xyz);
+                        float scale = (uSize / dist) * uScale;
+                        
+                        rotated *= scale;
+                        rotated.x /= uAspect;
+                        
+                        gl_Position = clipCenter;
+                        gl_Position.xy += rotated * clipCenter.w;
+                        
+                        vScreenPos = gl_Position.xy / gl_Position.w;
+                    }
+                `,
+            fragmentShader: `
+                    uniform sampler2D uMap;
+                    uniform float uOpacity;
+                    varying vec2 vUv;
+                    void main() {
+                        float mask = getMaskAlpha();
+                        if (mask < 0.01) discard;
+                        vec4 tex = texture2D(uMap, vUv);
+                        gl_FragColor = vec4(tex.rgb, tex.a * uOpacity * mask);
+                    }
+                `,
+            transparent: true,
+            depthWrite: false,
+            depthTest: true,
+            blending,
+            side: THREE5.DoubleSide
+          });
+          material.uniforms.uMap.value = this.textureLoader.load(texPath, (tex) => {
+            if (c.aspectRatio === void 0 && tex.image.width && tex.image.height) {
+              const natAspect = tex.image.width / tex.image.height;
+              material.uniforms.uImgAspect.value = natAspect;
+            }
+          });
+          if (c.zBias) {
+            material.polygonOffset = true;
+            material.polygonOffsetFactor = -c.zBias;
+          }
+          const mesh = new THREE5.Mesh(geometry, material);
+          mesh.frustumCulled = false;
+          mesh.userData = { id: c.id, type: "constellation" };
+          mesh.position.copy(center);
+          this.root.add(mesh);
+          this.items.push({ config: c, mesh, material, baseOpacity: c.opacity });
+        });
+      }
+      update(fov, showArt) {
+        this.root.visible = showArt;
+        if (!showArt) return;
+        for (const item of this.items) {
+          const { fade } = item.config;
+          let opacity = fade.maxOpacity;
+          if (fov >= fade.zoomInStart) {
+            opacity = fade.maxOpacity;
+          } else if (fov <= fade.zoomInEnd) {
+            opacity = fade.minOpacity;
+          } else {
+            const t = (fade.zoomInStart - fov) / (fade.zoomInStart - fade.zoomInEnd);
+            opacity = THREE5.MathUtils.lerp(fade.maxOpacity, fade.minOpacity, t);
+          }
+          opacity = Math.min(Math.max(opacity, 0), 1);
+          item.material.uniforms.uOpacity.value = opacity;
+        }
+      }
+      setHovered(id) {
+        this.hoveredId = id;
+      }
+      setFocused(id) {
+        this.focusedId = id;
+      }
+      dispose() {
+        this.clear();
+        this.root.removeFromParent();
+      }
+      clear() {
+        this.items.forEach((i) => {
+          this.root.remove(i.mesh);
+          i.material.dispose();
+          i.mesh.geometry.dispose();
+        });
+        this.items = [];
+      }
     };
   }
 });
@@ -396,17 +644,37 @@ function createEngine({
   container,
   onSelect,
   onHover,
-  onArrangementChange
+  onArrangementChange,
+  onFovChange
 }) {
-  const renderer = new THREE4.WebGLRenderer({ antialias: true, alpha: false });
+  let hoveredBookId = null;
+  let focusedBookId = null;
+  let orderRevealEnabled = true;
+  let activeBookIndex = -1;
+  let orderRevealStrength = 0;
+  const hoverCooldowns = /* @__PURE__ */ new Map();
+  const COOLDOWN_MS = 2e3;
+  const bookIdToIndex = /* @__PURE__ */ new Map();
+  const renderer = new THREE5.WebGLRenderer({ antialias: true, alpha: false });
   renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
   renderer.setSize(container.clientWidth, container.clientHeight);
   container.appendChild(renderer.domElement);
-  const scene = new THREE4.Scene();
-  scene.background = new THREE4.Color(0);
-  const camera = new THREE4.PerspectiveCamera(60, 1, 0.1, 3e3);
+  const scene = new THREE5.Scene();
+  scene.background = new THREE5.Color(0);
+  const camera = new THREE5.PerspectiveCamera(60, 1, 0.1, 1e4);
   camera.position.set(0, 0, 0);
   camera.up.set(0, 1, 0);
+  function setHoveredBook(id) {
+    if (id === hoveredBookId) return;
+    const now = performance.now();
+    if (hoveredBookId) {
+      hoverCooldowns.set(hoveredBookId, now);
+    }
+    if (id) {
+      hoverCooldowns.get(id) || 0;
+    }
+    hoveredBookId = id;
+  }
   let running = false;
   let raf = 0;
   const state = {
@@ -424,12 +692,15 @@ function createEngine({
     draggedNodeId: null,
     draggedStarIndex: -1,
     draggedDist: 2e3,
-    draggedGroup: null
+    draggedGroup: null,
+    tempArrangement: {}
   };
-  const mouseNDC = new THREE4.Vector2();
+  const mouseNDC = new THREE5.Vector2();
   let isMouseInWindow = false;
-  let handlers = { onSelect, onHover, onArrangementChange };
+  let edgeHoverStart = 0;
+  let handlers = { onSelect, onHover, onArrangementChange, onFovChange };
   let currentConfig;
+  const constellationLayer = new ConstellationArtworkLayer(scene);
   function mix(a, b, t) {
     return a * (1 - t) + b * t;
   }
@@ -464,7 +735,7 @@ function createEngine({
     const phi = Math.atan2(uvY, uvX);
     const sinTheta = Math.sin(theta);
     const cosTheta = Math.cos(theta);
-    return new THREE4.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
+    return new THREE5.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
   }
   function getMouseWorldVector(pixelX, pixelY, width, height) {
     const aspect = width / height;
@@ -483,7 +754,7 @@ function createEngine({
     const phi = Math.atan2(uvY, uvX);
     const sinTheta = Math.sin(theta);
     const cosTheta = Math.cos(theta);
-    const vView = new THREE4.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
+    const vView = new THREE5.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
     return vView.applyQuaternion(camera.quaternion);
   }
   function smartProjectJS(worldPos) {
@@ -496,147 +767,187 @@ function createEngine({
     const k = mix(kLinear, kStereo, blend);
     return { x: k * dir.x, y: k * dir.y, z: dir.z };
   }
-  const groundGroup = new THREE4.Group();
+  const groundGroup = new THREE5.Group();
   scene.add(groundGroup);
   function createGround() {
     groundGroup.clear();
     const radius = 995;
-    const geometry = new THREE4.SphereGeometry(radius, 128, 64, 0, Math.PI * 2, Math.PI / 2, Math.PI / 2);
+    const geometry = new THREE5.SphereGeometry(radius, 128, 64, 0, Math.PI * 2, Math.PI / 2 - 0.15, Math.PI / 2 + 0.15);
     const material = createSmartMaterial({
-      uniforms: { color: { value: new THREE4.Color(526862) } },
-      vertexShaderBody: `varying vec3 vPos; void main() { vPos = position; vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); gl_Position = smartProject(mvPosition); vScreenPos = gl_Position.xy / gl_Position.w; }`,
-      fragmentShader: `uniform vec3 color; varying vec3 vPos; void main() { float alphaMask = getMaskAlpha(); if (alphaMask < 0.01) discard; float noise = sin(vPos.x * 0.2) * sin(vPos.z * 0.2) * 0.05; vec3 col = color + noise; vec3 n = normalize(vPos); float horizon = smoothstep(-0.02, 0.0, n.y); col += vec3(0.1, 0.15, 0.2) * horizon; gl_FragColor = vec4(col, 1.0); }`,
-      side: THREE4.BackSide,
+      uniforms: {
+        color: { value: new THREE5.Color(131587) },
+        // Very dark almost black
+        fogColor: { value: new THREE5.Color(331812) }
+        // Matches atmosphere bot color
+      },
+      vertexShaderBody: `
+                varying vec3 vPos; 
+                varying vec3 vWorldPos;
+                void main() { 
+                    vPos = position; 
+                    vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); 
+                    gl_Position = smartProject(mvPosition); 
+                    vScreenPos = gl_Position.xy / gl_Position.w; 
+                    vWorldPos = (modelMatrix * vec4(position, 1.0)).xyz;
+                }
+            `,
+      fragmentShader: `
+                uniform vec3 color; 
+                uniform vec3 fogColor;
+                varying vec3 vPos; 
+                varying vec3 vWorldPos;
+                
+                void main() { 
+                    float alphaMask = getMaskAlpha(); 
+                    if (alphaMask < 0.01) discard; 
+                    
+                    // Procedural Horizon (Mountains)
+                    float angle = atan(vPos.z, vPos.x);
+                    
+                    // Simple FBM-like terrain
+                    float h = 0.0;
+                    h += sin(angle * 6.0) * 20.0;
+                    h += sin(angle * 13.0 + 1.0) * 10.0;
+                    h += sin(angle * 29.0 + 2.0) * 5.0;
+                    h += sin(angle * 63.0 + 4.0) * 2.0;
+                    
+                    // Base horizon offset (lift slightly)
+                    float terrainHeight = h + 10.0;
+                    
+                    if (vPos.y > terrainHeight) discard;
+                    
+                    // Atmospheric Haze / Fog on the ground
+                    // Mix ground color with fog color based on vertical height (fade into horizon)
+                    // Closer to horizon (higher y) -> more fog
+                    float fogFactor = smoothstep(-100.0, terrainHeight, vPos.y);
+                    vec3 finalCol = mix(color, fogColor, fogFactor * 0.5);
+                    
+                    gl_FragColor = vec4(finalCol, 1.0); 
+                }
+            `,
+      side: THREE5.BackSide,
       transparent: false,
       depthWrite: true,
       depthTest: true
     });
-    const ground = new THREE4.Mesh(geometry, material);
+    const ground = new THREE5.Mesh(geometry, material);
     groundGroup.add(ground);
-    const boxGeo = new THREE4.BoxGeometry(8, 30, 8);
-    for (let i = 0; i < 12; i++) {
-      const angle = i / 12 * Math.PI * 2;
-      const b = new THREE4.Mesh(boxGeo, material);
-      const r = radius * 0.98;
-      b.position.set(Math.cos(angle) * r, -15, Math.sin(angle) * r);
-      b.lookAt(0, 0, 0);
-      groundGroup.add(b);
-    }
   }
+  let atmosphereMesh = null;
   function createAtmosphere() {
-    const geometry = new THREE4.SphereGeometry(990, 128, 64);
+    const geometry = new THREE5.SphereGeometry(990, 64, 64);
     const material = createSmartMaterial({
-      uniforms: { top: { value: new THREE4.Color(0) }, bot: { value: new THREE4.Color(1712172) } },
       vertexShaderBody: `
-    
-                    varying vec3 vP; 
-    
-                    void main() { 
-    
-                        vP = position; 
-    
-                        vec4 mv = modelViewMatrix * vec4(position, 1.0); 
-    
-                        gl_Position = smartProject(mv); 
-    
-                        vScreenPos = gl_Position.xy / gl_Position.w; 
-    
-                    }
-    
-                `,
+                varying vec3 vWorldNormal;
+                void main() { 
+                    vWorldNormal = normalize(position);
+                    vec4 mv = modelViewMatrix * vec4(position, 1.0); 
+                    gl_Position = smartProject(mv); 
+                    vScreenPos = gl_Position.xy / gl_Position.w;
+                }`,
       fragmentShader: `
-    
-                    uniform vec3 top; 
-    
-                    uniform vec3 bot; 
-    
-                    varying vec3 vP; 
-    
-                    void main() { 
-    
-                        float alphaMask = getMaskAlpha(); 
-    
-                        if (alphaMask < 0.01) discard; 
-    
-                        vec3 n = normalize(vP); 
-    
-                        float h = max(0.0, n.y); 
-    
-                        gl_FragColor = vec4(mix(bot, top, pow(h, 0.6)), 1.0); 
-    
-                    }
-    
-                `,
-      side: THREE4.BackSide,
+                varying vec3 vWorldNormal;
+                
+                uniform float uAtmGlow;
+                uniform float uAtmDark;
+                uniform vec3 uColorHorizon;
+                uniform vec3 uColorZenith;
+                
+                void main() {
+                    float alphaMask = getMaskAlpha();
+                    if (alphaMask < 0.01) discard;
+
+                    // Altitude angle (Y is up)
+                    float h = normalize(vWorldNormal).y;
+                    
+                    // Gradient Logic
+                    // 1. Base gradient from Horizon to Zenith
+                    float t = smoothstep(-0.1, 0.5, h);
+                    
+                    // Non-linear mix for realistic sky falloff
+                    // Zenith darkness adjustment
+                    vec3 skyColor = mix(uColorHorizon * uAtmGlow, uColorZenith * (1.0 - uAtmDark), pow(t, 0.6));
+                    
+                    // 2. Horizon Glow Band (Simulate scattering/haze layer)
+                    float horizonBand = exp(-15.0 * abs(h - 0.02)); // Sharp peak near 0
+                    skyColor += uColorHorizon * horizonBand * 0.5 * uAtmGlow;
+
+                    gl_FragColor = vec4(skyColor, 1.0);
+                }
+            `,
+      side: THREE5.BackSide,
       depthWrite: false,
       depthTest: true
     });
-    const atm = new THREE4.Mesh(geometry, material);
+    const atm = new THREE5.Mesh(geometry, material);
+    atmosphereMesh = atm;
     groundGroup.add(atm);
   }
-  const backdropGroup = new THREE4.Group();
+  const backdropGroup = new THREE5.Group();
   scene.add(backdropGroup);
-  function createBackdropStars() {
+  function createBackdropStars(count = 31e3) {
     backdropGroup.clear();
-    const geometry = new THREE4.BufferGeometry();
+    while (backdropGroup.children.length > 0) {
+      const c = backdropGroup.children[0];
+      backdropGroup.remove(c);
+      if (c.geometry) c.geometry.dispose();
+      if (c.material) c.material.dispose();
+    }
+    const geometry = new THREE5.BufferGeometry();
     const positions = [];
     const sizes = [];
     const colors = [];
-    const colorPalette = [
-      new THREE4.Color(10203391),
-      new THREE4.Color(11190271),
-      new THREE4.Color(13293567),
-      new THREE4.Color(16316415),
-      new THREE4.Color(16774378),
-      new THREE4.Color(16765601),
-      new THREE4.Color(16764015)
-    ];
     const r = 2500;
-    new THREE4.Vector3(0, 1, 0.5).normalize();
-    for (let i = 0; i < 4e3; i++) {
-      const isMilkyWay = Math.random() < 0.4;
-      let x, y, z;
-      if (isMilkyWay) {
-        const theta = Math.random() * Math.PI * 2;
-        const scatter = (Math.random() - 0.5) * 0.4;
-        const v = new THREE4.Vector3(Math.cos(theta), scatter, Math.sin(theta));
-        v.normalize();
-        v.applyAxisAngle(new THREE4.Vector3(1, 0, 0), THREE4.MathUtils.degToRad(60));
-        x = v.x * r;
-        y = v.y * r;
-        z = v.z * r;
-      } else {
-        const u = Math.random();
-        const v = Math.random();
-        const theta = 2 * Math.PI * u;
-        const phi = Math.acos(2 * v - 1);
-        x = r * Math.sin(phi) * Math.cos(theta);
-        y = r * Math.sin(phi) * Math.sin(theta);
-        z = r * Math.cos(phi);
-      }
+    for (let i = 0; i < count; i++) {
+      const u = Math.random();
+      const v = Math.random();
+      const theta = 2 * Math.PI * u;
+      const phi = Math.acos(2 * v - 1);
+      const x = r * Math.sin(phi) * Math.cos(theta);
+      const y = r * Math.cos(phi);
+      const z = r * Math.sin(phi) * Math.sin(theta);
       positions.push(x, y, z);
-      const size = 0.5 + -Math.log(Math.random()) * 0.8 * 1.5;
+      const size = 1 + -Math.log(Math.random()) * 0.8 * 1.5;
       sizes.push(size);
-      const cIndex = Math.floor(Math.random() * colorPalette.length);
-      const c = colorPalette[cIndex];
-      colors.push(c.r, c.g, c.b);
+      colors.push(1, 1, 1);
     }
-    geometry.setAttribute("position", new THREE4.Float32BufferAttribute(positions, 3));
-    geometry.setAttribute("size", new THREE4.Float32BufferAttribute(sizes, 1));
-    geometry.setAttribute("color", new THREE4.Float32BufferAttribute(colors, 3));
+    geometry.setAttribute("position", new THREE5.Float32BufferAttribute(positions, 3));
+    geometry.setAttribute("size", new THREE5.Float32BufferAttribute(sizes, 1));
+    geometry.setAttribute("color", new THREE5.Float32BufferAttribute(colors, 3));
     const material = createSmartMaterial({
-      uniforms: { pixelRatio: { value: renderer.getPixelRatio() } },
+      uniforms: {
+        pixelRatio: { value: renderer.getPixelRatio() },
+        uScale: globalUniforms.uScale
+      },
       vertexShaderBody: `
                 attribute float size; 
                 attribute vec3 color; 
                 varying vec3 vColor; 
                 uniform float pixelRatio; 
+                
+                uniform float uAtmExtinction;
+
                 void main() { 
-                    vColor = color; 
+                    vec3 nPos = normalize(position);
+                    float altitude = nPos.y;
+                    
+                    // Simple Extinction & Horizon Fade
+                    float horizonFade = smoothstep(-0.1, 0.1, altitude);
+                    float airmass = 1.0 / (max(0.05, altitude + 0.05));
+                    float extinction = exp(-uAtmExtinction * 0.15 * airmass);
+
+                    // Boost intensity significantly (3.0x)
+                    vColor = color * 3.0 * extinction * horizonFade;
+
                     vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); 
                     gl_Position = smartProject(mvPosition); 
                     vScreenPos = gl_Position.xy / gl_Position.w; 
-                    gl_PointSize = size * pixelRatio * (600.0 / -mvPosition.z); 
+                    
+                    // Non-linear scale with zoom to keep stars looking like points
+                    // pow(uScale, 0.5) prevents them from getting too large at low FOV
+                    float zoomScale = pow(uScale, 0.5); 
+                    
+                    gl_PointSize = size * zoomScale * 0.5 * pixelRatio * (800.0 / -mvPosition.z) * horizonFade; 
                 }
             `,
       fragmentShader: `
@@ -647,31 +958,81 @@ function createEngine({
                     if (dist > 1.0) discard; 
                     float alphaMask = getMaskAlpha(); 
                     if (alphaMask < 0.01) discard; 
-                    // Use same Gaussian glow for backdrop
-                    float alpha = exp(-3.0 * dist * dist);
+                    
+                    // Sharp falloff for intense point look
+                    float alpha = exp(-4.0 * dist * dist);
                     gl_FragColor = vec4(vColor, alpha * alphaMask); 
                 }
             `,
       transparent: true,
       depthWrite: false,
-      depthTest: true
+      depthTest: true,
+      blending: THREE5.AdditiveBlending
     });
-    const points = new THREE4.Points(geometry, material);
+    const points = new THREE5.Points(geometry, material);
     points.frustumCulled = false;
     backdropGroup.add(points);
   }
   createGround();
   createAtmosphere();
   createBackdropStars();
-  const raycaster = new THREE4.Raycaster();
+  const raycaster = new THREE5.Raycaster();
   raycaster.params.Points.threshold = 5;
-  new THREE4.Vector2();
-  const root = new THREE4.Group();
+  new THREE5.Vector2();
+  const root = new THREE5.Group();
   scene.add(root);
   const nodeById = /* @__PURE__ */ new Map();
   const starIndexToId = [];
   const dynamicLabels = [];
+  const hoverLabelMat = createSmartMaterial({
+    uniforms: {
+      uMap: { value: null },
+      uSize: { value: new THREE5.Vector2(1, 1) },
+      uAlpha: { value: 0 },
+      uAngle: { value: 0 }
+    },
+    vertexShaderBody: `
+            uniform vec2 uSize;
+            uniform float uAngle;
+            varying vec2 vUv;
+            void main() {
+                vUv = uv;
+                vec4 mvPos = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+                vec4 projected = smartProject(mvPos);
+                
+                float c = cos(uAngle);
+                float s = sin(uAngle);
+                mat2 rot = mat2(c, -s, s, c);
+                vec2 offset = rot * (position.xy * uSize);
+                
+                projected.xy += offset / vec2(uAspect, 1.0);
+                gl_Position = projected;
+            }
+        `,
+    fragmentShader: `
+            uniform sampler2D uMap;
+            uniform float uAlpha;
+            varying vec2 vUv;
+            void main() {
+                float mask = getMaskAlpha();
+                if (mask < 0.01) discard;
+                vec4 tex = texture2D(uMap, vUv);
+                gl_FragColor = vec4(tex.rgb, tex.a * uAlpha * mask);
+            }
+        `,
+    transparent: true,
+    depthWrite: false,
+    depthTest: false
+    // Always on top of stars
+  });
+  const hoverLabelMesh = new THREE5.Mesh(new THREE5.PlaneGeometry(1, 1), hoverLabelMat);
+  hoverLabelMesh.visible = false;
+  hoverLabelMesh.renderOrder = 999;
+  hoverLabelMesh.frustumCulled = false;
+  root.add(hoverLabelMesh);
+  let currentHoverNodeId = null;
   let constellationLines = null;
+  let boundaryLines = null;
   let starPoints = null;
   function clearRoot() {
     for (const child of [...root.children]) {
@@ -687,6 +1048,7 @@ function createEngine({
     starIndexToId.length = 0;
     dynamicLabels.length = 0;
     constellationLines = null;
+    boundaryLines = null;
     starPoints = null;
   }
   function createTextTexture(text, color = "#ffffff") {
@@ -694,58 +1056,102 @@ function createEngine({
     const ctx = canvas.getContext("2d");
     if (!ctx) return null;
     const fontSize = 96;
-    ctx.font = `bold ${fontSize}px sans-serif`;
+    const font = `400 ${fontSize}px "Inter", system-ui, sans-serif`;
+    ctx.font = font;
     const metrics = ctx.measureText(text);
     const w = Math.ceil(metrics.width);
     const h = Math.ceil(fontSize * 1.2);
     canvas.width = w;
     canvas.height = h;
-    ctx.font = `bold ${fontSize}px sans-serif`;
+    ctx.font = font;
     ctx.fillStyle = color;
     ctx.textAlign = "center";
     ctx.textBaseline = "middle";
     ctx.fillText(text, w / 2, h / 2);
-    const tex = new THREE4.CanvasTexture(canvas);
-    tex.minFilter = THREE4.LinearFilter;
+    const tex = new THREE5.CanvasTexture(canvas);
+    tex.minFilter = THREE5.LinearFilter;
     return { tex, aspect: w / h };
   }
   function getPosition(n) {
     if (currentConfig?.arrangement) {
       const arr = currentConfig.arrangement[n.id];
-      if (arr) return new THREE4.Vector3(arr.position[0], arr.position[1], arr.position[2]);
+      if (arr) {
+        if (arr.position[2] === 0) {
+          const x = arr.position[0];
+          const y = arr.position[1];
+          const radius = currentConfig.layout?.radius ?? 2e3;
+          const r_norm = Math.min(1, Math.sqrt(x * x + y * y) / radius);
+          const phi = Math.atan2(y, x);
+          const theta = r_norm * (Math.PI / 2);
+          return new THREE5.Vector3(
+            Math.sin(theta) * Math.cos(phi),
+            Math.cos(theta),
+            Math.sin(theta) * Math.sin(phi)
+          ).multiplyScalar(radius);
+        }
+        return new THREE5.Vector3(arr.position[0], arr.position[1], arr.position[2]);
+      }
     }
-    return new THREE4.Vector3(n.meta?.x ?? 0, n.meta?.y ?? 0, n.meta?.z ?? 0);
+    return new THREE5.Vector3(n.meta?.x ?? 0, n.meta?.y ?? 0, n.meta?.z ?? 0);
   }
   function getBoundaryPoint(angle, t, radius) {
     const y = 0.05 + t * (1 - 0.05);
     const rY = Math.sqrt(1 - y * y);
     const x = Math.cos(angle) * rY;
     const z = Math.sin(angle) * rY;
-    return new THREE4.Vector3(x, y, z).multiplyScalar(radius);
+    return new THREE5.Vector3(x, y, z).multiplyScalar(radius);
   }
   function buildFromModel(model, cfg) {
     clearRoot();
-    scene.background = cfg.background && cfg.background !== "transparent" ? new THREE4.Color(cfg.background) : new THREE4.Color(0);
+    bookIdToIndex.clear();
+    scene.background = cfg.background && cfg.background !== "transparent" ? new THREE5.Color(cfg.background) : new THREE5.Color(0);
     const layoutCfg = { ...cfg.layout, radius: cfg.layout?.radius ?? 2e3 };
     const laidOut = computeLayoutPositions(model, layoutCfg);
+    const divisionPositions = /* @__PURE__ */ new Map();
+    if (cfg.arrangement) {
+      const divMap = /* @__PURE__ */ new Map();
+      for (const n of laidOut.nodes) {
+        if (n.level === 2 && n.parent) {
+          const list = divMap.get(n.parent) ?? [];
+          list.push(n);
+          divMap.set(n.parent, list);
+        }
+      }
+      for (const [divId, books] of divMap.entries()) {
+        const centroid = new THREE5.Vector3();
+        let count = 0;
+        for (const b of books) {
+          const p = getPosition(b);
+          centroid.add(p);
+          count++;
+        }
+        if (count > 0) {
+          centroid.divideScalar(count);
+          divisionPositions.set(divId, centroid);
+        }
+      }
+    }
     const starPositions = [];
     const starSizes = [];
     const starColors = [];
+    const starPhases = [];
+    const starBookIndices = [];
+    const starChapterIndices = [];
     const SPECTRAL_COLORS = [
-      new THREE4.Color(10203391),
-      // O - Blue
-      new THREE4.Color(11190271),
-      // B - Blue-white
-      new THREE4.Color(13293567),
-      // A - White-blue
-      new THREE4.Color(16316415),
+      new THREE5.Color(14544639),
+      // O - Blueish White
+      new THREE5.Color(15660287),
+      // B - White
+      new THREE5.Color(16317695),
+      // A - White
+      new THREE5.Color(16777208),
       // F - White
-      new THREE4.Color(16774378),
-      // G - Yellow-white
-      new THREE4.Color(16765601),
-      // K - Yellow-orange
-      new THREE4.Color(16764015)
-      // M - Orange-red
+      new THREE5.Color(16775406),
+      // G - Yellowish White
+      new THREE5.Color(16773085),
+      // K - Pale Orange
+      new THREE5.Color(16771788)
+      // M - Light Orange
     ];
     let minWeight = Infinity;
     let maxWeight = -Infinity;
@@ -770,32 +1176,62 @@ function createEngine({
         let baseSize = 3.5;
         if (typeof n.weight === "number") {
           const t = (n.weight - minWeight) / (maxWeight - minWeight);
-          baseSize = 3 + t * 4;
+          baseSize = 0.1 + Math.pow(t, 0.5) * 11.9;
         }
         starSizes.push(baseSize);
         const colorIdx = Math.floor(Math.pow(Math.random(), 1.5) * SPECTRAL_COLORS.length);
         const c = SPECTRAL_COLORS[Math.min(colorIdx, SPECTRAL_COLORS.length - 1)];
         starColors.push(c.r, c.g, c.b);
-      } else if (n.level === 2) {
-        const color = "#ffffff";
-        const texRes = createTextTexture(n.label, color);
+        starPhases.push(Math.random() * Math.PI * 2);
+        let bIdx = -1;
+        if (n.parent) {
+          if (!bookIdToIndex.has(n.parent)) {
+            bookIdToIndex.set(n.parent, bookIdToIndex.size + 1);
+          }
+          bIdx = bookIdToIndex.get(n.parent);
+        }
+        starBookIndices.push(bIdx);
+        let cIdx = 0;
+        if (n.meta?.chapter) cIdx = Number(n.meta.chapter);
+        starChapterIndices.push(cIdx);
+      }
+      if (n.level === 1 || n.level === 2 || n.level === 3) {
+        let color = "#ffffff";
+        if (n.level === 1) color = "#38bdf8";
+        else if (n.level === 2) color = "#cbd5e1";
+        else if (n.level === 3) color = "#94a3b8";
+        let labelText = n.label;
+        if (n.level === 3 && n.meta?.chapter) {
+          labelText = String(n.meta.chapter);
+        }
+        const texRes = createTextTexture(labelText, color);
         if (texRes) {
-          const baseScale = 0.05;
-          const size = new THREE4.Vector2(baseScale * texRes.aspect, baseScale);
+          let baseScale = 0.05;
+          if (n.level === 1) baseScale = 0.08;
+          else if (n.level === 2) baseScale = 0.04;
+          else if (n.level === 3) baseScale = 0.03;
+          const size = new THREE5.Vector2(baseScale * texRes.aspect, baseScale);
           const mat = createSmartMaterial({
             uniforms: {
               uMap: { value: texRes.tex },
               uSize: { value: size },
-              uAlpha: { value: 0 }
+              uAlpha: { value: 0 },
+              uAngle: { value: 0 }
             },
             vertexShaderBody: `
                             uniform vec2 uSize;
+                            uniform float uAngle;
                             varying vec2 vUv;
                             void main() {
                                 vUv = uv;
                                 vec4 mvPos = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
                                 vec4 projected = smartProject(mvPos);
-                                vec2 offset = position.xy * uSize;
+                                
+                                float c = cos(uAngle);
+                                float s = sin(uAngle);
+                                mat2 rot = mat2(c, -s, s, c);
+                                vec2 offset = rot * (position.xy * uSize);
+                                
                                 projected.xy += offset / vec2(uAspect, 1.0);
                                 gl_Position = projected;
                             }
@@ -815,8 +1251,19 @@ function createEngine({
             depthWrite: false,
             depthTest: true
           });
-          const mesh = new THREE4.Mesh(new THREE4.PlaneGeometry(1, 1), mat);
-          const p = getPosition(n);
+          const mesh = new THREE5.Mesh(new THREE5.PlaneGeometry(1, 1), mat);
+          let p = getPosition(n);
+          if (n.level === 1) {
+            if (divisionPositions.has(n.id)) {
+              p.copy(divisionPositions.get(n.id));
+            }
+            const r = layoutCfg.radius * 0.95;
+            const angle = Math.atan2(p.z, p.x);
+            p.set(r * Math.cos(angle), 150, r * Math.sin(angle));
+          } else if (n.level === 3) {
+            p.y += 30;
+            p.multiplyScalar(1.001);
+          }
           mesh.position.set(p.x, p.y, p.z);
           mesh.scale.set(size.x, size.y, 1);
           mesh.frustumCulled = false;
@@ -826,47 +1273,119 @@ function createEngine({
         }
       }
     }
-    const starGeo = new THREE4.BufferGeometry();
-    starGeo.setAttribute("position", new THREE4.Float32BufferAttribute(starPositions, 3));
-    starGeo.setAttribute("size", new THREE4.Float32BufferAttribute(starSizes, 1));
-    starGeo.setAttribute("color", new THREE4.Float32BufferAttribute(starColors, 3));
+    const starGeo = new THREE5.BufferGeometry();
+    starGeo.setAttribute("position", new THREE5.Float32BufferAttribute(starPositions, 3));
+    starGeo.setAttribute("size", new THREE5.Float32BufferAttribute(starSizes, 1));
+    starGeo.setAttribute("color", new THREE5.Float32BufferAttribute(starColors, 3));
+    starGeo.setAttribute("phase", new THREE5.Float32BufferAttribute(starPhases, 1));
+    starGeo.setAttribute("bookIndex", new THREE5.Float32BufferAttribute(starBookIndices, 1));
+    starGeo.setAttribute("chapterIndex", new THREE5.Float32BufferAttribute(starChapterIndices, 1));
     const starMat = createSmartMaterial({
-      uniforms: { pixelRatio: { value: renderer.getPixelRatio() } },
+      uniforms: {
+        pixelRatio: { value: renderer.getPixelRatio() },
+        uScale: globalUniforms.uScale,
+        uTime: globalUniforms.uTime,
+        uActiveBookIndex: { value: -1 },
+        uOrderRevealStrength: { value: 0 },
+        uGlobalDimFactor: { value: ORDER_REVEAL_CONFIG.globalDim },
+        uPulseParams: { value: new THREE5.Vector3(
+          ORDER_REVEAL_CONFIG.pulseDuration,
+          ORDER_REVEAL_CONFIG.delayPerChapter,
+          ORDER_REVEAL_CONFIG.pulseAmplitude
+        ) }
+      },
       vertexShaderBody: `
                 attribute float size; 
                 attribute vec3 color; 
+                attribute float phase;
+                attribute float bookIndex;
+                attribute float chapterIndex;
+
                 varying vec3 vColor; 
                 uniform float pixelRatio; 
+                
+                uniform float uTime;
+                uniform float uAtmExtinction;
+                uniform float uAtmTwinkle;
+
+                uniform float uActiveBookIndex;
+                uniform float uOrderRevealStrength;
+                uniform float uGlobalDimFactor;
+                uniform vec3 uPulseParams;
+
                 void main() { 
-                    vColor = color; 
+                    vec3 nPos = normalize(position);
+                    
+                    // 1. Altitude (Y is UP)
+                    float altitude = nPos.y; 
+                    
+                    // 2. Atmospheric Extinction (Airmass approximation)
+                    float airmass = 1.0 / (max(0.02, altitude + 0.05));
+                    float extinction = exp(-uAtmExtinction * 0.1 * airmass);
+                    
+                    // Fade out stars below horizon
+                    float horizonFade = smoothstep(-0.1, 0.05, altitude);
+                    
+                    // 3. Scintillation
+                    float turbulence = 1.0 + (1.0 - smoothstep(0.0, 1.0, altitude)) * 2.0;
+                    float twinkle = sin(uTime * 3.0 + phase + position.x * 0.01) * 0.5 + 0.5; 
+                    float scintillation = mix(1.0, twinkle * 2.0, uAtmTwinkle * 0.5 * turbulence);
+                    
+                    // --- Order Reveal Logic ---
+                    float isTarget = 1.0 - min(1.0, abs(bookIndex - uActiveBookIndex));
+                    
+                    // Dimming
+                    float dimFactor = mix(1.0, uGlobalDimFactor, uOrderRevealStrength * (1.0 - isTarget));
+                    
+                    // Pulse
+                    float delay = chapterIndex * uPulseParams.y;
+                    float cycleDuration = uPulseParams.x * 2.5; 
+                    float t = mod(uTime - delay, cycleDuration);
+                    
+                    float pulse = smoothstep(0.0, 0.2, t) * (1.0 - smoothstep(0.4, uPulseParams.x, t));
+                    pulse = max(0.0, pulse);
+                    
+                    float activePulse = pulse * uPulseParams.z * isTarget * uOrderRevealStrength;
+
+                    vec3 baseColor = color * extinction * horizonFade * scintillation;
+                    vColor = baseColor * dimFactor;
+                    vColor += vec3(1.0, 0.8, 0.4) * activePulse;
+
                     vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); 
                     gl_Position = smartProject(mvPosition); 
                     vScreenPos = gl_Position.xy / gl_Position.w; 
-                    gl_PointSize = size * pixelRatio * (2000.0 / -mvPosition.z); 
+                    
+                    float sizeBoost = 1.0 + activePulse * 0.8;
+                    gl_PointSize = (size * sizeBoost * 1.5) * uScale * pixelRatio * (2000.0 / -mvPosition.z) * horizonFade; 
                 }
             `,
       fragmentShader: `
                 varying vec3 vColor; 
                 void main() { 
                     vec2 coord = gl_PointCoord - vec2(0.5); 
-                    // Use larger drawing area for glow
-                    float dist = length(coord) * 2.0; 
-                    if (dist > 1.0) discard; 
+                    float d = length(coord) * 2.0; 
+                    if (d > 1.0) discard; 
                     
                     float alphaMask = getMaskAlpha(); 
                     if (alphaMask < 0.01) discard; 
                     
-                    // Gaussian Glow: Sharp core, soft halo
-                    float alpha = exp(-3.0 * dist * dist);
+                    float dd = d * d;
+                    // Stellarium Profile
+                    float core = exp(-20.0 * dd);
+                    float halo = exp(-4.0 * dd);
                     
-                    gl_FragColor = vec4(vColor, alpha * alphaMask); 
+                    vec3 cCore = vec3(1.0) * core * 1.5;
+                    vec3 cHalo = vColor * halo * 0.6;
+                    
+                    gl_FragColor = vec4((cCore + cHalo) * alphaMask, 1.0); 
                 }
             `,
       transparent: true,
       depthWrite: false,
-      depthTest: true
+      depthTest: true,
+      blending: THREE5.AdditiveBlending
     });
-    starPoints = new THREE4.Points(starGeo, starMat);
+    starPoints = new THREE5.Points(starGeo, starMat);
     starPoints.frustumCulled = false;
     root.add(starPoints);
     const linePoints = [];
@@ -892,31 +1411,119 @@ function createEngine({
       }
     }
     if (linePoints.length > 0) {
-      const lineGeo = new THREE4.BufferGeometry();
-      lineGeo.setAttribute("position", new THREE4.Float32BufferAttribute(linePoints, 3));
+      const lineGeo = new THREE5.BufferGeometry();
+      lineGeo.setAttribute("position", new THREE5.Float32BufferAttribute(linePoints, 3));
       const lineMat = createSmartMaterial({
-        uniforms: { color: { value: new THREE4.Color(4478310) } },
+        uniforms: { color: { value: new THREE5.Color(11193599) } },
         vertexShaderBody: `uniform vec3 color; varying vec3 vColor; void main() { vColor = color; vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); gl_Position = smartProject(mvPosition); vScreenPos = gl_Position.xy / gl_Position.w; }`,
-        fragmentShader: `varying vec3 vColor; void main() { float alphaMask = getMaskAlpha(); if (alphaMask < 0.01) discard; gl_FragColor = vec4(vColor, 0.2 * alphaMask); }`,
+        fragmentShader: `varying vec3 vColor; void main() { float alphaMask = getMaskAlpha(); if (alphaMask < 0.01) discard; gl_FragColor = vec4(vColor, 0.4 * alphaMask); }`,
         transparent: true,
         depthWrite: false,
-        blending: THREE4.AdditiveBlending
+        blending: THREE5.AdditiveBlending
       });
-      constellationLines = new THREE4.LineSegments(lineGeo, lineMat);
+      constellationLines = new THREE5.LineSegments(lineGeo, lineMat);
       constellationLines.frustumCulled = false;
       root.add(constellationLines);
     }
+    if (cfg.groups) {
+      for (const [bookId, chapters] of bookMap.entries()) {
+        const bookNode = nodeById.get(bookId);
+        if (!bookNode) continue;
+        const bookName = bookNode.meta?.book || bookNode.label;
+        const groupList = cfg.groups[bookName.toLowerCase()];
+        if (groupList) {
+          groupList.forEach((g, idx) => {
+            const groupId = `G:${bookId}:${idx}`;
+            let p = new THREE5.Vector3();
+            if (cfg.arrangement && cfg.arrangement[groupId]) {
+              const arr = cfg.arrangement[groupId];
+              p.set(arr.position[0], arr.position[1], arr.position[2]);
+            } else {
+              const relevantChapters = chapters.filter((c) => {
+                const ch = c.meta?.chapter;
+                return ch >= g.start && ch <= g.end;
+              });
+              if (relevantChapters.length === 0) return;
+              for (const c of relevantChapters) {
+                p.add(getPosition(c));
+              }
+              p.divideScalar(relevantChapters.length);
+            }
+            const labelText = `${g.name} (${g.start}-${g.end})`;
+            const texRes = createTextTexture(labelText, "#4fa4fa80");
+            if (texRes) {
+              const baseScale = 0.036;
+              const size = new THREE5.Vector2(baseScale * texRes.aspect, baseScale);
+              const mat = createSmartMaterial({
+                uniforms: {
+                  uMap: { value: texRes.tex },
+                  uSize: { value: size },
+                  uAlpha: { value: 0 },
+                  uAngle: { value: 0 }
+                },
+                vertexShaderBody: `
+                                    uniform vec2 uSize;
+                                    uniform float uAngle;
+                                    varying vec2 vUv;
+                                    void main() {
+                                        vUv = uv;
+                                        vec4 mvPos = modelViewMatrix * vec4(0.0, 0.0, 0.0, 1.0);
+                                        vec4 projected = smartProject(mvPos);
+                                        
+                                        float c = cos(uAngle);
+                                        float s = sin(uAngle);
+                                        mat2 rot = mat2(c, -s, s, c);
+                                        vec2 offset = rot * (position.xy * uSize);
+                                        
+                                        projected.xy += offset / vec2(uAspect, 1.0);
+                                        gl_Position = projected;
+                                    }
+                                `,
+                fragmentShader: `
+                                    uniform sampler2D uMap;
+                                    uniform float uAlpha;
+                                    varying vec2 vUv;
+                                    void main() {
+                                        float mask = getMaskAlpha();
+                                        if (mask < 0.01) discard;
+                                        vec4 tex = texture2D(uMap, vUv);
+                                        gl_FragColor = vec4(tex.rgb, tex.a * uAlpha * mask);
+                                    }
+                                `,
+                transparent: true,
+                depthWrite: false,
+                depthTest: true
+              });
+              const mesh = new THREE5.Mesh(new THREE5.PlaneGeometry(1, 1), mat);
+              mesh.position.copy(p);
+              mesh.scale.set(size.x, size.y, 1);
+              mesh.frustumCulled = false;
+              mesh.userData = { id: groupId };
+              root.add(mesh);
+              const node = {
+                id: groupId,
+                label: labelText,
+                level: 2.5,
+                // Special Level
+                parent: bookId
+              };
+              dynamicLabels.push({ obj: mesh, node, initialScale: size.clone() });
+            }
+          });
+        }
+      }
+    }
     const boundaries = laidOut.meta?.divisionBoundaries ?? [];
     if (boundaries.length > 0) {
       const boundaryMat = createSmartMaterial({
-        uniforms: { color: { value: new THREE4.Color(5601177) } },
+        uniforms: { color: { value: new THREE5.Color(5601177) } },
         vertexShaderBody: `uniform vec3 color; varying vec3 vColor; void main() { vColor = color; vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); gl_Position = smartProject(mvPosition); vScreenPos = gl_Position.xy / gl_Position.w; }`,
         fragmentShader: `varying vec3 vColor; void main() { float alphaMask = getMaskAlpha(); if (alphaMask < 0.01) discard; gl_FragColor = vec4(vColor, 0.10 * alphaMask); }`,
         transparent: true,
         depthWrite: false,
-        blending: THREE4.AdditiveBlending
+        blending: THREE5.AdditiveBlending
       });
-      const boundaryGeo = new THREE4.BufferGeometry();
+      const boundaryGeo = new THREE5.BufferGeometry();
       const bPoints = [];
       boundaries.forEach((angle) => {
         const steps = 32;
@@ -929,18 +1536,80 @@ function createEngine({
           bPoints.push(p2.x, p2.y, p2.z);
         }
       });
-      boundaryGeo.setAttribute("position", new THREE4.Float32BufferAttribute(bPoints, 3));
-      const boundaryLines = new THREE4.LineSegments(boundaryGeo, boundaryMat);
+      boundaryGeo.setAttribute("position", new THREE5.Float32BufferAttribute(bPoints, 3));
+      boundaryLines = new THREE5.LineSegments(boundaryGeo, boundaryMat);
       boundaryLines.frustumCulled = false;
       root.add(boundaryLines);
     }
+    if (cfg.polygons) {
+      const polyPoints = [];
+      const rBase = layoutCfg.radius;
+      for (const pts of Object.values(cfg.polygons)) {
+        if (pts.length < 2) continue;
+        for (let i = 0; i < pts.length; i++) {
+          const p1_2d = pts[i];
+          const p2_2d = pts[(i + 1) % pts.length];
+          if (!p1_2d || !p2_2d) continue;
+          const project2dTo3d = (p) => {
+            const x = p[0];
+            const y = p[1];
+            const r_norm = Math.sqrt(x * x + y * y);
+            const phi = Math.atan2(y, x);
+            const theta = r_norm * (Math.PI / 2);
+            return new THREE5.Vector3(
+              Math.sin(theta) * Math.cos(phi),
+              Math.cos(theta),
+              Math.sin(theta) * Math.sin(phi)
+            ).multiplyScalar(rBase);
+          };
+          const v1 = project2dTo3d(p1_2d);
+          const v2 = project2dTo3d(p2_2d);
+          polyPoints.push(v1.x, v1.y, v1.z);
+          polyPoints.push(v2.x, v2.y, v2.z);
+        }
+      }
+      if (polyPoints.length > 0) {
+        const polyGeo = new THREE5.BufferGeometry();
+        polyGeo.setAttribute("position", new THREE5.Float32BufferAttribute(polyPoints, 3));
+        const polyMat = createSmartMaterial({
+          uniforms: { color: { value: new THREE5.Color(3718648) } },
+          // Cyan-ish
+          vertexShaderBody: `uniform vec3 color; varying vec3 vColor; void main() { vColor = color; vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); gl_Position = smartProject(mvPosition); vScreenPos = gl_Position.xy / gl_Position.w; }`,
+          fragmentShader: `varying vec3 vColor; void main() { float alphaMask = getMaskAlpha(); if (alphaMask < 0.01) discard; gl_FragColor = vec4(vColor, 0.2 * alphaMask); }`,
+          transparent: true,
+          depthWrite: false,
+          blending: THREE5.AdditiveBlending
+        });
+        const polyLines = new THREE5.LineSegments(polyGeo, polyMat);
+        polyLines.frustumCulled = false;
+        root.add(polyLines);
+      }
+    }
     resize();
   }
   let lastData = void 0;
   let lastAdapter = void 0;
   let lastModel = void 0;
+  let lastAppliedLon = void 0;
+  let lastAppliedLat = void 0;
+  let lastBackdropCount = void 0;
   function setConfig(cfg) {
     currentConfig = cfg;
+    if (typeof cfg.camera?.lon === "number" && cfg.camera.lon !== lastAppliedLon) {
+      state.lon = cfg.camera.lon;
+      state.targetLon = cfg.camera.lon;
+      lastAppliedLon = cfg.camera.lon;
+    }
+    if (typeof cfg.camera?.lat === "number" && cfg.camera.lat !== lastAppliedLat) {
+      state.lat = cfg.camera.lat;
+      state.targetLat = cfg.camera.lat;
+      lastAppliedLat = cfg.camera.lat;
+    }
+    const desiredBackdropCount = typeof cfg.backdropStarsCount === "number" ? cfg.backdropStarsCount : 4e3;
+    if (lastBackdropCount !== desiredBackdropCount) {
+      createBackdropStars(desiredBackdropCount);
+      lastBackdropCount = desiredBackdropCount;
+    }
     let shouldRebuild = false;
     let model = cfg.model;
     if (!model && cfg.data && cfg.adapter) {
@@ -964,6 +1633,29 @@ function createEngine({
     } else if (cfg.arrangement && starPoints) {
       if (lastModel) buildFromModel(lastModel, cfg);
     }
+    if (cfg.constellations) {
+      constellationLayer.load(cfg.constellations, (id) => {
+        if (cfg.arrangement && cfg.arrangement[id]) {
+          const arr = cfg.arrangement[id];
+          if (arr.position[2] === 0) {
+            const x = arr.position[0];
+            const y = arr.position[1];
+            const radius = cfg.layout?.radius ?? 2e3;
+            const r_norm = Math.min(1, Math.sqrt(x * x + y * y) / radius);
+            const phi = Math.atan2(y, x);
+            const theta = r_norm * (Math.PI / 2);
+            return new THREE5.Vector3(
+              Math.sin(theta) * Math.cos(phi),
+              Math.cos(theta),
+              Math.sin(theta) * Math.sin(phi)
+            ).multiplyScalar(radius);
+          }
+          return new THREE5.Vector3(arr.position[0], arr.position[1], arr.position[2]);
+        }
+        const n = nodeById.get(id);
+        return n ? getPosition(n) : null;
+      });
+    }
   }
   function setHandlers(next) {
     handlers = next;
@@ -971,22 +1663,25 @@ function createEngine({
   function getFullArrangement() {
     const arr = {};
     if (starPoints && starPoints.geometry.attributes.position) {
-      const positions = starPoints.geometry.attributes.position.array;
+      const attr = starPoints.geometry.attributes.position;
       for (let i = 0; i < starIndexToId.length; i++) {
         const id = starIndexToId[i];
         if (id) {
-          const x = positions[i * 3] ?? 0;
-          const y = positions[i * 3 + 1] ?? 0;
-          const z = positions[i * 3 + 2] ?? 0;
-          if (Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)) {
-            arr[id] = { position: [x, y, z] };
-          }
+          const x = attr.getX(i);
+          const y = attr.getY(i);
+          const z = attr.getZ(i);
+          arr[id] = { position: [x, y, z] };
         }
       }
     }
     for (const item of dynamicLabels) {
+      if (item.node.level === 3) continue;
       arr[item.node.id] = { position: [item.obj.position.x, item.obj.position.y, item.obj.position.z] };
     }
+    for (const item of constellationLayer.getItems()) {
+      arr[item.config.id] = { position: [item.mesh.position.x, item.mesh.position.y, item.mesh.position.z] };
+    }
+    Object.assign(arr, state.tempArrangement);
     return arr;
   }
   function pick(ev) {
@@ -995,16 +1690,18 @@ function createEngine({
     const mY = ev.clientY - rect.top;
     mouseNDC.x = mX / rect.width * 2 - 1;
     mouseNDC.y = -(mY / rect.height) * 2 + 1;
-    let closestLabel = null;
-    let minLabelDist = 40;
     const uScale = globalUniforms.uScale.value;
     const uAspect = camera.aspect;
     const w = rect.width;
     const h = rect.height;
+    let closestLabel = null;
+    let minLabelDist = 40;
     for (const item of dynamicLabels) {
       if (!item.obj.visible) continue;
       const pWorld = item.obj.position;
       const pProj = smartProjectJS(pWorld);
+      const isBehind = globalUniforms.uBlend.value > 0.5 && pProj.z > 0.4 || globalUniforms.uBlend.value < 0.1 && pProj.z > -0.1;
+      if (isBehind) continue;
       const xNDC = pProj.x * uScale / uAspect;
       const yNDC = pProj.y * uScale;
       const sX = (xNDC * 0.5 + 0.5) * w;
@@ -1012,24 +1709,72 @@ function createEngine({
       const dx = mX - sX;
       const dy = mY - sY;
       const d = Math.sqrt(dx * dx + dy * dy);
-      const isBehind = globalUniforms.uBlend.value > 0.5 && pProj.z > 0.4 || globalUniforms.uBlend.value < 0.1 && pProj.z > -0.1;
-      if (!isBehind && d < minLabelDist) {
+      if (d < minLabelDist) {
         minLabelDist = d;
         closestLabel = item;
       }
     }
-    if (closestLabel) return { type: "label", node: closestLabel.node, object: closestLabel.obj, point: closestLabel.obj.position.clone(), index: void 0 };
-    const worldDir = getMouseWorldVector(mX, mY, rect.width, rect.height);
-    raycaster.ray.origin.set(0, 0, 0);
-    raycaster.ray.direction.copy(worldDir);
-    raycaster.params.Points.threshold = 5 * (state.fov / 60);
-    const hits = raycaster.intersectObject(starPoints, false);
-    const pointHit = hits[0];
-    if (pointHit && pointHit.index !== void 0) {
-      const id = starIndexToId[pointHit.index];
-      if (id) {
-        const node = nodeById.get(id);
-        if (node) return { type: "star", node, index: pointHit.index, point: pointHit.point, object: void 0 };
+    if (closestLabel) {
+      return { type: "label", node: closestLabel.node, object: closestLabel.obj, point: closestLabel.obj.position.clone(), index: void 0 };
+    }
+    let closestConst = null;
+    let minConstDist = Infinity;
+    for (const item of constellationLayer.getItems()) {
+      if (!item.mesh.visible) continue;
+      const pWorld = item.mesh.position;
+      const pProj = smartProjectJS(pWorld);
+      const isBehind = globalUniforms.uBlend.value > 0.5 && pProj.z > 0.4 || globalUniforms.uBlend.value < 0.1 && pProj.z > -0.1;
+      if (isBehind) continue;
+      const uniforms = item.material.uniforms;
+      if (!uniforms || !uniforms.uSize) continue;
+      const uSize = uniforms.uSize.value;
+      const uImgAspect = uniforms.uImgAspect.value;
+      const uImgRotation = uniforms.uImgRotation.value;
+      const dist = pWorld.length();
+      if (dist < 1e-3) continue;
+      const scale = uSize / dist * uScale;
+      const halfH_px = scale / 2 * (h / 2);
+      const halfW_px = halfH_px * uImgAspect;
+      const xNDC = pProj.x * uScale / uAspect;
+      const yNDC = pProj.y * uScale;
+      const sX = (xNDC * 0.5 + 0.5) * w;
+      const sY = (-yNDC * 0.5 + 0.5) * h;
+      const dx = mX - sX;
+      const dy = mY - sY;
+      const dy_cart = -dy;
+      const cr = Math.cos(-uImgRotation);
+      const sr = Math.sin(-uImgRotation);
+      const localX = dx * cr - dy_cart * sr;
+      const localY = dx * sr + dy_cart * cr;
+      if (Math.abs(localX) < halfW_px * 1.2 && Math.abs(localY) < halfH_px * 1.2) {
+        const d = Math.sqrt(dx * dx + dy * dy);
+        if (!closestConst || d < minConstDist) {
+          minConstDist = d;
+          closestConst = item;
+        }
+      }
+    }
+    if (closestConst) {
+      const fakeNode = {
+        id: closestConst.config.id,
+        label: closestConst.config.title,
+        level: -1
+      };
+      return { type: "constellation", node: fakeNode, object: closestConst.mesh, point: closestConst.mesh.position.clone(), index: void 0 };
+    }
+    if (starPoints) {
+      const worldDir = getMouseWorldVector(mX, mY, rect.width, rect.height);
+      raycaster.ray.origin.set(0, 0, 0);
+      raycaster.ray.direction.copy(worldDir);
+      raycaster.params.Points.threshold = 5 * (state.fov / 60);
+      const hits = raycaster.intersectObject(starPoints, false);
+      const pointHit = hits[0];
+      if (pointHit && pointHit.index !== void 0) {
+        const id = starIndexToId[pointHit.index];
+        if (id) {
+          const node = nodeById.get(id);
+          if (node) return { type: "star", node, index: pointHit.index, point: pointHit.point, object: void 0 };
+        }
       }
     }
     return void 0;
@@ -1057,21 +1802,25 @@ function createEngine({
               if (starId) {
                 const starNode = nodeById.get(starId);
                 if (starNode && starNode.parent === bookId) {
-                  children.push({ index: i, initialPos: new THREE4.Vector3(positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]) });
+                  children.push({ index: i, initialPos: new THREE5.Vector3(positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]) });
                 }
               }
             }
           }
           state.draggedGroup = { labelInitialPos: hit.object.position.clone(), children };
           state.draggedStarIndex = -1;
+        } else if (hit.type === "constellation") {
+          state.draggedGroup = null;
+          state.draggedStarIndex = -1;
         }
-        return;
       }
+      return;
     }
     state.dragMode = "camera";
     state.isDragging = true;
     state.velocityX = 0;
     state.velocityY = 0;
+    state.tempArrangement = {};
     document.body.style.cursor = "grabbing";
   }
   function onMouseMove(e) {
@@ -1092,16 +1841,29 @@ function createEngine({
       } else if (state.draggedGroup && state.draggedNodeId) {
         const group = state.draggedGroup;
         const item = dynamicLabels.find((l) => l.node.id === state.draggedNodeId);
-        if (item) item.obj.position.copy(newPos);
+        if (item) {
+          item.obj.position.copy(newPos);
+          state.tempArrangement[item.node.id] = { position: [newPos.x, newPos.y, newPos.z] };
+        } else if (state.draggedNodeId) {
+          const cItem = constellationLayer.getItems().find((c) => c.config.id === state.draggedNodeId);
+          if (cItem) {
+            cItem.mesh.position.copy(newPos);
+            state.tempArrangement[state.draggedNodeId] = { position: [newPos.x, newPos.y, newPos.z] };
+          }
+        }
         const vStart = group.labelInitialPos.clone().normalize();
         const vEnd = newPos.clone().normalize();
-        const q = new THREE4.Quaternion().setFromUnitVectors(vStart, vEnd);
+        const q = new THREE5.Quaternion().setFromUnitVectors(vStart, vEnd);
         if (starPoints && group.children.length > 0) {
           const attr = starPoints.geometry.attributes.position;
-          const tempVec = new THREE4.Vector3();
+          const tempVec = new THREE5.Vector3();
           for (const child of group.children) {
             tempVec.copy(child.initialPos).applyQuaternion(q);
             attr.setXYZ(child.index, tempVec.x, tempVec.y, tempVec.z);
+            const id = starIndexToId[child.index];
+            if (id) {
+              state.tempArrangement[id] = { position: [tempVec.x, tempVec.y, tempVec.z] };
+            }
           }
           attr.needsUpdate = true;
         }
@@ -1121,9 +1883,30 @@ function createEngine({
       state.lat = state.targetLat;
     } else {
       const hit = pick(e);
+      if (hit && hit.type === "star") {
+        if (currentHoverNodeId !== hit.node.id) {
+          currentHoverNodeId = hit.node.id;
+          const res = createTextTexture(hit.node.label, "#ffd700");
+          if (res) {
+            hoverLabelMat.uniforms.uMap.value = res.tex;
+            const baseScale = 0.03;
+            const size = new THREE5.Vector2(baseScale * res.aspect, baseScale);
+            hoverLabelMat.uniforms.uSize.value = size;
+            hoverLabelMesh.scale.set(size.x, size.y, 1);
+          }
+        }
+        hoverLabelMesh.position.copy(hit.point);
+        hoverLabelMat.uniforms.uAlpha.value = 1;
+        hoverLabelMesh.visible = true;
+      } else {
+        currentHoverNodeId = null;
+        hoverLabelMat.uniforms.uAlpha.value = 0;
+        hoverLabelMesh.visible = false;
+      }
       if (hit?.node.id !== handlers._lastHoverId) {
         handlers._lastHoverId = hit?.node.id;
         handlers.onHover?.(hit?.node);
+        constellationLayer.setHovered(hit?.node.id ?? null);
       }
       document.body.style.cursor = hit ? currentConfig?.editable ? "crosshair" : "pointer" : "default";
     }
@@ -1143,7 +1926,14 @@ function createEngine({
       document.body.style.cursor = "default";
     } else {
       const hit = pick(e);
-      if (hit) handlers.onSelect?.(hit.node);
+      if (hit) {
+        handlers.onSelect?.(hit.node);
+        constellationLayer.setFocused(hit.node.id);
+        if (hit.node.level === 2) setFocusedBook(hit.node.id);
+        else if (hit.node.level === 3 && hit.node.parent) setFocusedBook(hit.node.parent);
+      } else {
+        setFocusedBook(null);
+      }
     }
   }
   function onWheel(e) {
@@ -1154,25 +1944,26 @@ function createEngine({
     const zoomSpeed = 1e-3 * state.fov;
     state.fov += e.deltaY * zoomSpeed;
     state.fov = Math.max(ENGINE_CONFIG.minFov, Math.min(ENGINE_CONFIG.maxFov, state.fov));
+    handlers.onFovChange?.(state.fov);
     updateUniforms();
     const vAfter = getMouseViewVector(state.fov, aspect);
-    const quaternion = new THREE4.Quaternion().setFromUnitVectors(vAfter, vBefore);
+    const quaternion = new THREE5.Quaternion().setFromUnitVectors(vAfter, vBefore);
     const y = Math.sin(state.lat);
     const r = Math.cos(state.lat);
     const x = r * Math.sin(state.lon);
     const z = -r * Math.cos(state.lon);
-    const currentLook = new THREE4.Vector3(x, y, z);
+    const currentLook = new THREE5.Vector3(x, y, z);
     const camForward = currentLook.clone().normalize();
     const camUp = camera.up.clone();
-    const camRight = new THREE4.Vector3().crossVectors(camForward, camUp).normalize();
-    const camUpOrtho = new THREE4.Vector3().crossVectors(camRight, camForward).normalize();
-    const mat = new THREE4.Matrix4().makeBasis(camRight, camUpOrtho, camForward.clone().negate());
-    const qOld = new THREE4.Quaternion().setFromRotationMatrix(mat);
+    const camRight = new THREE5.Vector3().crossVectors(camForward, camUp).normalize();
+    const camUpOrtho = new THREE5.Vector3().crossVectors(camRight, camForward).normalize();
+    const mat = new THREE5.Matrix4().makeBasis(camRight, camUpOrtho, camForward.clone().negate());
+    const qOld = new THREE5.Quaternion().setFromRotationMatrix(mat);
     const qNew = qOld.clone().multiply(quaternion);
-    const newForward = new THREE4.Vector3(0, 0, -1).applyQuaternion(qNew);
+    const newForward = new THREE5.Vector3(0, 0, -1).applyQuaternion(qNew);
     state.lat = Math.asin(Math.max(-0.999, Math.min(0.999, newForward.y)));
     state.lon = Math.atan2(newForward.x, -newForward.z);
-    const newUp = new THREE4.Vector3(0, 1, 0).applyQuaternion(qNew);
+    const newUp = new THREE5.Vector3(0, 1, 0).applyQuaternion(qNew);
     camera.up.copy(newUp);
     if (e.deltaY > 0 && state.fov > ENGINE_CONFIG.zenithStartFov) {
       const range = ENGINE_CONFIG.maxFov - ENGINE_CONFIG.zenithStartFov;
@@ -1213,79 +2004,205 @@ function createEngine({
   function tick() {
     if (!running) return;
     raf = requestAnimationFrame(tick);
-    if (!state.isDragging && isMouseInWindow) {
+    const now = performance.now();
+    globalUniforms.uTime.value = now / 1e3;
+    let activeId = null;
+    if (focusedBookId) {
+      activeId = focusedBookId;
+    } else if (hoveredBookId) {
+      const lastExit = hoverCooldowns.get(hoveredBookId) || 0;
+      if (now - lastExit > COOLDOWN_MS) {
+        activeId = hoveredBookId;
+      }
+    }
+    const targetStrength = orderRevealEnabled && activeId ? 1 : 0;
+    orderRevealStrength = mix(orderRevealStrength, targetStrength, 0.1);
+    if (orderRevealStrength > 1e-3 || targetStrength > 0) {
+      if (activeId && bookIdToIndex.has(activeId)) {
+        activeBookIndex = bookIdToIndex.get(activeId);
+      }
+      if (starPoints && starPoints.material) {
+        const m = starPoints.material;
+        if (m.uniforms.uActiveBookIndex) m.uniforms.uActiveBookIndex.value = activeBookIndex;
+        if (m.uniforms.uOrderRevealStrength) m.uniforms.uOrderRevealStrength.value = orderRevealStrength;
+      }
+    }
+    let panX = 0;
+    let panY = 0;
+    if (!state.isDragging && isMouseInWindow && !currentConfig?.editable) {
       const t = ENGINE_CONFIG.edgePanThreshold;
-      const speedBase = ENGINE_CONFIG.edgePanMaxSpeed * (state.fov / ENGINE_CONFIG.defaultFov);
-      let panX = 0;
-      let panY = 0;
-      if (mouseNDC.x < -1 + t) {
-        const s = (-1 + t - mouseNDC.x) / t;
-        panX = -s * s * speedBase;
-      } else if (mouseNDC.x > 1 - t) {
-        const s = (mouseNDC.x - (1 - t)) / t;
-        panX = s * s * speedBase;
-      }
-      if (mouseNDC.y < -1 + t) {
-        const s = (-1 + t - mouseNDC.y) / t;
-        panY = -s * s * speedBase;
-      } else if (mouseNDC.y > 1 - t) {
-        const s = (mouseNDC.y - (1 - t)) / t;
-        panY = s * s * speedBase;
-      }
-      if (Math.abs(panX) > 0 || Math.abs(panY) > 0) {
-        state.lon += panX;
-        state.lat += panY;
-        state.targetLon = state.lon;
-        state.targetLat = state.lat;
+      const inZoneX = mouseNDC.x < -1 + t || mouseNDC.x > 1 - t;
+      const inZoneY = mouseNDC.y < -1 + t || mouseNDC.y > 1 - t;
+      if (inZoneX || inZoneY) {
+        if (edgeHoverStart === 0) edgeHoverStart = performance.now();
+        if (performance.now() - edgeHoverStart > ENGINE_CONFIG.edgePanDelay) {
+          const speedBase = ENGINE_CONFIG.edgePanMaxSpeed * (state.fov / ENGINE_CONFIG.defaultFov);
+          if (mouseNDC.x < -1 + t) {
+            const s = (-1 + t - mouseNDC.x) / t;
+            panX = -s * s * speedBase;
+          } else if (mouseNDC.x > 1 - t) {
+            const s = (mouseNDC.x - (1 - t)) / t;
+            panX = s * s * speedBase;
+          }
+          if (mouseNDC.y < -1 + t) {
+            const s = (-1 + t - mouseNDC.y) / t;
+            panY = -s * s * speedBase;
+          } else if (mouseNDC.y > 1 - t) {
+            const s = (mouseNDC.y - (1 - t)) / t;
+            panY = s * s * speedBase;
+          }
+        }
       } else {
-        state.lon += state.velocityX;
-        state.lat += state.velocityY;
-        state.velocityX *= ENGINE_CONFIG.inertiaDamping;
-        state.velocityY *= ENGINE_CONFIG.inertiaDamping;
-        if (Math.abs(state.velocityX) < 1e-6) state.velocityX = 0;
-        if (Math.abs(state.velocityY) < 1e-6) state.velocityY = 0;
+        edgeHoverStart = 0;
       }
+    } else {
+      edgeHoverStart = 0;
+    }
+    if (Math.abs(panX) > 0 || Math.abs(panY) > 0) {
+      state.lon += panX;
+      state.lat += panY;
+      state.targetLon = state.lon;
+      state.targetLat = state.lat;
     } else if (!state.isDragging) {
       state.lon += state.velocityX;
       state.lat += state.velocityY;
       state.velocityX *= ENGINE_CONFIG.inertiaDamping;
       state.velocityY *= ENGINE_CONFIG.inertiaDamping;
+      if (Math.abs(state.velocityX) < 1e-6) state.velocityX = 0;
+      if (Math.abs(state.velocityY) < 1e-6) state.velocityY = 0;
     }
     state.lat = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, state.lat));
     const y = Math.sin(state.lat);
     const r = Math.cos(state.lat);
     const x = r * Math.sin(state.lon);
     const z = -r * Math.cos(state.lon);
-    const target = new THREE4.Vector3(x, y, z);
-    const idealUp = new THREE4.Vector3(-Math.sin(state.lat) * Math.sin(state.lon), Math.cos(state.lat), Math.sin(state.lat) * Math.cos(state.lon)).normalize();
+    const target = new THREE5.Vector3(x, y, z);
+    const idealUp = new THREE5.Vector3(-Math.sin(state.lat) * Math.sin(state.lon), Math.cos(state.lat), Math.sin(state.lat) * Math.cos(state.lon)).normalize();
     camera.up.lerp(idealUp, ENGINE_CONFIG.horizonLockStrength);
     camera.up.normalize();
     camera.lookAt(target);
+    camera.updateMatrixWorld();
+    camera.matrixWorldInverse.copy(camera.matrixWorld).invert();
     updateUniforms();
-    const cameraDir = new THREE4.Vector3();
-    camera.getWorldDirection(cameraDir);
-    const objPos = new THREE4.Vector3();
-    const objDir = new THREE4.Vector3();
-    const SHOW_LABELS_FOV = 60;
+    constellationLayer.update(state.fov, currentConfig?.showConstellationArt ?? false);
+    backdropGroup.visible = currentConfig?.showBackdropStars ?? true;
+    if (atmosphereMesh) atmosphereMesh.visible = currentConfig?.showAtmosphere ?? false;
+    const DIVISION_THRESHOLD = 60;
+    const showDivisions = state.fov > DIVISION_THRESHOLD;
+    if (constellationLines) {
+      constellationLines.visible = currentConfig?.showConstellationLines ?? false;
+    }
+    if (boundaryLines) {
+      boundaryLines.visible = currentConfig?.showDivisionBoundaries ?? false;
+    }
+    const rect = renderer.domElement.getBoundingClientRect();
+    const screenW = rect.width;
+    const screenH = rect.height;
+    const aspect = screenW / screenH;
+    const labelsToCheck = [];
+    const occupied = [];
+    function isOverlapping(x2, y2, w, h) {
+      for (const r2 of occupied) {
+        if (x2 < r2.x + r2.w && x2 + w > r2.x && y2 < r2.y + r2.h && y2 + h > r2.y) return true;
+      }
+      return false;
+    }
+    const showBookLabels = currentConfig?.showBookLabels === true;
+    const showDivisionLabels = currentConfig?.showDivisionLabels === true;
+    const showChapterLabels = currentConfig?.showChapterLabels === true;
+    const showGroupLabels = currentConfig?.showGroupLabels === true;
+    const showBooks = state.fov < 120;
+    const showChapters = state.fov < 70;
     for (const item of dynamicLabels) {
       const uniforms = item.obj.material.uniforms;
-      let targetAlpha = 0;
-      if (state.fov < SHOW_LABELS_FOV) {
-        item.obj.getWorldPosition(objPos);
-        objDir.subVectors(objPos, camera.position).normalize();
-        const dot = cameraDir.dot(objDir);
-        const fullVisibleDot = 0.98;
-        const invisibleDot = 0.9;
-        let gazeOpacity = 0;
-        if (dot >= fullVisibleDot) gazeOpacity = 1;
-        else if (dot > invisibleDot) gazeOpacity = (dot - invisibleDot) / (fullVisibleDot - invisibleDot);
-        const zoomFactor = 1 - THREE4.MathUtils.smoothstep(40, SHOW_LABELS_FOV, state.fov);
-        targetAlpha = gazeOpacity * zoomFactor;
-      }
-      if (uniforms.uAlpha) {
-        uniforms.uAlpha.value = THREE4.MathUtils.lerp(uniforms.uAlpha.value, targetAlpha, 0.1);
+      const level = item.node.level;
+      let isEnabled = false;
+      if (level === 2 && showBookLabels) isEnabled = true;
+      else if (level === 1 && showDivisionLabels) isEnabled = true;
+      else if (level === 3 && showChapterLabels) isEnabled = true;
+      else if (level === 2.5 && showGroupLabels) isEnabled = true;
+      if (!isEnabled) {
+        uniforms.uAlpha.value = THREE5.MathUtils.lerp(uniforms.uAlpha.value, 0, 0.2);
         item.obj.visible = uniforms.uAlpha.value > 0.01;
+        continue;
       }
+      const pWorld = item.obj.position;
+      const pProj = smartProjectJS(pWorld);
+      if (pProj.z > 0.2) {
+        uniforms.uAlpha.value = THREE5.MathUtils.lerp(uniforms.uAlpha.value, 0, 0.2);
+        item.obj.visible = uniforms.uAlpha.value > 0.01;
+        continue;
+      }
+      if (level === 2 && !showBooks && item.node.id !== state.draggedNodeId) {
+        uniforms.uAlpha.value = THREE5.MathUtils.lerp(uniforms.uAlpha.value, 0, 0.2);
+        item.obj.visible = uniforms.uAlpha.value > 0.01;
+        continue;
+      }
+      if ((level === 3 || level === 2.5) && !showChapters && item.node.id !== state.draggedNodeId) {
+        uniforms.uAlpha.value = THREE5.MathUtils.lerp(uniforms.uAlpha.value, 0, 0.2);
+        item.obj.visible = uniforms.uAlpha.value > 0.01;
+        continue;
+      }
+      const ndcX = pProj.x * globalUniforms.uScale.value / aspect;
+      const ndcY = pProj.y * globalUniforms.uScale.value;
+      const sX = (ndcX * 0.5 + 0.5) * screenW;
+      const sY = (-ndcY * 0.5 + 0.5) * screenH;
+      const size = uniforms.uSize.value;
+      const pixelH = size.y * screenH * 0.8;
+      const pixelW = size.x * screenH * 0.8;
+      labelsToCheck.push({ item, sX, sY, w: pixelW, h: pixelH, uniforms, level, ndcX, ndcY });
+    }
+    const hoverId = handlers._lastHoverId;
+    const selectedId = state.draggedNodeId;
+    labelsToCheck.sort((a, b) => {
+      const getScore = (l) => {
+        if (l.item.node.id === selectedId) return 10;
+        if (l.item.node.id === hoverId) return 9;
+        const level = l.level;
+        if (level === 2) return 5;
+        if (level === 1) return showDivisions ? 6 : 1;
+        return 0;
+      };
+      return getScore(b) - getScore(a);
+    });
+    for (const l of labelsToCheck) {
+      let target2 = 0;
+      const isSpecial = l.item.node.id === selectedId || l.item.node.id === hoverId;
+      if (l.level === 1) {
+        let rot = 0;
+        const blend = globalUniforms.uBlend.value;
+        if (blend > 0.5) {
+          const dx = l.sX - screenW / 2;
+          const dy = l.sY - screenH / 2;
+          rot = Math.atan2(-dy, -dx) - Math.PI / 2;
+        }
+        l.uniforms.uAngle.value = THREE5.MathUtils.lerp(l.uniforms.uAngle.value, rot, 0.1);
+      }
+      if (l.level === 2) {
+        if (showBooks || isSpecial) {
+          target2 = 1;
+          occupied.push({ x: l.sX - l.w / 2, y: l.sY - l.h / 2, w: l.w, h: l.h });
+        }
+      } else if (l.level === 1) {
+        if (showDivisions || isSpecial) {
+          const pad = -5;
+          if (!isOverlapping(l.sX - l.w / 2 - pad, l.sY - l.h / 2 - pad, l.w + pad * 2, l.h + pad * 2)) {
+            target2 = 1;
+            occupied.push({ x: l.sX - l.w / 2, y: l.sY - l.h / 2, w: l.w, h: l.h });
+          }
+        }
+      } else if (l.level === 2.5 || l.level === 3) {
+        if (showChapters || isSpecial) {
+          target2 = 1;
+          if (!isSpecial) {
+            const dist = Math.sqrt(l.ndcX * l.ndcX + l.ndcY * l.ndcY);
+            const focusFade = 1 - THREE5.MathUtils.smoothstep(0.4, 0.7, dist);
+            target2 *= focusFade;
+          }
+        }
+      }
+      l.uniforms.uAlpha.value = THREE5.MathUtils.lerp(l.uniforms.uAlpha.value, target2, 0.1);
+      l.item.obj.visible = l.uniforms.uAlpha.value > 0.01;
     }
     renderer.render(scene, camera);
   }
@@ -1301,16 +2218,31 @@ function createEngine({
   }
   function dispose() {
     stop();
+    constellationLayer.dispose();
     renderer.dispose();
     renderer.domElement.remove();
   }
-  return { setConfig, start, stop, dispose, setHandlers, getFullArrangement };
+  function setHoveredBook(id) {
+    if (id === hoveredBookId) return;
+    if (hoveredBookId) {
+      hoverCooldowns.set(hoveredBookId, performance.now());
+    }
+    hoveredBookId = id;
+  }
+  function setFocusedBook(id) {
+    focusedBookId = id;
+  }
+  function setOrderRevealEnabled(enabled) {
+    orderRevealEnabled = enabled;
+  }
+  return { setConfig, start, stop, dispose, setHandlers, getFullArrangement, setHoveredBook, setFocusedBook, setOrderRevealEnabled };
 }
-var ENGINE_CONFIG;
+var ENGINE_CONFIG, ORDER_REVEAL_CONFIG;
 var init_createEngine = __esm({
   "src/engine/createEngine.ts"() {
     init_layout();
     init_materials();
+    init_ConstellationArtworkLayer();
     ENGINE_CONFIG = {
       minFov: 10,
       maxFov: 165,
@@ -1323,16 +2255,26 @@ var init_createEngine = __esm({
       zenithStrength: 0.02,
       horizonLockStrength: 0.05,
       edgePanThreshold: 0.15,
-      edgePanMaxSpeed: 0.02
+      edgePanMaxSpeed: 0.02,
+      edgePanDelay: 250
+    };
+    ORDER_REVEAL_CONFIG = {
+      globalDim: 0.85,
+      pulseAmplitude: 0.6,
+      pulseDuration: 2,
+      delayPerChapter: 0.1
     };
   }
 });
 var StarMap = forwardRef(
-  ({ config, className, onSelect, onHover, onArrangementChange }, ref) => {
+  ({ config, className, onSelect, onHover, onArrangementChange, onFovChange }, ref) => {
     const containerRef = useRef(null);
     const engineRef = useRef(null);
     useImperativeHandle(ref, () => ({
-      getFullArrangement: () => engineRef.current?.getFullArrangement?.()
+      getFullArrangement: () => engineRef.current?.getFullArrangement?.(),
+      setHoveredBook: (id) => engineRef.current?.setHoveredBook?.(id),
+      setFocusedBook: (id) => engineRef.current?.setFocusedBook?.(id),
+      setOrderRevealEnabled: (enabled) => engineRef.current?.setOrderRevealEnabled?.(enabled)
     }));
     useEffect(() => {
       let disposed = false;
@@ -1344,7 +2286,8 @@ var StarMap = forwardRef(
           container: containerRef.current,
           onSelect,
           onHover,
-          onArrangementChange
+          onArrangementChange,
+          onFovChange
         });
         engineRef.current.setConfig(config);
         engineRef.current.start();
@@ -1360,8 +2303,8 @@ var StarMap = forwardRef(
       engineRef.current?.setConfig?.(config);
     }, [config]);
     useEffect(() => {
-      engineRef.current?.setHandlers?.({ onSelect, onHover, onArrangementChange });
-    }, [onSelect, onHover, onArrangementChange]);
+      engineRef.current?.setHandlers?.({ onSelect, onHover, onArrangementChange, onFovChange });
+    }, [onSelect, onHover, onArrangementChange, onFovChange]);
     return /* @__PURE__ */ jsx("div", { ref: containerRef, className, style: { width: "100%", height: "100%" } });
   }
 );
@@ -1390,10 +2333,11 @@ function bibleToSceneModel(data) {
       });
       links.push({ source: did, target: tid });
       for (const b of d.books) {
+        const bookLabel = b.name;
         const bid = id.book(b.key);
         nodes.push({
           id: bid,
-          label: b.name,
+          label: bookLabel,
           level: 2,
           parent: did,
           meta: { testament: t.name, division: d.name, bookKey: b.key, book: b.name }
@@ -1405,7 +2349,7 @@ function bibleToSceneModel(data) {
           const cid = id.chapter(b.key, chapterNum);
           nodes.push({
             id: cid,
-            label: `${b.name} ${chapterNum}`,
+            label: `${bookLabel} ${chapterNum}`,
             level: 3,
             parent: bid,
             weight: verseCounts[i],
@@ -30468,7 +31412,145 @@ var default_stars_default = {
     }
   ]
 };
+var defaultGenerateOptions = {
+  seed: 12345,
+  discRadius: 2e3,
+  milkyWayEnabled: true,
+  milkyWayAngle: 60,
+  milkyWayWidth: 0.3,
+  // Width in dot-product space
+  milkyWayStrength: 0.7,
+  noiseScale: 2,
+  noiseStrength: 0.4,
+  clusterSpread: 0.08
+  // Radians approx
+};
+var RNG = class {
+  seed;
+  constructor(seed) {
+    this.seed = seed;
+  }
+  // Returns 0..1
+  next() {
+    this.seed = (this.seed * 9301 + 49297) % 233280;
+    return this.seed / 233280;
+  }
+  // Returns range [min, max)
+  range(min, max) {
+    return min + this.next() * (max - min);
+  }
+  // Uniform random on upper hemisphere (y > 0)
+  randomOnSphere() {
+    const y = this.next();
+    const theta = 2 * Math.PI * this.next();
+    const r = Math.sqrt(1 - y * y);
+    const x = r * Math.cos(theta);
+    const z = r * Math.sin(theta);
+    return new THREE5.Vector3(x, y, z);
+  }
+};
+function simpleNoise3D(v, scale) {
+  const s = scale;
+  return (Math.sin(v.x * s) + Math.sin(v.y * s * 1.3) + Math.sin(v.z * s * 1.7) + Math.sin(v.x * s * 2.1 + v.y * s * 2.1) * 0.5) / 3.5;
+}
+function getDensity(v, opts, mwNormal) {
+  let density = 0.3;
+  if (opts.milkyWayEnabled) {
+    const dot = v.dot(mwNormal);
+    const dist = Math.abs(dot);
+    const band = Math.exp(-(dist * dist) / (opts.milkyWayWidth * opts.milkyWayWidth));
+    density += band * opts.milkyWayStrength;
+  }
+  const noise = simpleNoise3D(v, opts.noiseScale);
+  density *= 1 + noise * opts.noiseStrength;
+  return Math.max(0.01, density);
+}
+function generateArrangement(bible, options = {}) {
+  const opts = { ...defaultGenerateOptions, ...options };
+  const rng = new RNG(opts.seed);
+  const arrangement = {};
+  const books = [];
+  bible.testaments.forEach((t) => {
+    t.divisions.forEach((d) => {
+      d.books.forEach((b) => {
+        books.push({
+          key: b.key,
+          name: b.name,
+          chapters: b.chapters,
+          division: d.name,
+          testament: t.name
+        });
+      });
+    });
+  });
+  const bookCount = books.length;
+  const mwRad = THREE5.MathUtils.degToRad(opts.milkyWayAngle);
+  const mwNormal = new THREE5.Vector3(Math.sin(mwRad), Math.cos(mwRad), 0).normalize();
+  const anchors = [];
+  for (let i = 0; i < bookCount; i++) {
+    let bestP = new THREE5.Vector3();
+    let valid = false;
+    let attempt = 0;
+    while (!valid && attempt < 100) {
+      const p = rng.randomOnSphere();
+      const d = getDensity(p, opts, mwNormal);
+      if (rng.next() < d) {
+        bestP = p;
+        valid = true;
+      }
+      attempt++;
+    }
+    if (!valid) bestP = rng.randomOnSphere();
+    anchors.push(bestP);
+  }
+  anchors.sort((a, b) => {
+    const lonA = Math.atan2(a.z, a.x);
+    const lonB = Math.atan2(b.z, b.x);
+    return lonA - lonB;
+  });
+  books.forEach((book, i) => {
+    const anchor = anchors[i];
+    const anchorPos = anchor.clone().multiplyScalar(opts.discRadius);
+    arrangement[`B:${book.key}`] = { position: [anchorPos.x, anchorPos.y, anchorPos.z] };
+    for (let c = 0; c < book.chapters; c++) {
+      const localSpread = opts.clusterSpread * (0.8 + rng.next() * 0.4);
+      const offset = new THREE5.Vector3(
+        (rng.next() - 0.5) * 2,
+        (rng.next() - 0.5) * 2,
+        (rng.next() - 0.5) * 2
+      ).normalize().multiplyScalar(rng.next() * localSpread);
+      const starDir = anchor.clone().add(offset).normalize();
+      if (starDir.y < 0.01) {
+        starDir.y = 0.01;
+        starDir.normalize();
+      }
+      const starPos = starDir.multiplyScalar(opts.discRadius);
+      const chapId = `C:${book.key}:${c + 1}`;
+      arrangement[chapId] = { position: [starPos.x, starPos.y, starPos.z] };
+    }
+  });
+  const divisions = /* @__PURE__ */ new Map();
+  books.forEach((book, i) => {
+    const anchor = anchors[i];
+    const anchorPos = anchor.clone().multiplyScalar(opts.discRadius);
+    const divId = `D:${book.testament}:${book.division}`;
+    if (!divisions.has(divId)) {
+      divisions.set(divId, { sum: new THREE5.Vector3(), count: 0 });
+    }
+    const entry = divisions.get(divId);
+    entry.sum.add(anchorPos);
+    entry.count++;
+  });
+  divisions.forEach((val, key) => {
+    if (val.count > 0) {
+      val.sum.divideScalar(val.count);
+      val.sum.normalize().multiplyScalar(opts.discRadius * 0.9);
+      arrangement[key] = { position: [val.sum.x, val.sum.y, val.sum.z] };
+    }
+  });
+  return arrangement;
+}
 
-export { StarMap, bibleToSceneModel, default_stars_default as defaultStars };
+export { StarMap, bibleToSceneModel, defaultGenerateOptions, default_stars_default as defaultStars, generateArrangement };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map