🐛 fix: contact 캔버스 오프스크린 미정지 수정 + 캐시 재마운트 판정

[pcwadarong]

목적

PR #97이 후속으로 분리한 2건을 정리한다.

(1) contact 캔버스가 한 번 노출된 뒤 화면 밖으로 나가도 계속 렌더됐다. RenderWhenVisible이 setFrameloop('never')를 명령형으로 호출하지만, R3F <Canvas>가 리렌더마다 frameloop prop(기본값 'always')을 스토어에 재적용해 그 호출을 곧바로 덮어썼다. (2) characterInstanceCache 싱글턴이 sourceScene 동일성만으로 캐시를 판정하는 게 라우트 이동 후 재마운트에서 안전한지 확인 — 결론은 문제 없음, 근거를 주석·테스트로 남겼다.

	전	후
contact 노출 후 화면 밖 (useFrame/초)	≈60 (계속 돔)	0 (정지)
가시성 판단 주체	Canvas 내부 명령형 setFrameloop	<Canvas frameloop> 제어 prop
리렌더 시 frameloop	configure가 'always'로 되돌림	의도한 값 유지
캐시 재마운트 근거	코드에 없음 (의심 반복)	주석 + 계약 테스트로 고정

적용 범위: use-render-when-visible.ts(컴포넌트→훅), hero/contact 캔버스 2곳의 배선, use-character-instance.ts 주석. 애니메이션·전환 로직·에셋은 건드리지 않았다.

설계

1. 원인이 IO root가 아니라 <Canvas frameloop> 재적용임을 계측으로 좁혔다

과제의 유력 후보는 "IO의 root가 기본값(window)이라 실제 스크롤 루트([data-app-scroll-viewport])를 못 따라간다"였다. 프로덕션 빌드 + GPU Chromium(M3 Pro) 계측으로 반증했다.

좁히는 순서	결과
② contact 캔버스에 root=null·root=앱뷰포트 두 옵저버 부착, 스크롤 in/out	둘 다 이탈 시 isIntersecting:false 정확 발화 → IO는 무죄
③ RenderWhenVisible에 로그 주입	이탈 시 setFrameloop('never') 호출됨, contact 실제로 멈춤(t≈60ms)
④ 이후 frameloop 폴링	~1초 뒤 혼자 always로 복귀(RWV 호출 없음). 오프스크린에서 resize 1발 → never→always 재현

R3F 9.5.0 소스에서 확정:

// <Canvas>: deps 없는 layout effect — 매 렌더 실행
useIsomorphicLayoutEffect(() => { root.current.configure({ /* frameloop 등 */ }) })

// configure(): frameloop 인자 기본값이 'always'
if (state.frameloop !== frameloop) state.setFrameloop(frameloop)

명령형 setFrameloop('never')는 다음 리렌더 한 번에 덮어써진다. ContactScene의 리사이즈·availableHeight 동기화·스크롤 구동 부모 렌더가 흔하므로 오프스크린 후 곧 클로버된다. hero가 멀쩡한 건 IO 우열이 아니라 **이 페이지에서 항상 최소 93px 노출(sticky 핀)**이라 원하는 상태가 어차피 always라서다. contact만 완전히 이탈해 드러난다.

이 메커니즘은 "한 번도 노출 안 되면 0회/초"도 설명한다 — 안 보이는 동안 스크롤이 없으면 Canvas 리렌더가 없어 never가 유지되고, 한 번 보이려고 스크롤하는 순간 리렌더가 다발로 나 클로버된다.

2. 왜 controlled frameloop prop인가

frameloop prop이 R3F의 진실이라, 원하는 값을 prop으로 제어하면 리렌더가 나도 그 값이 재적용돼 유지된다.

const [canvasElement, setCanvasElement] = useState<HTMLCanvasElement | null>(null);
const frameloop = useCanvasVisibilityFrameloop(canvasElement); // 'always' | 'never'
<Canvas frameloop={frameloop} onCreated={({ gl }) => setCanvasElement(gl.domElement)} />

버린 대안

대안	왜 안 골랐나
IO root를 앱 스크롤 뷰포트로 변경	원인이 아니라 안 고쳐진다 (설계 1)
Canvas 내부에서 store 구독 후 'never' 재-assert	매 리렌더 configure가 'always'로 세팅 → 우리가 'never'로 되돌리는 핑퐁. 프레임 누수는 없지만 프레임워크와 싸우고 판단 주체가 둘이 된다
frameloop="demand"	캐릭터 mixer·gsap·OrbitControls 댐핑이 상시 구동돼 매 프레임 invalidate로 퇴화 (기존 JSDoc 근거)

3. resume 시 명시적 invalidate()를 두지 않았다

'never'→'always' 복귀 시, hero가 이 페이지에서 항상 always라 전역 rAF 루프가 멈추지 않으므로 다음 프레임에 contact가 자동 렌더된다(실측 확인). 이 두 캔버스는 홈 라우트에만 존재하므로 hero가 루프를 살려두는 전제가 항상 성립한다. 전역 invalidate()는 모든 root를 무효화해 과하므로 두지 않았다.

Changes

커밋	내용
eb78ae5	🐛 fix: contact 오프스크린 미정지 — controlled frameloop prop
081f4df	🧪 test: characterInstanceCache 재마운트 판정 근거 명시

• RenderWhenVisible 컴포넌트 → useCanvasVisibilityFrameloop(canvasElement) 훅. IO + visibilitychange 판단은 그대로, 반환만 'always' | 'never'.
• hero/contact 캔버스가 onCreated의 gl.domElement를 state로 잡아 훅에 넘기고 frameloop prop으로 소비. (hero는 이미 canvasElement state가 있어 재사용.)
• getOrCreateCharacterCache에 sourceScene 키가 재마운트에 안전한 근거 주석 + 계약 테스트 2건.

의도적으로 안 바꾼 것

항목	이유
MIXER_MAX_DELTA_SECONDS 상한	#93의 frameloop 재개 안전장치. 이번 범위 밖
#97의 instance별 mixer 분리	유지
characterInstanceCache 싱글턴 구조	판정 결과 "문제 없음"이라 구조 변경 불필요 (설계는 캐시 재사용이 오히려 이득)
비홈 라우트 프리로드(F-3)	브랜치 02 소유

리뷰 포인트

1. <Canvas> configure가 매 렌더 frameloop을 재적용한다는 전제 (설계 1) — 이게 틀리면 진단이 무너진다. 설치된 @react-three/fiber@9.5.0의 deps 없는 layout effect + configure의 frameloop 기본값 'always'가 근거다.
2. controlled prop 전환으로 판단 주체가 하나로 유지되는지 — 가시성 판단은 훅 한 곳, <Canvas>는 그 값을 받기만 한다.
3. resume 시 invalidate 생략이 안전한지 (설계 3) — hero가 홈에서 전역 루프를 항상 살려두는 전제.
4. 캐시 재마운트 판정 — sourceScene 동일성이 옳은 키라는 근거(drei useGLTF URL 캐시가 언마운트로 안 비워짐)와 계약 테스트.

Test plan

• pnpm run check-types — 통과

• pnpm run lint — 통과

• pnpm run test:vitest — 전 버킷 통과 (신규: useCanvasVisibilityFrameloop 7건, 캐시 계약 2건)

• 실측 전/후 — 프로덕션 빌드 + GPU Chromium(M3 Pro), 1600×1100, /ko. useFrame/초 계측:

  상태	전 contact	후 contact
  미노출	0	0
  노출중	≈60	≈77
  노출후 화면밖	≈60	0
  resize 8발(오프스크린)	(60 복귀)	0 유지
  재노출	≈60	≈77
  SPA 라우트 왕복 후 오프스크린	—	0

  hero(main)는 전·후 모두 항상 running(항상 부분 노출이라 정상). 콘솔 에러 0.

• SPA 라우트 왕복(client-side) 후 애니메이션 정상 재개 + 캐시 싱글턴 유지 확인 (캐시 판정 근거)

• 탭 백그라운드/복귀 라이브 계측 — 미실행. 구동 Chromium이 document.visibilityState 재정의를 막아 라이브로는 못 걸었다. 동일 applyVisibility 경로라 유닛 테스트로 커버.

• pnpm run test:browser — 25 passed / 1 failed. 실패한 home-hero-scene.spec.ts:39는 이 변경과 무관한 기존 flake: git stash로 clean main을 리빌드해 돌려도 동일하게 실패(같은 tabIndex 5s 타임아웃). headless 소프트웨어 렌더링(≈4fps)에서 씬 준비가 poll을 못 맞추는 타이밍 이슈고, 로컬 retries:0이라 노출된다. CI는 retries:2라 마스킹된다.

후속

• home-hero-scene.spec.ts:39의 headless 타이밍 flake — 이번 변경과 무관하나 로컬에서 재현된다. 5s expect.poll 대신 명시적 대기 조건으로 안정화하는 별도 작업이 필요하다. 이번 PR 범위 밖(테스트 인프라 소유).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
chaen	Ready	Preview	Sep 6, 2026 10:26am UTC

[coderabbitai]

Warning

Review limit reached

Next included review available in 51 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 92491f99-e37b-4425-bb06-68c957bea6e8

📥 Commits

Reviewing files that changed from the base of the PR and between 9a4a938 and 701fcca.

📒 Files selected for processing (10)

• .claude/skills/article-writing/SKILL.md
• .claude/skills/article-writing/references/capture-workflow.md
• src/entities/character/model/use-character-instance.test.ts
• src/entities/character/model/use-character-instance.ts
• src/shared/lib/three/use-render-when-visible.test.tsx
• src/shared/lib/three/use-render-when-visible.ts
• src/widgets/contact-scene/ui/contact-scene-canvas.test.tsx
• src/widgets/contact-scene/ui/contact-scene-canvas.tsx
• src/widgets/home-hero-scene/ui/home-hero-stage-canvas.test.tsx
• src/widgets/home-hero-scene/ui/home-hero-stage-canvas.tsx

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/render-when-visible-cache-remount

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 081f4dfebd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".