thesis-3d 탭 간 구 크기 오염 — JavaScript 비동기 전역 상태의 구조적 결함 분석

1. 문제 현상

ers.hyperbook.com/viz/thesis-3d에는 세 개의 탭이 있다.

각 탭의 크기 공식은 의미적으로 독립되어야 한다. 그러나 빠른 탭 전환 또는 30초 자동 갱신과 탭 전환이 겹치면, 키워드 탭 노드가 네트워크 탭 크기로 그려지거나, 시냅스 탭 데이터가 키워드 크기로 렌더링되는 현상이 발생한다.

2. 코드 구조 분석

2.1 전역 상태 단일화

let currentType = "network";  // 세 탭 모두 공유하는 단일 변수
let nodes3d = [];              // 씬 노드 배열 — 탭 공유
let edges3d = [];              // 씬 엣지 배열 — 탭 공유
let rotX = 0, rotY = 0;       // 회전 상태 — 탭 공유
// camera.position.z           // 줌 — 탭 공유

씬의 모든 상태가 탭 무관 단일 전역값이다. 탭 전환은 이 전역값을 덮어쓴다.

2.2 buildScene — 파라미터 없이 전역 읽기

function buildScene(nodes, edges) {
  // ...
  nodes.forEach(n => {
    const r = currentType === "network"           // ← 실행 시점의 전역값!
      ? Math.max(0.4, (n.paper_count || 1) * 0.15 + 0.3)
      : 0.3;
    const geo = new THREE.SphereGeometry(r, 16, 16);
    // ...
  });
}

buildScene은 노드 데이터를 인자로 받지만, 크기를 결정하는 타입은 전역 currentType에서 읽는다. 이것이 핵심 결함이다.

2.3 loadLayout — await 경계에서 전역 노출

async function loadLayout() {
  if (currentType === "synapse") { ... }   // 시점 A: currentType 읽기 #1
  await checkStatus();                       // ← 비동기 공백 (수십 ms)
  const resp = await fetch(                 // ← 비동기 공백 (수백 ms)
    `/api/thesis-3d/layout?type=${currentType}`  // 시점 B: currentType 읽기 #2
  );
  const data = await resp.json();           // ← 비동기 공백 (수백 ms)
  buildScene(data.nodes, data.edges);       // 시점 C: buildScene이 #3 읽기
}

currentType은 세 개의 await 경계에 걸쳐 총 세 번 읽힌다. 각 공백 사이에 사용자가 탭을 전환하면, 다음 읽기는 새 탭의 타입을 반환한다.

2.4 경쟁 조건 재현 시나리오

시나리오: 키워드 → 네트워크 → 키워드 빠른 전환

t=0ms   : setType("network") → currentType="network", loadLayout() 호출
t=30ms  : checkStatus() 대기 중
t=50ms  : 사용자가 "키워드" 클릭 → currentType="keywords", 두 번째 loadLayout() 호출
t=60ms  : 두 번째 loadLayout()이 keywords 데이터 fetch 시작 (캐시 히트)
t=80ms  : 첫 번째 loadLayout()의 checkStatus() 완료
          fetch URL = `/layout?type=keywords` (currentType이 이미 변경됨!)
t=120ms : keywords 데이터 도착 → buildScene(keywords_data)
          currentType = "keywords" → r = 0.3 → 정상
t=140ms : 첫 번째 loadLayout()의 fetch도 keywords 데이터 수신
          buildScene(keywords_data)을 또 한 번 실행 → 정상이지만 불필요한 이중 렌더

시나리오: 30초 자동 갱신과 탭 전환 충돌

t=0s    : setInterval이 loadLayout() 발화 — currentType="network"
t=50ms  : checkStatus() 대기 중
t=100ms : 사용자가 "시냅스" 탭 클릭 → currentType="synapse"
          setType은 loadLayout()을 다시 호출 → 두 번째 loadLayout()
t=110ms : 두 번째 loadLayout(): currentType=="synapse" → loadSynapse() 호출
t=300ms : 시냅스 데이터 도착 → buildSynapseScene() 완료
t=350ms : 첫 번째 loadLayout()의 fetch URL = `/layout?type=synapse`
          (currentType이 "synapse"이므로) → 잘못된 fetch
          또는: fetch = network 데이터이지만 buildScene이 currentType="synapse"로 읽으면
          → 크기 공식이 혼재

3. 설계 결함의 발생 경위 — 점진적 기능 추가 패턴

이 결함은 단번에 잘못 설계된 것이 아니다. 다음 단계적 진화의 결과다.

Phase 1: 단일 뷰

초기 구현은 network 뷰 하나였다. currentType은 상수나 다름없었고, 전역 상태는 문제를 일으키지 않았다.

// Phase 1: 단일 뷰, 전역 타입 문제 없음
const currentType = "network";
function buildScene(nodes, edges) {
  const r = 0.4;  // 고정값 — 문제 없음
}

Phase 2: 두 번째 뷰 추가

keywords 탭을 추가할 때 최소 변경 경로를 택했다. buildScene 내부에 currentType 분기를 추가했다. 이 시점부터 잠재 결함이 발생했으나, 탭 전환이 느릴 때는 증상이 없었다.

// Phase 2: 분기 추가 — 잠재 결함 발생
function buildScene(nodes, edges) {
  const r = currentType === "network" ? variable_size : 0.3;  // 전역 의존
}

Phase 3: 세 번째 뷰 추가

synapse 탭은 크기 공식이 달라 별도 buildSynapseScene()으로 분리했다. 그러나 같은 nodes3d, edges3d, pivot을 공유했다. 전역 상태의 오염 경로가 완성됐다.

핵심 통찰: 각 단계에서 "가장 작은 변경"을 선택했기 때문에, 설계 검토의 기회가 없었다. 함수 하나를 추가하는 것이 전역 상태를 리팩토링하는 것보다 쉬웠다.

4. 수정 방안

4.1 즉시 수정: 타입을 조기에 캡처하고 파라미터로 전달

async function loadLayout() {
  const type = currentType;  // ← 비동기 시작 전 즉시 캡처
  if (type === "synapse") { await loadSynapse(); return; }
  await checkStatus();
  if (type !== currentType) return;  // ← 탭이 바뀌었으면 중단
  const resp = await fetch(`/api/thesis-3d/layout?type=${type}`);
  if (!resp.ok || type !== currentType) return;  // ← 다시 확인
  const data = await resp.json();
  if (type !== currentType) return;  // ← 최종 확인
  buildScene(data.nodes || [], data.edges || [], type);  // ← type 전달
}

function buildScene(nodes, edges, type) {  // ← 파라미터로 수신
  // ...
  const r = type === "network"
    ? Math.max(0.4, (n.paper_count || 1) * 0.15 + 0.3)
    : 0.3;
  // ...
  const showLabel = type !== "keywords" || (n.freq || 0) >= (nodes.length > 60 ? 3 : 1);
}

4.2 자동 갱신 취소 메커니즘

let _loadGen = 0;  // 세대 카운터 — 탭 전환마다 증가

function setType(t) {
  currentType = t;
  _loadGen++;      // 기존 진행 중인 loadLayout 무효화
  // ...
  loadLayout();
}

async function loadLayout() {
  const type = currentType;
  const gen = _loadGen;  // 현재 세대 기억
  // ...
  await checkStatus();
  if (gen !== _loadGen || type !== currentType) return;  // 세대 불일치 = 폐기
  // ...
}

4.3 근본 해결: 탭별 독립 피벗 그룹

const _views = {
  network:  { pivot: new THREE.Group(), nodes: [], edges: [] },
  keywords: { pivot: new THREE.Group(), nodes: [], edges: [] },
  synapse:  { pivot: new THREE.Group(), nodes: [], edges: [] },
};
scene.add(_views.network.pivot, _views.keywords.pivot, _views.synapse.pivot);

function setType(t) {
  // 모든 피벗 숨기고 선택된 것만 표시
  Object.entries(_views).forEach(([k, v]) => { v.pivot.visible = (k === t); });
  currentType = t;
  loadLayout();
}

이 방식은 탭 전환 시 Three.js 씬 재구성이 불필요하며, 각 탭의 회전·줌 상태도 독립적으로 유지할 수 있다.

5. 결론

이 버그의 본질은 JavaScript async 함수에서 전역 가변 상태(global mutable state)를 await 경계를 넘어 공유하는 패턴이다. 이는 싱글스레드 JavaScript의 가장 흔한 설계 함정 중 하나다. 동기 코드에서는 문제가 없지만, 비동기 공백(수십~수백 ms)에서 외부 이벤트가 전역 상태를 변경할 수 있다.

수정의 원칙은 단순하다: async 함수의 첫 줄에서 모든 전역 의존 값을 로컬 변수로 캡처하고, await마다 스냅샷과 현재값을 비교해 폐기 여부를 판단하라. 이것이 React의 useEffect cleanup, Kotlin의 structured concurrency, Swift의 actor isolation이 공통으로 가르치는 비동기 설계 원칙이다.

영향 범위 요약