@project-skymap/library 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -341,45 +341,60 @@ var init_shaders = __esm({
 uniform float uScale;
 uniform float uAspect;
 uniform float uBlend;
+uniform int uProjectionType;
 
 vec4 smartProject(vec4 viewPos) {
     vec3 dir = normalize(viewPos.xyz);
     float dist = length(viewPos.xyz);
-    float zLinear = max(0.01, -dir.z);
-    float kStereo = 2.0 / (1.0 - dir.z);
-    float kLinear = 1.0 / zLinear;
-    float k = mix(kLinear, kStereo, uBlend);
-    vec2 projected = vec2(k * dir.x, k * dir.y);
-    projected *= uScale;
-    projected.x /= uAspect;
-    float zMetric = -1.0 + (dist / 15000.0);
-    
+    float k;
+
     // 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(escapePos, 10.0, 1.0);
-    // Clip very close points in linear mode
-    if (uBlend < 0.1 && dir.z > -0.1) return vec4(escapePos, 10.0, 1.0);
-    
+    if (uProjectionType == 0) {
+        // Perspective
+        if (dir.z > -0.1) return vec4(escapePos, 10.0, 1.0);
+        k = 1.0 / max(0.01, -dir.z);
+    } else if (uProjectionType == 1) {
+        // Stereographic \u2014 tighter clip to prevent stretch near singularity
+        if (dir.z > 0.1) return vec4(escapePos, 10.0, 1.0);
+        k = 2.0 / (1.0 - dir.z);
+    } else {
+        // Blended (auto-blend behavior)
+        float zLinear = max(0.01, -dir.z);
+        float kStereo = 2.0 / (1.0 - dir.z);
+        float kLinear = 1.0 / zLinear;
+        k = mix(kLinear, kStereo, uBlend);
+
+        // Tighter clip threshold that scales with blend factor
+        float clipZ = mix(-0.1, 0.1, uBlend);
+        if (dir.z > clipZ) return vec4(escapePos, 10.0, 1.0);
+    }
+
+    vec2 projected = vec2(k * dir.x, k * dir.y);
+    projected *= uScale;
+    projected.x /= uAspect;
+    float zMetric = -1.0 + (dist / 15000.0);
+
     return vec4(projected, zMetric, 1.0);
 }
 `;
     MASK_CHUNK = `
 uniform float uAspect;
 uniform float uBlend;
+uniform int uProjectionType;
 varying vec2 vScreenPos;
 float getMaskAlpha() {
-    if (uBlend < 0.1) return 1.0;
+    // No artificial circular mask \u2014 the horizon, atmosphere, and ground
+    // define the dome boundary naturally (as Stellarium does).
+    // Only apply a minimal edge softening to catch stray back-face artifacts.
     vec2 p = vScreenPos;
     p.x *= uAspect;
     float dist = length(p);
-    float t = smoothstep(0.75, 1.0, uBlend);
-    float currentRadius = mix(2.5, 1.0, t);
-    float edgeSoftness = mix(0.5, 0.02, t);
-    return 1.0 - smoothstep(currentRadius - edgeSoftness, currentRadius, dist);
+    // Gentle falloff only at extreme screen edges (beyond NDC ~1.8)
+    return 1.0 - smoothstep(1.8, 2.0, dist);
 }
 `;
   }
@@ -412,13 +427,15 @@ var init_materials = __esm({
       uScale: { value: 1 },
       uAspect: { value: 1 },
       uBlend: { value: 0 },
+      uProjectionType: { value: 2 },
+      // 0=perspective, 1=stereographic, 2=blended
       uTime: { value: 0 },
       // Atmosphere Settings
       uAtmGlow: { value: 1 },
       uAtmDark: { value: 0.6 },
       uAtmExtinction: { value: 4 },
       uAtmTwinkle: { value: 0.8 },
-      uColorHorizon: { value: new THREE5__namespace.Color(2768476) },
+      uColorHorizon: { value: new THREE5__namespace.Color(3825292) },
       uColorZenith: { value: new THREE5__namespace.Color(132104) }
     };
   }
@@ -617,6 +634,10 @@ var init_ConstellationArtworkLayer = __esm({
           this.items.push({ config: c, mesh, material, baseOpacity: c.opacity });
         });
       }
+      _globalOpacity = 1;
+      setGlobalOpacity(v) {
+        this._globalOpacity = v;
+      }
       update(fov, showArt) {
         this.root.visible = showArt;
         if (!showArt) return;
@@ -631,7 +652,7 @@ var init_ConstellationArtworkLayer = __esm({
             const t = (fade.zoomInStart - fov) / (fade.zoomInStart - fade.zoomInEnd);
             opacity = THREE5__namespace.MathUtils.lerp(fade.maxOpacity, fade.minOpacity, t);
           }
-          opacity = Math.min(Math.max(opacity, 0), 1);
+          opacity = Math.min(Math.max(opacity, 0), 1) * this._globalOpacity;
           item.material.uniforms.uOpacity.value = opacity;
         }
       }
@@ -657,6 +678,167 @@ var init_ConstellationArtworkLayer = __esm({
   }
 });
 
+// src/engine/projections.ts
+var PerspectiveProjection, StereographicProjection, BlendedProjection; exports.PROJECTIONS = void 0;
+var init_projections = __esm({
+  "src/engine/projections.ts"() {
+    PerspectiveProjection = class {
+      id = "perspective";
+      label = "Perspective";
+      maxFov = 160;
+      glslProjectionType = 0;
+      forward(dir) {
+        if (dir.z > -0.1) return null;
+        const k = 1 / Math.max(0.01, -dir.z);
+        return { x: k * dir.x, y: k * dir.y, z: dir.z };
+      }
+      inverse(uvX, uvY, fovRad) {
+        const halfHeight = Math.tan(fovRad / 2);
+        const r = Math.sqrt(uvX * uvX + uvY * uvY);
+        const theta = Math.atan(r * halfHeight);
+        const phi = Math.atan2(uvY, uvX);
+        const sinT = Math.sin(theta);
+        return {
+          x: sinT * Math.cos(phi),
+          y: sinT * Math.sin(phi),
+          z: -Math.cos(theta)
+        };
+      }
+      getScale(fovRad) {
+        return 1 / Math.tan(fovRad / 2);
+      }
+      isClipped(dirZ) {
+        return dirZ > -0.1;
+      }
+    };
+    StereographicProjection = class {
+      id = "stereographic";
+      label = "Stereographic";
+      maxFov = 360;
+      glslProjectionType = 1;
+      forward(dir) {
+        if (dir.z > 0.4) return null;
+        const k = 2 / (1 - dir.z);
+        return { x: k * dir.x, y: k * dir.y, z: dir.z };
+      }
+      inverse(uvX, uvY, fovRad) {
+        const halfHeight = 2 * Math.tan(fovRad / 4);
+        const r = Math.sqrt(uvX * uvX + uvY * uvY);
+        const theta = 2 * Math.atan(r * halfHeight / 2);
+        const phi = Math.atan2(uvY, uvX);
+        const sinT = Math.sin(theta);
+        return {
+          x: sinT * Math.cos(phi),
+          y: sinT * Math.sin(phi),
+          z: -Math.cos(theta)
+        };
+      }
+      getScale(fovRad) {
+        return 1 / (2 * Math.tan(fovRad / 4));
+      }
+      isClipped(dirZ) {
+        return dirZ > 0.4;
+      }
+    };
+    BlendedProjection = class {
+      id = "blended";
+      label = "Blended (Auto)";
+      maxFov = 165;
+      glslProjectionType = 2;
+      /** FOV thresholds for blend transition (degrees) */
+      blendStart;
+      blendEnd;
+      /** Current blend factor, updated via setFov() */
+      blend = 0;
+      constructor(blendStart = 40, blendEnd = 100) {
+        this.blendStart = blendStart;
+        this.blendEnd = blendEnd;
+      }
+      /** Call this each frame / when FOV changes so forward/inverse stay in sync */
+      setFov(fovDeg) {
+        if (fovDeg <= this.blendStart) {
+          this.blend = 0;
+          return;
+        }
+        if (fovDeg >= this.blendEnd) {
+          this.blend = 1;
+          return;
+        }
+        const t = (fovDeg - this.blendStart) / (this.blendEnd - this.blendStart);
+        this.blend = t * t * (3 - 2 * t);
+      }
+      getBlend() {
+        return this.blend;
+      }
+      forward(dir) {
+        if (this.blend > 0.5 && dir.z > 0.4) return null;
+        if (this.blend < 0.1 && dir.z > -0.1) return null;
+        const kLinear = 1 / Math.max(0.01, -dir.z);
+        const kStereo = 2 / (1 - dir.z);
+        const k = kLinear * (1 - this.blend) + kStereo * this.blend;
+        return { x: k * dir.x, y: k * dir.y, z: dir.z };
+      }
+      inverse(uvX, uvY, fovRad) {
+        const r = Math.sqrt(uvX * uvX + uvY * uvY);
+        const halfHeightLin = Math.tan(fovRad / 2);
+        const thetaLin = Math.atan(r * halfHeightLin);
+        const halfHeightStereo = 2 * Math.tan(fovRad / 4);
+        const thetaStereo = 2 * Math.atan(r * halfHeightStereo / 2);
+        const theta = thetaLin * (1 - this.blend) + thetaStereo * this.blend;
+        const phi = Math.atan2(uvY, uvX);
+        const sinT = Math.sin(theta);
+        return {
+          x: sinT * Math.cos(phi),
+          y: sinT * Math.sin(phi),
+          z: -Math.cos(theta)
+        };
+      }
+      getScale(fovRad) {
+        const scaleLinear = 1 / Math.tan(fovRad / 2);
+        const scaleStereo = 1 / (2 * Math.tan(fovRad / 4));
+        return scaleLinear * (1 - this.blend) + scaleStereo * this.blend;
+      }
+      isClipped(dirZ) {
+        if (this.blend > 0.5) return dirZ > 0.4;
+        if (this.blend < 0.1) return dirZ > -0.1;
+        return false;
+      }
+    };
+    exports.PROJECTIONS = {
+      perspective: () => new PerspectiveProjection(),
+      stereographic: () => new StereographicProjection()
+    };
+  }
+});
+
+// src/engine/fader.ts
+var Fader;
+var init_fader = __esm({
+  "src/engine/fader.ts"() {
+    Fader = class {
+      target = false;
+      value = 0;
+      duration;
+      constructor(duration = 0.3) {
+        this.duration = duration;
+      }
+      update(dt) {
+        const goal = this.target ? 1 : 0;
+        if (this.value === goal) return;
+        const speed = 1 / this.duration;
+        const step = speed * dt;
+        const diff = goal - this.value;
+        this.value += Math.sign(diff) * Math.min(step, Math.abs(diff));
+      }
+      /** Smoothstep-eased value for perceptually smooth transitions */
+      get eased() {
+        const v = this.value;
+        return v * v * (3 - 2 * v);
+      }
+    };
+  }
+});
+
 // src/engine/createEngine.ts
 var createEngine_exports = {};
 __export(createEngine_exports, {
@@ -674,9 +856,21 @@ function createEngine({
   let orderRevealEnabled = true;
   let activeBookIndex = -1;
   let orderRevealStrength = 0;
+  let flyToActive = false;
+  let flyToTargetLon = 0;
+  let flyToTargetLat = 0;
+  let flyToTargetFov = ENGINE_CONFIG.minFov;
+  const FLY_TO_SPEED = 0.04;
+  let currentFilter = null;
+  let filterStrength = 0;
+  let filterTestamentIndex = -1;
+  let filterDivisionIndex = -1;
+  let filterBookIndex = -1;
   const hoverCooldowns = /* @__PURE__ */ new Map();
   const COOLDOWN_MS = 2e3;
   const bookIdToIndex = /* @__PURE__ */ new Map();
+  const testamentToIndex = /* @__PURE__ */ new Map();
+  const divisionToIndex = /* @__PURE__ */ new Map();
   const renderer = new THREE5__namespace.WebGLRenderer({ antialias: true, alpha: false });
   renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
   renderer.setSize(container.clientWidth, container.clientHeight);
@@ -715,10 +909,21 @@ function createEngine({
     draggedStarIndex: -1,
     draggedDist: 2e3,
     draggedGroup: null,
-    tempArrangement: {}
+    tempArrangement: {},
+    // Touch state
+    touchCount: 0,
+    touchStartTime: 0,
+    touchStartX: 0,
+    touchStartY: 0,
+    touchMoved: false,
+    pinchStartDistance: 0,
+    pinchStartFov: ENGINE_CONFIG.defaultFov,
+    pinchCenterX: 0,
+    pinchCenterY: 0
   };
   const mouseNDC = new THREE5__namespace.Vector2();
   let isMouseInWindow = false;
+  let isTouchDevice = false;
   let edgeHoverStart = 0;
   let handlers = { onSelect, onHover, onArrangementChange, onFovChange };
   let currentConfig;
@@ -726,68 +931,53 @@ function createEngine({
   function mix(a, b, t) {
     return a * (1 - t) + b * t;
   }
-  function getBlendFactor(fov) {
-    if (fov <= ENGINE_CONFIG.blendStart) return 0;
-    if (fov >= ENGINE_CONFIG.blendEnd) return 1;
-    let t = (fov - ENGINE_CONFIG.blendStart) / (ENGINE_CONFIG.blendEnd - ENGINE_CONFIG.blendStart);
-    return t * t * (3 - 2 * t);
+  let currentProjection = new BlendedProjection(ENGINE_CONFIG.blendStart, ENGINE_CONFIG.blendEnd);
+  function syncProjectionState() {
+    if (currentProjection instanceof BlendedProjection) {
+      currentProjection.setFov(state.fov);
+      globalUniforms.uBlend.value = currentProjection.getBlend();
+    }
+    globalUniforms.uProjectionType.value = currentProjection.glslProjectionType;
   }
   function updateUniforms() {
-    const blend = getBlendFactor(state.fov);
-    globalUniforms.uBlend.value = blend;
+    syncProjectionState();
     const fovRad = state.fov * Math.PI / 180;
-    const scaleLinear = 1 / Math.tan(fovRad / 2);
-    const scaleStereo = 1 / (2 * Math.tan(fovRad / 4));
-    globalUniforms.uScale.value = mix(scaleLinear, scaleStereo, blend);
-    globalUniforms.uAspect.value = camera.aspect;
+    let scale = currentProjection.getScale(fovRad);
+    const aspect = camera.aspect;
+    if (currentConfig?.fitProjection) {
+      if (aspect > 1) {
+        scale /= aspect;
+      }
+    }
+    globalUniforms.uScale.value = scale;
+    globalUniforms.uAspect.value = aspect;
     camera.fov = Math.min(state.fov, ENGINE_CONFIG.defaultFov);
     camera.updateProjectionMatrix();
   }
   function getMouseViewVector(fovDeg, aspectRatio) {
-    const blend = getBlendFactor(fovDeg);
+    syncProjectionState();
     const fovRad = fovDeg * Math.PI / 180;
     const uvX = mouseNDC.x * aspectRatio;
     const uvY = mouseNDC.y;
-    const r_uv = Math.sqrt(uvX * uvX + uvY * uvY);
-    const halfHeightLinear = Math.tan(fovRad / 2);
-    const theta_lin = Math.atan(r_uv * halfHeightLinear);
-    const halfHeightStereo = 2 * Math.tan(fovRad / 4);
-    const theta_str = 2 * Math.atan(r_uv * halfHeightStereo / 2);
-    const theta = mix(theta_lin, theta_str, blend);
-    const phi = Math.atan2(uvY, uvX);
-    const sinTheta = Math.sin(theta);
-    const cosTheta = Math.cos(theta);
-    return new THREE5__namespace.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
+    const v = currentProjection.inverse(uvX, uvY, fovRad);
+    return new THREE5__namespace.Vector3(v.x, v.y, v.z).normalize();
   }
   function getMouseWorldVector(pixelX, pixelY, width, height) {
     const aspect = width / height;
     const ndcX = pixelX / width * 2 - 1;
     const ndcY = -(pixelY / height) * 2 + 1;
-    const blend = getBlendFactor(state.fov);
+    syncProjectionState();
     const fovRad = state.fov * Math.PI / 180;
-    const uvX = ndcX * aspect;
-    const uvY = ndcY;
-    const r_uv = Math.sqrt(uvX * uvX + uvY * uvY);
-    const halfHeightLinear = Math.tan(fovRad / 2);
-    const theta_lin = Math.atan(r_uv * halfHeightLinear);
-    const halfHeightStereo = 2 * Math.tan(fovRad / 4);
-    const theta_str = 2 * Math.atan(r_uv * halfHeightStereo / 2);
-    const theta = mix(theta_lin, theta_str, blend);
-    const phi = Math.atan2(uvY, uvX);
-    const sinTheta = Math.sin(theta);
-    const cosTheta = Math.cos(theta);
-    const vView = new THREE5__namespace.Vector3(sinTheta * Math.cos(phi), sinTheta * Math.sin(phi), -cosTheta).normalize();
+    const v = currentProjection.inverse(ndcX * aspect, ndcY, fovRad);
+    const vView = new THREE5__namespace.Vector3(v.x, v.y, v.z).normalize();
     return vView.applyQuaternion(camera.quaternion);
   }
   function smartProjectJS(worldPos) {
     const viewPos = worldPos.clone().applyMatrix4(camera.matrixWorldInverse);
     const dir = viewPos.clone().normalize();
-    const zLinear = Math.max(0.01, -dir.z);
-    const kStereo = 2 / (1 - dir.z);
-    const kLinear = 1 / zLinear;
-    const blend = globalUniforms.uBlend.value;
-    const k = mix(kLinear, kStereo, blend);
-    return { x: k * dir.x, y: k * dir.y, z: dir.z };
+    const result = currentProjection.forward(dir);
+    if (!result) return { x: 0, y: 0, z: dir.z };
+    return result;
   }
   const groundGroup = new THREE5__namespace.Group();
   scene.add(groundGroup);
@@ -797,10 +987,8 @@ function createEngine({
     const geometry = new THREE5__namespace.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 THREE5__namespace.Color(131587) },
-        // Very dark almost black
-        fogColor: { value: new THREE5__namespace.Color(331812) }
-        // Matches atmosphere bot color
+        color: { value: new THREE5__namespace.Color(65794) },
+        fogColor: { value: new THREE5__namespace.Color(663098) }
       },
       vertexShaderBody: `
                 varying vec3 vPos; 
@@ -826,24 +1014,30 @@ function createEngine({
                     // Procedural Horizon (Mountains)
                     float angle = atan(vPos.z, vPos.x);
                     
-                    // Simple FBM-like terrain
+                    // FBM-like terrain with increased amplitude
                     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;
-                    
+                    h += sin(angle * 6.0) * 35.0;
+                    h += sin(angle * 13.0 + 1.0) * 18.0;
+                    h += sin(angle * 29.0 + 2.0) * 8.0;
+                    h += sin(angle * 63.0 + 4.0) * 3.0;
+                    h += sin(angle * 97.0 + 5.0) * 1.5;
+
+                    float terrainHeight = h + 12.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);
-                    
+
+                    // Atmospheric rim glow just below terrain peaks
+                    float rimDist = terrainHeight - vPos.y;
+                    float rim = exp(-rimDist * 0.15) * 0.4;
+                    vec3 rimColor = fogColor * 1.5;
+
+                    // Atmospheric haze \u2014 stronger near horizon
+                    float fogFactor = smoothstep(-120.0, terrainHeight, vPos.y);
+                    vec3 finalCol = mix(color, fogColor, fogFactor * 0.6);
+
+                    // Add rim glow near terrain peaks
+                    finalCol += rimColor * rim;
+
                     gl_FragColor = vec4(finalCol, 1.0); 
                 }
             `,
@@ -881,19 +1075,25 @@ function createEngine({
 
                     // 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);
-                    
+
+                    // 1. Base gradient from Horizon to Zenith (wider range)
+                    float t = smoothstep(-0.15, 0.7, 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
+
+                    // 2. Teal tint at mid-altitudes (subtle colour variation)
+                    float midBand = exp(-6.0 * pow(h - 0.3, 2.0));
+                    skyColor += vec3(0.05, 0.12, 0.15) * midBand * uAtmGlow;
+
+                    // 3. Primary horizon glow band (wider than before)
+                    float horizonBand = exp(-10.0 * abs(h - 0.02));
                     skyColor += uColorHorizon * horizonBand * 0.5 * uAtmGlow;
 
+                    // 4. Warm secondary glow (light pollution / sodium scatter)
+                    float warmGlow = exp(-8.0 * abs(h));
+                    skyColor += vec3(0.4, 0.25, 0.15) * warmGlow * 0.3 * uAtmGlow;
+
                     gl_FragColor = vec4(skyColor, 1.0);
                 }
             `,
@@ -931,7 +1131,24 @@ function createEngine({
       positions.push(x, y, z);
       const size = 1 + -Math.log(Math.random()) * 0.8 * 1.5;
       sizes.push(size);
-      colors.push(1, 1, 1);
+      const temp = Math.random();
+      let cr, cg, cb;
+      if (temp < 0.15) {
+        cr = 0.7 + temp * 2;
+        cg = 0.8 + temp;
+        cb = 1;
+      } else if (temp < 0.6) {
+        const t = (temp - 0.15) / 0.45;
+        cr = 1;
+        cg = 1 - t * 0.1;
+        cb = 1 - t * 0.3;
+      } else {
+        const t = (temp - 0.6) / 0.4;
+        cr = 1;
+        cg = 0.85 - t * 0.35;
+        cb = 0.7 - t * 0.35;
+      }
+      colors.push(cr, cg, cb);
     }
     geometry.setAttribute("position", new THREE5__namespace.Float32BufferAttribute(positions, 3));
     geometry.setAttribute("size", new THREE5__namespace.Float32BufferAttribute(sizes, 1));
@@ -939,51 +1156,60 @@ function createEngine({
     const material = createSmartMaterial({
       uniforms: {
         pixelRatio: { value: renderer.getPixelRatio() },
-        uScale: globalUniforms.uScale
+        uScale: globalUniforms.uScale,
+        uTime: globalUniforms.uTime
       },
       vertexShaderBody: `
-                attribute float size; 
-                attribute vec3 color; 
-                varying vec3 vColor; 
-                uniform float pixelRatio; 
-                
+                attribute float size;
+                attribute vec3 color;
+                varying vec3 vColor;
+                uniform float pixelRatio;
+
                 uniform float uAtmExtinction;
+                uniform float uAtmTwinkle;
+                uniform float uTime;
 
-                void main() { 
+                void main() {
                     vec3 nPos = normalize(position);
                     float altitude = nPos.y;
-                    
-                    // Simple Extinction & Horizon Fade
+
+                    // 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;
+                    // Scintillation (twinkling) \u2014 stronger near horizon
+                    float turbulence = 1.0 + (1.0 - smoothstep(0.0, 1.0, altitude)) * 2.0;
+                    float twinkle = sin(uTime * 3.0 + position.x * 0.05 + position.z * 0.03) * 0.5 + 0.5;
+                    float scintillation = mix(1.0, twinkle * 2.0, uAtmTwinkle * 0.4 * turbulence);
 
-                    vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); 
-                    gl_Position = smartProject(mvPosition); 
-                    vScreenPos = gl_Position.xy / gl_Position.w; 
-                    
-                    // 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; 
+                    vColor = color * 3.0 * extinction * horizonFade * scintillation;
+
+                    vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
+                    gl_Position = smartProject(mvPosition);
+                    vScreenPos = gl_Position.xy / gl_Position.w;
+
+                    float zoomScale = pow(uScale, 0.5);
+                    float perceptualSize = pow(size, 0.55);
+                    gl_PointSize = clamp(perceptualSize * zoomScale * 0.5 * pixelRatio * (800.0 / -mvPosition.z) * horizonFade, 0.5, 20.0);
                 }
             `,
       fragmentShader: `
-                varying vec3 vColor; 
-                void main() { 
-                    vec2 coord = gl_PointCoord - vec2(0.5); 
-                    float dist = length(coord) * 2.0; 
-                    if (dist > 1.0) discard; 
-                    float alphaMask = getMaskAlpha(); 
-                    if (alphaMask < 0.01) discard; 
-                    
-                    // Sharp falloff for intense point look
-                    float alpha = exp(-4.0 * dist * dist);
-                    gl_FragColor = vec4(vColor, alpha * alphaMask); 
+                varying vec3 vColor;
+                void main() {
+                    vec2 coord = gl_PointCoord - vec2(0.5);
+                    float d = length(coord) * 2.0;
+                    if (d > 1.0) discard;
+                    float alphaMask = getMaskAlpha();
+                    if (alphaMask < 0.01) discard;
+
+                    // Stellarium-style: sharp core + soft glow
+                    float core = smoothstep(0.8, 0.4, d);
+                    float glow = smoothstep(1.0, 0.0, d) * 0.08;
+                    float k = core + glow;
+
+                    vec3 finalColor = mix(vColor, vec3(1.0), core * 0.5);
+                    gl_FragColor = vec4(finalColor * k * alphaMask, 1.0);
                 }
             `,
       transparent: true,
@@ -1056,6 +1282,9 @@ function createEngine({
   let constellationLines = null;
   let boundaryLines = null;
   let starPoints = null;
+  const linesFader = new Fader(0.4);
+  const artFader = new Fader(0.5);
+  let lastTickTime = 0;
   function clearRoot() {
     for (const child of [...root.children]) {
       root.remove(child);
@@ -1126,6 +1355,8 @@ function createEngine({
   function buildFromModel(model, cfg) {
     clearRoot();
     bookIdToIndex.clear();
+    testamentToIndex.clear();
+    divisionToIndex.clear();
     scene.background = cfg.background && cfg.background !== "transparent" ? new THREE5__namespace.Color(cfg.background) : new THREE5__namespace.Color(0);
     const layoutCfg = { ...cfg.layout, radius: cfg.layout?.radius ?? 2e3 };
     const laidOut = computeLayoutPositions(model, layoutCfg);
@@ -1159,6 +1390,8 @@ function createEngine({
     const starPhases = [];
     const starBookIndices = [];
     const starChapterIndices = [];
+    const starTestamentIndices = [];
+    const starDivisionIndices = [];
     const SPECTRAL_COLORS = [
       new THREE5__namespace.Color(14544639),
       // O - Blueish White
@@ -1216,12 +1449,32 @@ function createEngine({
         let cIdx = 0;
         if (n.meta?.chapter) cIdx = Number(n.meta.chapter);
         starChapterIndices.push(cIdx);
+        let tIdx = -1;
+        if (n.meta?.testament) {
+          const tName = n.meta.testament;
+          if (!testamentToIndex.has(tName)) {
+            testamentToIndex.set(tName, testamentToIndex.size + 1);
+          }
+          tIdx = testamentToIndex.get(tName);
+        }
+        starTestamentIndices.push(tIdx);
+        let dIdx = -1;
+        if (n.meta?.division) {
+          const dName = n.meta.division;
+          if (!divisionToIndex.has(dName)) {
+            divisionToIndex.set(dName, divisionToIndex.size + 1);
+          }
+          dIdx = divisionToIndex.get(dName);
+        }
+        starDivisionIndices.push(dIdx);
       }
       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";
+        else if (n.level === 2) {
+          const bookKey = n.meta?.bookKey;
+          color = bookKey && cfg.labelColors?.[bookKey] || "#cbd5e1";
+        } else if (n.level === 3) color = "#94a3b8";
         let labelText = n.label;
         if (n.level === 3 && n.meta?.chapter) {
           labelText = String(n.meta.chapter);
@@ -1302,6 +1555,8 @@ function createEngine({
     starGeo.setAttribute("phase", new THREE5__namespace.Float32BufferAttribute(starPhases, 1));
     starGeo.setAttribute("bookIndex", new THREE5__namespace.Float32BufferAttribute(starBookIndices, 1));
     starGeo.setAttribute("chapterIndex", new THREE5__namespace.Float32BufferAttribute(starChapterIndices, 1));
+    starGeo.setAttribute("testamentIndex", new THREE5__namespace.Float32BufferAttribute(starTestamentIndices, 1));
+    starGeo.setAttribute("divisionIndex", new THREE5__namespace.Float32BufferAttribute(starDivisionIndices, 1));
     const starMat = createSmartMaterial({
       uniforms: {
         pixelRatio: { value: renderer.getPixelRatio() },
@@ -1314,7 +1569,12 @@ function createEngine({
           ORDER_REVEAL_CONFIG.pulseDuration,
           ORDER_REVEAL_CONFIG.delayPerChapter,
           ORDER_REVEAL_CONFIG.pulseAmplitude
-        ) }
+        ) },
+        uFilterTestamentIndex: { value: -1 },
+        uFilterDivisionIndex: { value: -1 },
+        uFilterBookIndex: { value: -1 },
+        uFilterStrength: { value: 0 },
+        uFilterDimFactor: { value: 0.08 }
       },
       vertexShaderBody: `
                 attribute float size; 
@@ -1322,10 +1582,12 @@ function createEngine({
                 attribute float phase;
                 attribute float bookIndex;
                 attribute float chapterIndex;
+                attribute float testamentIndex;
+                attribute float divisionIndex;
+
+                varying vec3 vColor;
+                uniform float pixelRatio;
 
-                varying vec3 vColor; 
-                uniform float pixelRatio; 
-                
                 uniform float uTime;
                 uniform float uAtmExtinction;
                 uniform float uAtmTwinkle;
@@ -1335,6 +1597,12 @@ function createEngine({
                 uniform float uGlobalDimFactor;
                 uniform vec3 uPulseParams;
 
+                uniform float uFilterTestamentIndex;
+                uniform float uFilterDivisionIndex;
+                uniform float uFilterBookIndex;
+                uniform float uFilterStrength;
+                uniform float uFilterDimFactor;
+
                 void main() { 
                     vec3 nPos = normalize(position);
                     
@@ -1369,8 +1637,21 @@ function createEngine({
                     
                     float activePulse = pulse * uPulseParams.z * isTarget * uOrderRevealStrength;
 
+                    // --- Hierarchy Filter ---
+                    float filtered = 0.0;
+                    if (uFilterTestamentIndex >= 0.0) {
+                        filtered = 1.0 - step(0.5, 1.0 - abs(testamentIndex - uFilterTestamentIndex));
+                    }
+                    if (uFilterDivisionIndex >= 0.0 && filtered < 0.5) {
+                        filtered = 1.0 - step(0.5, 1.0 - abs(divisionIndex - uFilterDivisionIndex));
+                    }
+                    if (uFilterBookIndex >= 0.0 && filtered < 0.5) {
+                        filtered = 1.0 - step(0.5, 1.0 - abs(bookIndex - uFilterBookIndex));
+                    }
+                    float filterDim = mix(1.0, uFilterDimFactor, uFilterStrength * filtered);
+
                     vec3 baseColor = color * extinction * horizonFade * scintillation;
-                    vColor = baseColor * dimFactor;
+                    vColor = baseColor * dimFactor * filterDim;
                     vColor += vec3(1.0, 0.8, 0.4) * activePulse;
 
                     vec4 mvPosition = modelViewMatrix * vec4(position, 1.0); 
@@ -1378,7 +1659,8 @@ function createEngine({
                     vScreenPos = gl_Position.xy / gl_Position.w; 
                     
                     float sizeBoost = 1.0 + activePulse * 0.8;
-                    gl_PointSize = (size * sizeBoost * 1.5) * uScale * pixelRatio * (2000.0 / -mvPosition.z) * horizonFade; 
+                    float perceptualSize = pow(size, 0.55);
+                    gl_PointSize = clamp((perceptualSize * sizeBoost * 1.5) * uScale * pixelRatio * (2000.0 / -mvPosition.z) * horizonFade, 1.0, 40.0); 
                 }
             `,
       fragmentShader: `
@@ -1391,15 +1673,14 @@ function createEngine({
                     float alphaMask = getMaskAlpha(); 
                     if (alphaMask < 0.01) discard; 
                     
-                    float dd = d * d;
-                    // Stellarium Profile
-                    float core = exp(-20.0 * dd);
-                    float halo = exp(-4.0 * dd);
-                    
-                    vec3 cCore = vec3(1.0) * core * 1.5;
-                    vec3 cHalo = vColor * halo * 0.6;
-                    
-                    gl_FragColor = vec4((cCore + cHalo) * alphaMask, 1.0); 
+                    // Stellarium-style dual-layer: sharp core + soft glow
+                    float core = smoothstep(0.8, 0.4, d);
+                    float glow = smoothstep(1.0, 0.0, d) * 0.08;
+                    float k = core + glow;
+
+                    // White-hot core blending into coloured halo
+                    vec3 finalColor = mix(vColor, vec3(1.0), core * 0.7);
+                    gl_FragColor = vec4(finalColor * k * alphaMask, 1.0); 
                 }
             `,
       transparent: true,
@@ -1433,17 +1714,89 @@ function createEngine({
       }
     }
     if (linePoints.length > 0) {
+      const quadPositions = [];
+      const quadUvs = [];
+      const quadIndices = [];
+      const lineWidth = 8;
+      for (let i = 0; i < linePoints.length; i += 6) {
+        const ax = linePoints[i], ay = linePoints[i + 1], az = linePoints[i + 2];
+        const bx = linePoints[i + 3], by = linePoints[i + 4], bz = linePoints[i + 5];
+        const dx = bx - ax, dy = by - ay, dz = bz - az;
+        const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (len < 1e-3) continue;
+        let px = dy * 0 - dz * 1, py = dz * 0 - dx * 0, pz = dx * 1 - dy * 0;
+        const pLen = Math.sqrt(px * px + py * py + pz * pz);
+        if (pLen < 1e-3) {
+          px = 1;
+          py = 0;
+          pz = 0;
+        } else {
+          px /= pLen;
+          py /= pLen;
+          pz /= pLen;
+        }
+        const hw = lineWidth;
+        const baseIdx = quadPositions.length / 3;
+        quadPositions.push(ax - px * hw, ay - py * hw, az - pz * hw);
+        quadUvs.push(0, -1);
+        quadPositions.push(ax + px * hw, ay + py * hw, az + pz * hw);
+        quadUvs.push(0, 1);
+        quadPositions.push(bx - px * hw, by - py * hw, bz - pz * hw);
+        quadUvs.push(1, -1);
+        quadPositions.push(bx + px * hw, by + py * hw, bz + pz * hw);
+        quadUvs.push(1, 1);
+        quadIndices.push(baseIdx, baseIdx + 1, baseIdx + 2, baseIdx + 1, baseIdx + 3, baseIdx + 2);
+      }
       const lineGeo = new THREE5__namespace.BufferGeometry();
-      lineGeo.setAttribute("position", new THREE5__namespace.Float32BufferAttribute(linePoints, 3));
+      lineGeo.setAttribute("position", new THREE5__namespace.Float32BufferAttribute(quadPositions, 3));
+      lineGeo.setAttribute("lineUv", new THREE5__namespace.Float32BufferAttribute(quadUvs, 2));
+      lineGeo.setIndex(quadIndices);
       const lineMat = createSmartMaterial({
-        uniforms: { color: { value: new THREE5__namespace.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.4 * alphaMask); }`,
+        uniforms: {
+          color: { value: new THREE5__namespace.Color(11193599) },
+          uLineWidth: { value: 1.5 },
+          uGlowIntensity: { value: 0.3 }
+        },
+        vertexShaderBody: `
+                    attribute vec2 lineUv;
+                    varying vec2 vLineUv;
+                    void main() {
+                        vLineUv = lineUv;
+                        vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
+                        gl_Position = smartProject(mvPosition);
+                        vScreenPos = gl_Position.xy / gl_Position.w;
+                    }
+                `,
+        fragmentShader: `
+                    uniform vec3 color;
+                    uniform float uLineWidth;
+                    uniform float uGlowIntensity;
+                    varying vec2 vLineUv;
+                    void main() {
+                        float alphaMask = getMaskAlpha();
+                        if (alphaMask < 0.01) discard;
+
+                        float dist = abs(vLineUv.y);
+
+                        // Anti-aliased core line
+                        float hw = uLineWidth * 0.05;
+                        float base = smoothstep(hw + 0.08, hw - 0.08, dist);
+
+                        // Soft glow extending outward
+                        float glow = (1.0 - dist) * uGlowIntensity;
+
+                        float alpha = max(glow, base);
+                        if (alpha < 0.005) discard;
+
+                        gl_FragColor = vec4(color, alpha * alphaMask);
+                    }
+                `,
         transparent: true,
         depthWrite: false,
-        blending: THREE5__namespace.AdditiveBlending
+        blending: THREE5__namespace.AdditiveBlending,
+        side: THREE5__namespace.DoubleSide
       });
-      constellationLines = new THREE5__namespace.LineSegments(lineGeo, lineMat);
+      constellationLines = new THREE5__namespace.Mesh(lineGeo, lineMat);
       constellationLines.frustumCulled = false;
       root.add(constellationLines);
     }
@@ -1615,8 +1968,19 @@ function createEngine({
   let lastAppliedLon = void 0;
   let lastAppliedLat = void 0;
   let lastBackdropCount = void 0;
+  function setProjection(id) {
+    if (id === "blended") {
+      currentProjection = new BlendedProjection(ENGINE_CONFIG.blendStart, ENGINE_CONFIG.blendEnd);
+    } else {
+      const factory = exports.PROJECTIONS[id];
+      if (!factory) return;
+      currentProjection = factory();
+    }
+    updateUniforms();
+  }
   function setConfig(cfg) {
     currentConfig = cfg;
+    if (cfg.projection) setProjection(cfg.projection);
     if (typeof cfg.camera?.lon === "number" && cfg.camera.lon !== lastAppliedLon) {
       state.lon = cfg.camera.lon;
       state.targetLon = cfg.camera.lon;
@@ -1706,6 +2070,15 @@ function createEngine({
     Object.assign(arr, state.tempArrangement);
     return arr;
   }
+  function isNodeFiltered(node) {
+    if (!currentFilter) return false;
+    const meta = node.meta;
+    if (!meta) return false;
+    if (currentFilter.testament && meta.testament !== currentFilter.testament) return true;
+    if (currentFilter.division && meta.division !== currentFilter.division) return true;
+    if (currentFilter.bookKey && meta.bookKey !== currentFilter.bookKey) return true;
+    return false;
+  }
   function pick(ev) {
     const rect = renderer.domElement.getBoundingClientRect();
     const mX = ev.clientX - rect.left;
@@ -1717,13 +2090,14 @@ function createEngine({
     const w = rect.width;
     const h = rect.height;
     let closestLabel = null;
-    let minLabelDist = 40;
+    const LABEL_THRESHOLD = isTouchDevice ? 48 : 40;
+    let minLabelDist = LABEL_THRESHOLD;
     for (const item of dynamicLabels) {
       if (!item.obj.visible) continue;
+      if (isNodeFiltered(item.node)) 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;
+      if (currentProjection.isClipped(pProj.z)) continue;
       const xNDC = pProj.x * uScale / uAspect;
       const yNDC = pProj.y * uScale;
       const sX = (xNDC * 0.5 + 0.5) * w;
@@ -1745,8 +2119,7 @@ function createEngine({
       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;
+      if (currentProjection.isClipped(pProj.z)) continue;
       const uniforms = item.material.uniforms;
       if (!uniforms || !uniforms.uSize) continue;
       const uSize = uniforms.uSize.value;
@@ -1795,12 +2168,16 @@ function createEngine({
         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 (node && !isNodeFiltered(node)) return { type: "star", node, index: pointHit.index, point: pointHit.point, object: void 0 };
         }
       }
     }
     return void 0;
   }
+  function onWindowBlur() {
+    isMouseInWindow = false;
+    edgeHoverStart = 0;
+  }
   function onMouseDown(e) {
     state.lastMouseX = e.clientX;
     state.lastMouseY = e.clientY;
@@ -1838,6 +2215,7 @@ function createEngine({
       }
       return;
     }
+    flyToActive = false;
     state.dragMode = "camera";
     state.isDragging = true;
     state.velocityX = 0;
@@ -1896,11 +2274,13 @@ function createEngine({
       state.lastMouseX = e.clientX;
       state.lastMouseY = e.clientY;
       const speedScale = state.fov / ENGINE_CONFIG.defaultFov;
+      const rotLock = Math.max(0, Math.min(1, (state.fov - 100) / (ENGINE_CONFIG.maxFov - 100)));
+      const latFactor = 1 - rotLock * rotLock;
       state.targetLon += deltaX * ENGINE_CONFIG.dragSpeed * speedScale;
-      state.targetLat += deltaY * ENGINE_CONFIG.dragSpeed * speedScale;
+      state.targetLat += deltaY * ENGINE_CONFIG.dragSpeed * speedScale * latFactor;
       state.targetLat = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, state.targetLat));
       state.velocityX = deltaX * ENGINE_CONFIG.dragSpeed * speedScale;
-      state.velocityY = deltaY * ENGINE_CONFIG.dragSpeed * speedScale;
+      state.velocityY = deltaY * ENGINE_CONFIG.dragSpeed * speedScale * latFactor;
       state.lon = state.targetLon;
       state.lat = state.targetLat;
     } else {
@@ -1934,6 +2314,9 @@ function createEngine({
     }
   }
   function onMouseUp(e) {
+    const dx = e.clientX - state.lastMouseX;
+    const dy = e.clientY - state.lastMouseY;
+    const movedDist = Math.sqrt(dx * dx + dy * dy);
     if (state.dragMode === "node") {
       const fullArr = getFullArrangement();
       handlers.onArrangementChange?.(fullArr);
@@ -1946,6 +2329,17 @@ function createEngine({
       state.isDragging = false;
       state.dragMode = "none";
       document.body.style.cursor = "default";
+      if (movedDist < 5) {
+        const hit = pick(e);
+        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);
+        }
+      }
     } else {
       const hit = pick(e);
       if (hit) {
@@ -1960,6 +2354,7 @@ function createEngine({
   }
   function onWheel(e) {
     e.preventDefault();
+    flyToActive = false;
     const aspect = container.clientWidth / container.clientHeight;
     renderer.domElement.getBoundingClientRect();
     const vBefore = getMouseViewVector(state.fov, aspect);
@@ -1970,6 +2365,17 @@ function createEngine({
     updateUniforms();
     const vAfter = getMouseViewVector(state.fov, aspect);
     const quaternion = new THREE5__namespace.Quaternion().setFromUnitVectors(vAfter, vBefore);
+    const dampStartFov = 40;
+    const dampEndFov = 120;
+    let spinAmount = 1;
+    if (state.fov > dampStartFov) {
+      const t = Math.max(0, Math.min(1, (state.fov - dampStartFov) / (dampEndFov - dampStartFov)));
+      spinAmount = 1 - Math.pow(t, 1.5) * 0.8;
+    }
+    if (spinAmount < 0.999) {
+      const identityQuat = new THREE5__namespace.Quaternion();
+      quaternion.slerp(identityQuat, 1 - spinAmount);
+    }
     const y = Math.sin(state.lat);
     const r = Math.cos(state.lat);
     const x = r * Math.sin(state.lon);
@@ -1998,6 +2404,144 @@ function createEngine({
     state.targetLat = state.lat;
     state.targetLon = state.lon;
   }
+  function getTouchDistance(t1, t2) {
+    const dx = t1.clientX - t2.clientX;
+    const dy = t1.clientY - t2.clientY;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+  function getTouchCenter(t1, t2) {
+    return {
+      x: (t1.clientX + t2.clientX) / 2,
+      y: (t1.clientY + t2.clientY) / 2
+    };
+  }
+  function onTouchStart(e) {
+    e.preventDefault();
+    isTouchDevice = true;
+    const touches = e.touches;
+    state.touchCount = touches.length;
+    if (touches.length === 1) {
+      const touch = touches[0];
+      state.touchStartTime = performance.now();
+      state.touchStartX = touch.clientX;
+      state.touchStartY = touch.clientY;
+      state.touchMoved = false;
+      state.lastMouseX = touch.clientX;
+      state.lastMouseY = touch.clientY;
+      flyToActive = false;
+      state.dragMode = "camera";
+      state.isDragging = true;
+      state.velocityX = 0;
+      state.velocityY = 0;
+    } else if (touches.length === 2) {
+      const t0 = touches[0];
+      const t1 = touches[1];
+      state.pinchStartDistance = getTouchDistance(t0, t1);
+      state.pinchStartFov = state.fov;
+      const center = getTouchCenter(t0, t1);
+      state.pinchCenterX = center.x;
+      state.pinchCenterY = center.y;
+      state.lastMouseX = center.x;
+      state.lastMouseY = center.y;
+      state.touchMoved = true;
+    }
+  }
+  function onTouchMove(e) {
+    e.preventDefault();
+    const touches = e.touches;
+    if (touches.length === 1 && state.dragMode === "camera") {
+      const touch = touches[0];
+      const deltaX = touch.clientX - state.lastMouseX;
+      const deltaY = touch.clientY - state.lastMouseY;
+      state.lastMouseX = touch.clientX;
+      state.lastMouseY = touch.clientY;
+      const totalDx = touch.clientX - state.touchStartX;
+      const totalDy = touch.clientY - state.touchStartY;
+      if (Math.sqrt(totalDx * totalDx + totalDy * totalDy) > ENGINE_CONFIG.tapMaxDistance) {
+        state.touchMoved = true;
+      }
+      const speedScale = state.fov / ENGINE_CONFIG.defaultFov;
+      const rotLock = Math.max(0, Math.min(1, (state.fov - 100) / (ENGINE_CONFIG.maxFov - 100)));
+      const latFactor = 1 - rotLock * rotLock;
+      state.targetLon += deltaX * ENGINE_CONFIG.dragSpeed * speedScale;
+      state.targetLat += deltaY * ENGINE_CONFIG.dragSpeed * speedScale * latFactor;
+      state.targetLat = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, state.targetLat));
+      state.velocityX = deltaX * ENGINE_CONFIG.dragSpeed * speedScale;
+      state.velocityY = deltaY * ENGINE_CONFIG.dragSpeed * speedScale * latFactor;
+      state.lon = state.targetLon;
+      state.lat = state.targetLat;
+    } else if (touches.length === 2) {
+      const t0 = touches[0];
+      const t1 = touches[1];
+      const newDistance = getTouchDistance(t0, t1);
+      const scale = newDistance / state.pinchStartDistance;
+      state.fov = state.pinchStartFov / scale;
+      state.fov = Math.max(ENGINE_CONFIG.minFov, Math.min(ENGINE_CONFIG.maxFov, state.fov));
+      handlers.onFovChange?.(state.fov);
+      const center = getTouchCenter(t0, t1);
+      const deltaX = center.x - state.lastMouseX;
+      const deltaY = center.y - state.lastMouseY;
+      state.lastMouseX = center.x;
+      state.lastMouseY = center.y;
+      const speedScale = state.fov / ENGINE_CONFIG.defaultFov;
+      state.targetLon += deltaX * ENGINE_CONFIG.dragSpeed * speedScale * 0.5;
+      state.targetLat += deltaY * ENGINE_CONFIG.dragSpeed * speedScale * 0.5;
+      state.targetLat = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, state.targetLat));
+      state.lon = state.targetLon;
+      state.lat = state.targetLat;
+    }
+  }
+  function onTouchEnd(e) {
+    e.preventDefault();
+    const remainingTouches = e.touches.length;
+    if (remainingTouches === 0) {
+      const duration = performance.now() - state.touchStartTime;
+      const wasTap = !state.touchMoved && duration < ENGINE_CONFIG.tapMaxDuration;
+      if (wasTap) {
+        const rect = renderer.domElement.getBoundingClientRect();
+        const mX = state.touchStartX - rect.left;
+        const mY = state.touchStartY - rect.top;
+        mouseNDC.x = mX / rect.width * 2 - 1;
+        mouseNDC.y = -(mY / rect.height) * 2 + 1;
+        const syntheticEvent = {
+          clientX: state.touchStartX,
+          clientY: state.touchStartY
+        };
+        const hit = pick(syntheticEvent);
+        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);
+        }
+      }
+      state.isDragging = false;
+      state.dragMode = "none";
+      state.touchCount = 0;
+    } else if (remainingTouches === 1) {
+      const touch = e.touches[0];
+      state.lastMouseX = touch.clientX;
+      state.lastMouseY = touch.clientY;
+      state.touchCount = 1;
+      state.dragMode = "camera";
+      state.isDragging = true;
+      state.velocityX = 0;
+      state.velocityY = 0;
+    }
+  }
+  function onTouchCancel(e) {
+    e.preventDefault();
+    state.isDragging = false;
+    state.dragMode = "none";
+    state.touchCount = 0;
+    state.velocityX = 0;
+    state.velocityY = 0;
+  }
+  function onGesturePrevent(e) {
+    e.preventDefault();
+  }
   function resize() {
     const w = container.clientWidth || 1;
     const h = container.clientHeight || 1;
@@ -2018,9 +2562,15 @@ function createEngine({
     el.addEventListener("mouseenter", () => {
       isMouseInWindow = true;
     });
-    el.addEventListener("mouseleave", () => {
-      isMouseInWindow = false;
-    });
+    el.addEventListener("mouseleave", onWindowBlur);
+    window.addEventListener("blur", onWindowBlur);
+    el.addEventListener("touchstart", onTouchStart, { passive: false });
+    el.addEventListener("touchmove", onTouchMove, { passive: false });
+    el.addEventListener("touchend", onTouchEnd, { passive: false });
+    el.addEventListener("touchcancel", onTouchCancel, { passive: false });
+    el.addEventListener("gesturestart", onGesturePrevent, { passive: false });
+    el.addEventListener("gesturechange", onGesturePrevent, { passive: false });
+    el.addEventListener("gestureend", onGesturePrevent, { passive: false });
     raf = requestAnimationFrame(tick);
   }
   function tick() {
@@ -2049,9 +2599,20 @@ function createEngine({
         if (m.uniforms.uOrderRevealStrength) m.uniforms.uOrderRevealStrength.value = orderRevealStrength;
       }
     }
+    const filterTarget = currentFilter ? 1 : 0;
+    filterStrength = mix(filterStrength, filterTarget, 0.1);
+    if (filterStrength > 1e-3 || filterTarget > 0) {
+      if (starPoints && starPoints.material) {
+        const m = starPoints.material;
+        if (m.uniforms.uFilterTestamentIndex) m.uniforms.uFilterTestamentIndex.value = filterTestamentIndex;
+        if (m.uniforms.uFilterDivisionIndex) m.uniforms.uFilterDivisionIndex.value = filterDivisionIndex;
+        if (m.uniforms.uFilterBookIndex) m.uniforms.uFilterBookIndex.value = filterBookIndex;
+        if (m.uniforms.uFilterStrength) m.uniforms.uFilterStrength.value = filterStrength;
+      }
+    }
     let panX = 0;
     let panY = 0;
-    if (!state.isDragging && isMouseInWindow && !currentConfig?.editable) {
+    if (!state.isDragging && isMouseInWindow && !currentConfig?.editable && !isTouchDevice) {
       const t = ENGINE_CONFIG.edgePanThreshold;
       const inZoneX = mouseNDC.x < -1 + t || mouseNDC.x > 1 - t;
       const inZoneY = mouseNDC.y < -1 + t || mouseNDC.y > 1 - t;
@@ -2080,16 +2641,33 @@ function createEngine({
     } else {
       edgeHoverStart = 0;
     }
+    if (flyToActive && !state.isDragging) {
+      state.lon = mix(state.lon, flyToTargetLon, FLY_TO_SPEED);
+      state.lat = mix(state.lat, flyToTargetLat, FLY_TO_SPEED);
+      state.fov = mix(state.fov, flyToTargetFov, FLY_TO_SPEED);
+      state.targetLon = state.lon;
+      state.targetLat = state.lat;
+      state.velocityX = 0;
+      state.velocityY = 0;
+      handlers.onFovChange?.(state.fov);
+      if (Math.abs(state.lon - flyToTargetLon) < 1e-4 && Math.abs(state.lat - flyToTargetLat) < 1e-4 && Math.abs(state.fov - flyToTargetFov) < 0.05) {
+        flyToActive = false;
+        state.lon = flyToTargetLon;
+        state.lat = flyToTargetLat;
+        state.fov = flyToTargetFov;
+      }
+    }
     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) {
+    } else if (!state.isDragging && !flyToActive) {
       state.lon += state.velocityX;
       state.lat += state.velocityY;
-      state.velocityX *= ENGINE_CONFIG.inertiaDamping;
-      state.velocityY *= ENGINE_CONFIG.inertiaDamping;
+      const damping = isTouchDevice ? ENGINE_CONFIG.touchInertiaDamping : ENGINE_CONFIG.inertiaDamping;
+      state.velocityX *= damping;
+      state.velocityY *= damping;
       if (Math.abs(state.velocityX) < 1e-6) state.velocityX = 0;
       if (Math.abs(state.velocityY) < 1e-6) state.velocityY = 0;
     }
@@ -2106,13 +2684,30 @@ function createEngine({
     camera.updateMatrixWorld();
     camera.matrixWorldInverse.copy(camera.matrixWorld).invert();
     updateUniforms();
-    constellationLayer.update(state.fov, currentConfig?.showConstellationArt ?? false);
+    const nowSec = now / 1e3;
+    const dt = lastTickTime > 0 ? Math.min(nowSec - lastTickTime, 0.1) : 0.016;
+    lastTickTime = nowSec;
+    linesFader.target = currentConfig?.showConstellationLines ?? false;
+    linesFader.update(dt);
+    artFader.target = currentConfig?.showConstellationArt ?? false;
+    artFader.update(dt);
+    constellationLayer.update(state.fov, artFader.eased > 0.01);
+    if (artFader.eased < 1) {
+      constellationLayer.setGlobalOpacity?.(artFader.eased);
+    }
     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;
+      constellationLines.visible = linesFader.eased > 0.01;
+      if (constellationLines.visible && constellationLines.material) {
+        const mat = constellationLines.material;
+        if (mat.uniforms?.color) {
+          mat.uniforms.color.value.setHex(11193599);
+          mat.opacity = linesFader.eased;
+        }
+      }
     }
     if (boundaryLines) {
       boundaryLines.visible = currentConfig?.showDivisionBoundaries ?? false;
@@ -2133,8 +2728,7 @@ function createEngine({
     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;
+    const showChapters = state.fov < 45;
     for (const item of dynamicLabels) {
       const uniforms = item.obj.material.uniforms;
       const level = item.node.level;
@@ -2155,11 +2749,6 @@ function createEngine({
         item.obj.visible = uniforms.uAlpha.value > 0.01;
         continue;
       }
-      if (level === 2 && !showBooks && item.node.id !== state.draggedNodeId) {
-        uniforms.uAlpha.value = THREE5__namespace.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__namespace.MathUtils.lerp(uniforms.uAlpha.value, 0, 0.2);
         item.obj.visible = uniforms.uAlpha.value > 0.01;
@@ -2192,8 +2781,8 @@ function createEngine({
       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 isWideAngle = currentProjection.id !== "perspective";
+        if (isWideAngle) {
           const dx = l.sX - screenW / 2;
           const dy = l.sY - screenH / 2;
           rot = Math.atan2(-dy, -dx) - Math.PI / 2;
@@ -2201,7 +2790,7 @@ function createEngine({
         l.uniforms.uAngle.value = THREE5__namespace.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 });
         }
@@ -2223,6 +2812,17 @@ function createEngine({
           }
         }
       }
+      if (target2 > 0 && currentFilter && filterStrength > 0.01) {
+        const node = l.item.node;
+        if (node.level === 3) {
+          target2 = 0;
+        } else if (node.level === 2 || node.level === 2.5) {
+          const nodeToCheck = node.level === 2.5 && node.parent ? nodeById.get(node.parent) : node;
+          if (nodeToCheck && isNodeFiltered(nodeToCheck)) {
+            target2 = 0;
+          }
+        }
+      }
       l.uniforms.uAlpha.value = THREE5__namespace.MathUtils.lerp(l.uniforms.uAlpha.value, target2, 0.1);
       l.item.obj.visible = l.uniforms.uAlpha.value > 0.01;
     }
@@ -2237,6 +2837,15 @@ function createEngine({
     window.removeEventListener("mousemove", onMouseMove);
     window.removeEventListener("mouseup", onMouseUp);
     el.removeEventListener("wheel", onWheel);
+    el.removeEventListener("mouseleave", onWindowBlur);
+    window.removeEventListener("blur", onWindowBlur);
+    el.removeEventListener("touchstart", onTouchStart);
+    el.removeEventListener("touchmove", onTouchMove);
+    el.removeEventListener("touchend", onTouchEnd);
+    el.removeEventListener("touchcancel", onTouchCancel);
+    el.removeEventListener("gesturestart", onGesturePrevent);
+    el.removeEventListener("gesturechange", onGesturePrevent);
+    el.removeEventListener("gestureend", onGesturePrevent);
   }
   function dispose() {
     stop();
@@ -2257,7 +2866,30 @@ function createEngine({
   function setOrderRevealEnabled(enabled) {
     orderRevealEnabled = enabled;
   }
-  return { setConfig, start, stop, dispose, setHandlers, getFullArrangement, setHoveredBook, setFocusedBook, setOrderRevealEnabled };
+  function flyTo(nodeId, targetFov) {
+    const node = nodeById.get(nodeId);
+    if (!node) return;
+    const pos = getPosition(node).normalize();
+    flyToTargetLat = Math.asin(Math.max(-0.999, Math.min(0.999, pos.y)));
+    flyToTargetLon = Math.atan2(pos.x, -pos.z);
+    flyToTargetFov = targetFov ?? ENGINE_CONFIG.minFov;
+    flyToActive = true;
+    state.velocityX = 0;
+    state.velocityY = 0;
+  }
+  function setHierarchyFilter(filter) {
+    currentFilter = filter;
+    if (filter) {
+      filterTestamentIndex = filter.testament && testamentToIndex.has(filter.testament) ? testamentToIndex.get(filter.testament) : -1;
+      filterDivisionIndex = filter.division && divisionToIndex.has(filter.division) ? divisionToIndex.get(filter.division) : -1;
+      filterBookIndex = filter.bookKey && bookIdToIndex.has(`B:${filter.bookKey}`) ? bookIdToIndex.get(`B:${filter.bookKey}`) : -1;
+    } else {
+      filterTestamentIndex = -1;
+      filterDivisionIndex = -1;
+      filterBookIndex = -1;
+    }
+  }
+  return { setConfig, start, stop, dispose, setHandlers, getFullArrangement, setHoveredBook, setFocusedBook, setOrderRevealEnabled, setHierarchyFilter, flyTo, setProjection };
 }
 var ENGINE_CONFIG, ORDER_REVEAL_CONFIG;
 var init_createEngine = __esm({
@@ -2265,20 +2897,29 @@ var init_createEngine = __esm({
     init_layout();
     init_materials();
     init_ConstellationArtworkLayer();
+    init_projections();
+    init_fader();
     ENGINE_CONFIG = {
-      minFov: 10,
-      maxFov: 165,
-      defaultFov: 80,
+      minFov: 1,
+      maxFov: 135,
+      defaultFov: 50,
       dragSpeed: 125e-5,
       inertiaDamping: 0.92,
-      blendStart: 60,
-      blendEnd: 165,
-      zenithStartFov: 110,
-      zenithStrength: 0.02,
+      blendStart: 35,
+      blendEnd: 83,
+      zenithStartFov: 75,
+      zenithStrength: 0.15,
       horizonLockStrength: 0.05,
       edgePanThreshold: 0.15,
       edgePanMaxSpeed: 0.02,
-      edgePanDelay: 250
+      edgePanDelay: 250,
+      // Touch-specific
+      touchInertiaDamping: 0.85,
+      // Snappier than mouse (0.92)
+      tapMaxDuration: 300,
+      // ms
+      tapMaxDistance: 10
+      // px
     };
     ORDER_REVEAL_CONFIG = {
       globalDim: 0.85,
@@ -2296,7 +2937,10 @@ var StarMap = react.forwardRef(
       getFullArrangement: () => engineRef.current?.getFullArrangement?.(),
       setHoveredBook: (id) => engineRef.current?.setHoveredBook?.(id),
       setFocusedBook: (id) => engineRef.current?.setFocusedBook?.(id),
-      setOrderRevealEnabled: (enabled) => engineRef.current?.setOrderRevealEnabled?.(enabled)
+      setOrderRevealEnabled: (enabled) => engineRef.current?.setOrderRevealEnabled?.(enabled),
+      setHierarchyFilter: (filter) => engineRef.current?.setHierarchyFilter?.(filter),
+      flyTo: (nodeId, targetFov) => engineRef.current?.flyTo?.(nodeId, targetFov),
+      setProjection: (id) => engineRef.current?.setProjection?.(id)
     }));
     react.useEffect(() => {
       let disposed = false;
@@ -31573,6 +32217,9 @@ function generateArrangement(bible, options = {}) {
   return arrangement;
 }
 
+// src/index.ts
+init_projections();
+
 exports.StarMap = StarMap;
 exports.bibleToSceneModel = bibleToSceneModel;
 exports.defaultGenerateOptions = defaultGenerateOptions;