From b71f18f8f07968568996d832b3a9deaf5f16c7e5 Mon Sep 17 00:00:00 2001
From: digua <i@digua.me>
Date: Wed, 1 Jul 2026 00:58:24 +0800
Subject: [PATCH] refactor(relationships): clarify immersive galaxy framing

---
 .../components/RelationshipGalaxyThreeCanvas.vue       |  4 ++--
 .../relationship-galaxy-3d-camera.test.ts              |  6 +++---
 .../relationships/relationship-galaxy-3d-camera.ts     | 10 ++++++----
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/pages/people/relationships/components/RelationshipGalaxyThreeCanvas.vue b/src/pages/people/relationships/components/RelationshipGalaxyThreeCanvas.vue
index b9cf4cff..05f7245c 100644
--- a/src/pages/people/relationships/components/RelationshipGalaxyThreeCanvas.vue
+++ b/src/pages/people/relationships/components/RelationshipGalaxyThreeCanvas.vue
@@ -18,7 +18,7 @@ import { buildRelationshipVisibleLabelKeys } from '../relationship-galaxy-connec
 import {
   applyRelationshipGalaxy3DSafeArea,
   buildRelationshipGalaxy3DViewOffset,
-  buildRelationshipGalaxy3DFitCameraPose,
+  buildRelationshipGalaxy3DImmersiveCameraPose,
   type RelationshipGalaxy3DCameraPose,
 } from '../relationship-galaxy-3d-camera'
 import { maskRelationshipGalaxyPrivateText } from '../relationship-galaxy-privacy'
@@ -615,7 +615,7 @@ function fitView() {
   if (!camera || !controls) return
 
   hasUserMovedCamera = false
-  const pose = applySafeAreaToCameraPose(buildRelationshipGalaxy3DFitCameraPose(sceneModel.value.bounds))
+  const pose = applySafeAreaToCameraPose(buildRelationshipGalaxy3DImmersiveCameraPose(sceneModel.value.bounds))
   startCameraFlight(
     new THREE.Vector3(pose.position.x, pose.position.y, pose.position.z),
     new THREE.Vector3(pose.target.x, pose.target.y, pose.target.z),
diff --git a/src/pages/people/relationships/relationship-galaxy-3d-camera.test.ts b/src/pages/people/relationships/relationship-galaxy-3d-camera.test.ts
index 4122a43b..c3d06c9c 100644
--- a/src/pages/people/relationships/relationship-galaxy-3d-camera.test.ts
+++ b/src/pages/people/relationships/relationship-galaxy-3d-camera.test.ts
@@ -7,11 +7,11 @@ import test from 'node:test'
 import {
   applyRelationshipGalaxy3DSafeArea,
   buildRelationshipGalaxy3DViewOffset,
-  buildRelationshipGalaxy3DFitCameraPose,
+  buildRelationshipGalaxy3DImmersiveCameraPose,
 } from './relationship-galaxy-3d-camera'
 
-test('fits the panorama with enough padding for a selected relationship network', () => {
-  const pose = buildRelationshipGalaxy3DFitCameraPose({
+test('frames the 3D panorama tightly for an immersive default view', () => {
+  const pose = buildRelationshipGalaxy3DImmersiveCameraPose({
     minX: -5000,
     maxX: 5000,
     minY: -3600,
diff --git a/src/pages/people/relationships/relationship-galaxy-3d-camera.ts b/src/pages/people/relationships/relationship-galaxy-3d-camera.ts
index f147c53c..531c41ba 100644
--- a/src/pages/people/relationships/relationship-galaxy-3d-camera.ts
+++ b/src/pages/people/relationships/relationship-galaxy-3d-camera.ts
@@ -28,9 +28,11 @@ export interface RelationshipGalaxy3DViewOffset {
   height: number
 }
 
-const FIT_CAMERA_PADDING_SCALE = 0.9
+// The default 3D galaxy view intentionally uses tight, immersive framing.
+// Edge nodes may sit near or slightly beyond the viewport instead of always being fully contained.
+const IMMERSIVE_CAMERA_PADDING_SCALE = 0.9
 
-export function buildRelationshipGalaxy3DFitCameraPose(
+export function buildRelationshipGalaxy3DImmersiveCameraPose(
   bounds: RelationshipGalaxy3DScene['bounds']
 ): RelationshipGalaxy3DCameraPose {
   const span = Math.max(bounds.width, bounds.height, bounds.depth, 900)
@@ -38,8 +40,8 @@ export function buildRelationshipGalaxy3DFitCameraPose(
   return {
     position: {
       x: 0,
-      y: -span * 0.5 * FIT_CAMERA_PADDING_SCALE,
-      z: span * 0.5 * FIT_CAMERA_PADDING_SCALE,
+      y: -span * 0.5 * IMMERSIVE_CAMERA_PADDING_SCALE,
+      z: span * 0.5 * IMMERSIVE_CAMERA_PADDING_SCALE,
     },
     target: { x: 0, y: 0, z: 0 },
   }