first commit

docs/qa-regions/brief.md

@@ -0,0 +1,44 @@
+# 색면·경계 단순화 작업
+
+사용자 요청: 유리를 통과하면서 단순히 해상도가 낮아지거나 흐려지는 대신, 셀 내부의 비슷한 색을 묶고 작은 경계를 정리하여 Ref1~2의 색면 느낌을 시험한다.
+
+기존의 일관된 굴절 좌표, 셀 곡면, 시점 반응과 Ref1 | Ref2 비교 영역을 유지한다. 단색 셀이나 다른 사진 조각을 무작위로 배치하는 방식으로 대체하지 않는다.
+
+검증 기준:
+- 잔디·털의 작은 무늬가 줄고 큰 색면으로 정리되는지 원본 설정과 같은 구도에서 비교.
+- 눈·코의 어두운 형태와 얼굴 윤곽을 보존.
+- 처리 강도 0에서 기존 결과 복원, Distortion 0과 No Glass 경로 유지.
+- 드래그와 원위치 복귀, 셀 수 변경, 모바일 레이아웃 및 다른 유리 효과 확인.
+- 빌드 성공과 시각적 완성도를 구분하여 기록.
+
+수정 전 캡처: dog1-before.png, dog2-before.png, sample-before.png. 테스트 사진은 로컬 검증용이며 게시 허가를 의미하지 않는다.
+
+## 구현 결과
+
+수정 파일: `src/main.ts`, `src/shaders/mosaic.frag`, `src/shaders/region-palette.frag`, `index.html`.
+
+- 기본 조각 유리에 `색면 단순화` 0~1 조절을 추가했다. 기본값 0.65. 촘촘 유리/Reeded/Frosted에는 적용하지 않는다.
+- 같은 굴절 셰이더로 유리 좌표의 셀별 8×8 색상 표본을 만든다. 셀마다 네 대표 색을 결정적으로 초기화하고 두 번 군집 갱신한다.
+- 실제 화면은 원래 해상도로 샘플한다. 가장 가까운 대표 색으로 분류한 뒤, 주변 3×3 표본의 색상 분류 투표로 작은 고립 영역을 정리한다. RGB 공간 평균 블러나 저해상도 이미지 확대가 아니다. 전체 연결 요소를 추적하는 완전한 영역 분할 알고리즘은 아니다.
+- 원래 색과 대표 색을 강도에 따라 혼합하고, 눈·코의 어두운 특징이 크게 밝아지는 경우는 보호한다. 기존 표면 광택은 그 뒤에 적용한다.
+- 정지 사진의 같은 상태에서는 표본과 팔레트를 재사용한다. 시점·사진·depth·구도 등의 상태 변화에는 갱신한다. 영상은 갱신 경로를 유지하되 이번 QA에서 실제 영상은 재생하지 않았다.
+- 장치 최대 텍스처 크기를 넘는 극단적 종횡비는 색면 처리만 건너뛰고 기존 굴절을 출력한다.
+
+## 검증 결과
+
+- 최종 빌드와 타입 검사 통과. 기존 번들 크기 안내는 남는다.
+- Chrome 실제 WebGL 실행으로 셰이더 오류를 확인하고 수정했다. 최종 실행에서 페이지/셰이더 오류 없음. favicon 404는 기능 오류와 별개로 기존에 남아 있다.
+- dog1/dog2/sample의 강도 0·0.65·1을 같은 구도로 비교했다. 색면이 드러나고 털·잔디의 작은 무늬가 줄며 눈·코는 식별 가능하다. 1은 회화적 느낌이 강해 기본값 0.65를 유지했다.
+- 세 사진 모두 강도0 화면과 수정 전 화면이 모든 픽셀에서 일치했다.
+- 8단계 시점 이동과 원위치 복귀를 캡처했다. 복귀 차이는 RGB 채널 하나에서 값1뿐이었다. 캡처에서 장면 조각의 큰 점프는 보이지 않았지만 모든 연속 프레임의 깜빡임 부재를 보장하는 검증은 아니다.
+- Distortion0/No Glass 중앙150×150 비교는 3개 채널에서 값1 차이. 다른 유리 효과의 강도0/1 비교는 완전히 같거나 값1 이하 반올림 차이뿐이었다.
+- Grid96 출력과 390px 모바일 화면 확인. 가로 넘침 없음, Ref1/Ref2 모두 로드됨. PC 정지 화면의 30개 프레임 간격은 대체로16.7ms였으나 실기기 모바일/동영상/움직이는 고밀도 격자 성능 측정은 아니다.
+- 최종 소스 재빌드 후 세 사진의 기본값을 다시 캡처하고 극단적인 2×2048 사진 입력도 오류 없이 처리했다.
+
+최종 화면: `dog1-final.png`, `dog2-final.png`, `sample-final.png`. 기타 근거: `runtime.json`, `pixel-checks.json`, `final-smoke.json`, `motion-*.png`.
+
+## 한계와 다음 판단
+
+이번 결과는 사용자가 요청한 색면·경계 단순화 실험이다. Ref2의 강한 조각 확대와 동일한 광학적 질감을 달성했다고 판단하지 않는다. 8×8 표본과 셀별 네 색 때문에 고강도에서 색면 경계가 거칠거나 포스터화되어 보일 수 있다. 다음 개선은 사용자가 선호하는 강도에서 색면 크기와 경계 보존 정도를 조정하는 것이다. AI 추론과 실제 모바일 GPU/영상은 이번 변경에서 재검증하지 않았다.
+
+실행: 현재 `http://127.0.0.1:5175/`를 새로고침하고 기본 Mosaic의 `색면 단순화`를 조절한다. 개발 실행은 `npm run dev`, 배포 빌드는 `npm run build`.

docs/qa-regions/final-smoke.json

@@ -0,0 +1,4 @@
+{
+  "errors": [],
+  "extremeAspectSurvived": true
+}

docs/qa-regions/pixel-checks.json

@@ -0,0 +1,42 @@
+{
+  "dog1ZeroVsBefore": {
+    "changedChannels": 0,
+    "maxDifference": 0,
+    "meanDifference": 0
+  },
+  "dog2ZeroVsBefore": {
+    "changedChannels": 0,
+    "maxDifference": 0,
+    "meanDifference": 0
+  },
+  "sampleZeroVsBefore": {
+    "changedChannels": 0,
+    "maxDifference": 0,
+    "meanDifference": 0
+  },
+  "reededBypass": {
+    "changedChannels": 144,
+    "maxDifference": 1,
+    "meanDifference": 0.00006857142857142857
+  },
+  "frostedBypass": {
+    "changedChannels": 0,
+    "maxDifference": 0,
+    "meanDifference": 0
+  },
+  "mosaicBypass": {
+    "changedChannels": 347,
+    "maxDifference": 1,
+    "meanDifference": 0.00016523809523809525
+  },
+  "return": {
+    "changedChannels": 1,
+    "maxDifference": 1,
+    "meanDifference": 4.761904761904762e-7
+  },
+  "distortion0": {
+    "changedChannels": 3,
+    "maxDifference": 1,
+    "meanDifference": 0.000044444444444444447
+  }
+}

docs/qa-regions/review-current.md

@@ -0,0 +1,47 @@
+# 색면 단순화 재QA — 2026-09-14
+
+## 판정
+
+시각 방향은 유지할 가치가 있다. 큰 색면이 생기고 전체 사진이 흐려지는 이전 문제는 줄었다. 다만 Ref2 수준의 완료 판정은 보류한다. 실제 사용자 설정에서 표정의 세부 명암 손실과 기울어진 유리 가장자리의 빈 영역을 확인했다. 이번에는 QA만 수행했으며 소스와 기본값은 변경하지 않았다.
+
+## 실제 확인 환경
+
+- 사용자 탭: `http://127.0.0.1:5173/`.
+- dog1, 조각 유리, 색면 단순화1, Grid8, Distortion1, 굴곡0.65, 광택0.4, 조명X0.6/Y2, 사진 확대1.
+- 사용자 탭의 Camera Offset0.6, sensitivity2, Depth Scale0.4. 해당 사진은 UI상 Depth 없음/평면 테스트이므로 이 결과를 AI depth 시차로 해석하지 않는다.
+- 사용자 탭에서 같은 카메라 시점의 색면1/0/0.65를 비교한 뒤1로 복원했다. 사용자 사진과 카메라 시점은 변경하지 않았다.
+- 별도의 임시 탭에서 동일 색면/격자/왜곡 조건의 dog1 작은/큰 드래그, dog2 정면, sample 확대 얼굴을 확인했다. sample은 수작업 테스트 depth이며 AI 추정이 아니다. 별도 탭의 Depth Scale은 기본0.25를 유지했다.
+- 모바일 viewport390×844에서 DOM 가로 넘침 없음(scrollWidth375≤innerWidth390), 두 Ref 이미지 정상 로드, Ref1|Ref2 아래 작업 화면 배치 유지. 실기기 GPU 성능 테스트는 아니다.
+
+## 확인한 개선점
+
+- 셀 내부의 얼굴·털이 넓은 색 영역으로 정리된다. 색면0과 비교하면 잔무늬 감소가 명확하다.
+- 강한 전체 블러로 경계를 지우는 결과는 아니다. 셀 굴절과 색면 경계가 구분된다.
+- 사용자 탭의 Ref1/Ref2 비교 배치가 실제 개발 서버에서도 유지된다.
+- 별도 QA 탭에서 콘솔 error 기록 없음. 이번 턴에서 소스 변경이 없어 빌드를 반복하지 않았다.
+
+## 보정 우선순위
+
+### 1. 눈·코 내부 특징 보존 — 시각적으로 확인
+
+사용자 탭의 색면1에서 눈의 밝은 점과 코 내부 명암이 거의 사라지고 어두운 평면 조각처럼 보인다. 색면0에서는 같은 시점에서 눈 반사와 코가 더 명확하다. 별도 정면 dog1에서도 강도1에서 눈이 단순한 어두운 쐐기 모양으로 정리되었다. dog2는 검은 얼굴과 눈의 구분이 특히 약하다. 확대 sample은 눈·코 식별이 상대적으로 양호했다.
+
+전체 색면 효과를 약하게 되돌리는 대신, 고대비의 작은 밝은 특징과 어두운 특징을 함께 보존하도록 보호 조건을 보완하는 것이 적합하다. 현재 보호는 어두운 색이 크게 밝아지는 특정 경우만 대상으로 한다(`mosaic.frag`의 preserveDark). Ref2의 눈도 단순한 검은 면이 아니라 내부 밝은 특징을 유지한다.
+
+### 2. 비스듬한 시점의 사진 채움 범위 — 시각적으로 확인
+
+사용자 화면 왼쪽과 위쪽의 프레임 안에 배경색 빈 영역과 들쭉날쭉한 사진 끝이 보인다. 색면0에서도 같은 틈이 남았다. 별도 탭의 큰 드래그에서도 재현되었다. 따라서 색면 처리만의 결함으로 분류하지 않는다.
+
+사진/깊이의 일치된 구도를 유지하면서 허용 시점에서 충분한 원본 영역을 확보하는 방안을 별도로 검토해야 한다. 실제 깊이 표면을 완전히 복원한 것으로 표현하거나, 큰 블러로 숨겨서는 안 된다.
+
+### 3. 배경의 작은 색 조각 — 시각적으로 확인
+
+얼굴은 넓은 색면이 되었지만 잔디에는 작은 섬 같은 색 조각이 많이 남는다. 강도1에서는 이 차이 때문에 일부 영역이 유리보다 포스터화된 그림처럼 보인다. 대표 색 혼합 강도와 작은 영역 병합 정도를 분리해서 검토할 필요가 있다. 단색 셀로 대체하는 방식은 요구사항과 맞지 않는다.
+
+## 아직 통과로 판정하지 않은 항목
+
+- 작은 드래그에서 같은 장면이 이어지는 것은 확인했지만, 연속 프레임 전체의 팔레트 깜빡임 부재는 검증하지 못했다. 8×8 표본으로 시점마다 팔레트를 재계산하므로 원위치 재현성과 시간적 부드러움은 구분해야 한다.
+- 독립 소스 검토에서 마지막 부분 셀의 유리 바깥 표본이 배경색으로 팔레트에 들어가는 것을 확인했다. `main.ts`의 ceil(gridY) 할당, `mosaic.frag`의 바깥 배경 출력, `region-palette.frag`의 전체64표본 군집화 조합이다. 이는 가장자리에 한정된 잠재적 색 오염이며, 이번 눈·코 문제의 원인으로 단정하지 않는다. 유효 표본 제외가 최소 보정 방향이다.
+- AI 추론, 실제 모바일/영상 성능, 모든 유리 효과의 회귀 검사를 이번 턴에서 다시 수행하지 않았다.
+
+이번 QA의 다음 보정 순서는 눈·코의 작은 명암 보존 → 큰 시점의 빈 영역 → 잔디의 작은 색 영역 정리다. 사용자가 긍정적으로 평가한 색면 강도와 시점 일관성은 유지하는 방향이다.

docs/qa-regions/runtime.json

@@ -0,0 +1,40 @@
+{
+  "errors": [],
+  "mobileOverflow": false,
+  "references": [
+    1160,
+    1387
+  ],
+  "grid96FrameTimes": [
+    6.799999994039354,
+    16.699999999999818,
+    16.700000000000728,
+    16.699999999999818,
+    16.599999999999454,
+    16.700000000000728,
+    16.599999999999454,
+    16.900000000000546,
+    16.5,
+    16.699999999999818,
+    16.699999999999818,
+    16.699999999999818,
+    16.699999999999818,
+    16.600000000000364,
+    16.699999999999818,
+    16.699999999999818,
+    16.700000000000728,
+    16.599999999999454,
+    16.800000000000182,
+    16.699999999999818,
+    16.600000000000364,
+    16.699999999999818,
+    16.699999999999818,
+    16.699999999999818,
+    16.700000000000728,
+    16.599999999999454,
+    16.699999999999818,
+    16.700000000000728,
+    16.699999999999818,
+    16.699999999999818
+  ]
+}