first commit

docs/qa-depth-coupling/report.md

@@ -0,0 +1,35 @@
+# 깊이·굴절 연결 개선 — 2026-09-30
+
+사용자가 승인한 재점검 후속 구현. 옵션 1·2 문서는 보존하며 이번 결과를 새 개선안으로 구분한다. 수정 직전 `main.ts`, `mosaic.frag`는 이 폴더 baseline 파일에 보존했다. Git 저장소가 아니므로 커밋은 생성하지 않았다.
+
+## 변경
+
+- `src/main.ts`: 미디어 로드 시 zoom/pan 초기화 제거. 명시적 구도 초기화 버튼은 유지. RGB/Depth 공통 변환, 최대 depth 기준 안전 간격은 유지한다.
+- `src/depth/DepthProcessor.ts`, `src/constants/depth.ts`: 사진의 상대 depth 히스토그램에서 P50–P85 증거 범위를 계산. 범위가 좁으면 P5–P95로 재평가하고, 여전히 평탄하면 어두운 색면 증거를 끈다. 단일 가까운 이상치에 고정 문턱이 끌리지 않게 한다. 사진 전체 통계이며 얼굴/강아지 검출은 아니다.
+- `src/shaders/mosaic.frag`: 기존 연출 굴절을 출발점으로 세 번의 screen-depth 반복 보정을 추가. atlas/final에 동일 적용. 미수렴·무효 depth·유리 앞 표면에서는 원래 샘플로 복귀한다. 이동은 최대 셀 폭 0.35에 혼합 0.65를 적용하므로 0.2275셀 이하. 색면 강도의 거리 감쇠나 최종 원본 눈·코 복원은 없다.
+- `src/constants/glass.ts`, Mosaic: 공통 환경의 어두운 아래/밝은 위 명암과 Fresnel 각도 항을 작은 반사로 추가. 기존 직사각 광원은 유지. 광택·굴절 0에서 새 반사도 0. 조각 유리 모드에만 적용하며 임의 시간 변화는 없다.
+
+## 검증
+
+- `npm.cmd run build`: TypeScript/Vite 통과. 기존 500kB 청크 경고 유지.
+- `scripts/test-*.mjs` 9개 모두 통과. 새 depth-evidence 테스트는 미구현 상태와 bimodal 결함에서 각각 실패를 확인한 뒤 통과했다. 새 depth-refraction 테스트는 반사 게이트 추가 전 실패 후 통과했다.
+- 기존 surface-reflection의 atlas 전체 바이트 동일성 검사는 의도적으로 바뀐 광학 계산을 허용하고 반사가 atlas에 들어가지 않는 검사로 변경했다. 기존 반사 상수 출력/atlas 오염 mutation 검사는 계속 통과한다. 고정 depth 문턱 source 검사는 새 uniform 연결 검사로 변경했다.
+- 수학/소스 검사는 GPU 품질의 증명이 아니다. 기존 continuity 수치도 새 screen-depth 보정의 모든 경계/시점 연속성을 증명하지 않는다.
+- 브라우저: dog1/dog2 자동 AI 추론 성공. dog1 정면·드래그, dog2 Final/No Glass, Glass Only 및 광택 0을 확인. 광택 0의 유리 단독 화면에는 반사가 남지 않았다.
+- dog1 확대1.50/팬+0.10/-0.10을 설정한 후 같은 사진 재로드: 로드 직후와 AI 완료 후 값 유지. 명시적 구도 초기화 후 기본 구도로 돌아왔다.
+- dog2 390×844 viewport에서 유리/사진 배치 확인, override 해제. 실제 휴대폰 검증은 아니다.
+- 최종 콘솔 조회에서 error는 없었고 X3595(가변 반복문 내 gradient 연산) 경고 1건이 수집됐다. 기존에도 있던 종류의 경고이나 새 depth 반복 샘플링에도 관련될 수 있다. 다른 GPU에서의 영향은 미검증이다.
+- 창 크기 변경으로 캡처마다 viewport가 다르다. 저장 화면은 정성적 확인용이며 픽셀 단위 전후 비교나 효과 크기의 정량 증거로 사용하지 않는다.
+
+## 시각 판단과 남은 한계
+
+흰 강아지의 두 눈·코 사각 면은 유지된다. 깊이에 따른 색면 위치가 바뀌며 반사는 절제된 수준이다. 어두운 강아지는 Grid13에서 눈·코 구분이 여전히 약하다. 이 결과를 모든 사진의 식별성 개선 또는 Ref1 재현 완료로 판정하지 않는다.
+
+단일 깊이 표면과 화면에 보이는 depth만 사용하므로 가려진 옆면/배경을 복원하지 않는다. 실제 굴절 광선 추적의 완전한 해법이 아닌 기존 연출에 대한 제한된 보정이다. 강아지/얼굴을 분리하지 않으므로 얼굴을 유리 바로 뒤에 놓는 의미 기반 배치는 미구현이며 관통 방지를 위한 기존 전체 최대 depth 배치를 유지한다. 얼굴 확대·자동 팬은 추가하지 않았다.
+
+연속 영상의 깜빡임, GPU별 성능/FPS, 카메라 범위 전체 끝점, 실기기 터치·자이로, 다른 사진 크기에서의 전수 검증은 미실시. 사진은 로컬 QA 용도이며 게시하지 않았다.
+
+실행: `npm.cmd run dev -- --host 127.0.0.1 --port 5174`.
+
+![흰 강아지 개선안](dog1-final.jpg)
+![어두운 강아지 개선안](dog2-final.jpg)