behind_glass/AGENTS.md

Pet Glass / Pet Behind Glass 프로젝트 지침

원본 요구사항

• 2026-09-14 최신 Ref1 옵션 정리: 색면 단순화와 Distortion을 1로 고정하고 해당 조절 UI를 제거한다. 주 조절은 Grid 1024(큰 얼굴 권장1216, 작은 얼굴/여러 마리2024), 굴곡 −11, 광택, 시점 범위다. 기타 효과·깊이·조명·감도는 접힌 개발 비교로 이동하고 수동 구도는 유지한다. 초기 기준값 Grid13/굴곡+1/광택.3/Camera.5. 상세와 한계는 docs/ref1-option-ranges.md. 이전 기본값·노출 UI 지시보다 우선한다.

• 2026-09-14 최신 옵션 지정: 현재 어두운 사각 색면 보존 구현과 설정을 **현재 프로젝트에서 Ref1 목표에 가장 근접한 두 번째 옵션(옵션 2)**으로 명시한다. 정확한 값은 docs/ref1-option-2.md를 따른다. 기존 기준안은 옵션 1로 보존하며, 옵션 2를 Ref2 목표로 해석하지 않는다. 이후 변경은 두 기준과 구분해 기록한다.

• 2026-09-14 최신 색면 보호 방식: 눈·코 원본 윤곽만 붙여 놓은 인상을 없애기 위해 최종 픽셀의 보호/원본 RGB 복원 분기를 제거한다. 앞쪽 depth와 어두운 RGB의 증거는 셀의 사각 색면 대표색 선택에만 사용한다. 어두운 색면의 존재를 보존하며 원래 픽셀 모양을 보존하지 않는다. 아래의 픽셀별 안전 palette/원본 fallback 지시보다 우선한다. docs/ref1-dark-color-planes.md 참고.

• 2026-09-14 최신 보호 범위 정정: 눈·코 보호는 원본 depth의 앞쪽(흰 부분)과 RGB의 어두운 특징이 겹치는 곳에 한정한다. 원본 상대 depth 0.80~0.95에서 보호를 부드럽게 증가시키며 기존 안전 palette/원본 fallback을 유지한다. 굴절 RGB와 같은 장면 위치에서 원본 depth를 읽는다. 색면 전체의 거리 감쇠 제거, 배경 단순화 및 시점 반응은 유지한다. 상세 구현·검증은 docs/ref1-depth-protection.md.

• 2026-09-14 최종 사용자 정정: 실제 결과를 확인한 사용자가 눈·코 보호 예외를 유지하도록 다시 지시했다. 아래의 보호 제거 지시는 이 정정으로 대체한다. 어두운 형태가 밝은 색면에 흡수될 때 기존 안전 palette 우선 보호와 필요한 픽셀의 원본색 fallback을 복원한다. 사진 배경의 색면 강화, SSE 분할 선택, 시점 반응과 70ms 전환 보간은 유지한다.

• 2026-09-14 최신 기준안 지정 및 추가 작업: 지금까지의 적용 내용과 비교 옵션을 Ref1 목표에 가장 근접한 현재 기준안으로 명시한다. 상세 값은 docs/ref1-current-baseline.md를 따른다. 사용자 최신 정정에 따라 눈·코의 어두운 픽셀/원본 RGB 보호 예외를 제거하고 얼굴과 사진 속 배경에 같은 색면 단순화를 적용한다. 눈·코 식별은 결과의 평가 기준이며 보호 로직을 강제하지 않는다. 아래 과거 눈·코 보호 지시보다 이 지시가 우선한다. 시점 반응, 70ms 색면 전환 보간, 자동 구도 조정 금지는 유지한다.

• 2026-09-14 최신 레퍼런스 변경: 사용자는 주 시각 기준을 Ref1로 변경했다. Ref2의 근접 선명도·거리 반응 재현을 주 목표로 삼지 않는다. Ref1의 큰 사각 색면, 과감하게 단순화된 얼굴 윤곽, 적은 정보로 식별되는 눈·코를 우선 평가한다. 아래의 Ref2 우선 지시보다 이 지시가 우선한다. 자동 구도 조정 금지와 인접 셀의 공통 장면 일관성은 유지한다. Ref1 | Ref2 비교 배치에서는 Ref1을 주 기준, Ref2를 보조로 표시한다. 상세 기준: docs/ref1-direction.md.

• 최신 사용자 요청: 자동 구도 조정을 하지 않는다. 사진 입력 및 자동 AI depth 완료 시 확대·팬·크롭을 자동 변경하지 않는다. 유리 근접 깊이 배치와 수동 구도 조절은 유지한다. 과거 자동 얼굴/앞쪽 영역 구도 지시보다 우선한다.

• 최신 근접 배치 정정: 사용자는 얼굴 확대 프리셋만의 해결을 거부했다. 사진 입력 후 깊이 표면의 앞쪽을 유리 바로 뒤에 배치하여 공간적으로 가까운 인상을 구현한다. RGB/Depth 공통 배치와 굴절 교차 기준을 함께 갱신하며 유리 관통을 방지한다. 확대만으로 실제 간격을 바꿨다고 설명하지 않는다. 상세 기록: docs/glass-contact.md.

• 최신 색면 실험: 일관된 굴절 위에 셀 내부 색상 양자화와 작은 색 영역의 경계 단순화를 추가한다. 전체 사진 블러나 저해상도 확대, 셀 전체 단색화로 대체하지 않는다. 눈·코의 작은 어두운 형태를 보호하고 색면 단순화 0에서 기존 출력을 복원한다. Ref1 | Ref2 비교 배치를 유지한다. 작업·검증 기록은 docs/qa-regions/brief.md.

• 최신 사용자 정정: 가까운 얼굴에서 색면 효과를 줄이는 거리 감쇠를 제거한다. 유효한 표면에는 유리와의 간격에 관계없이 설정된 색면 강도를 적용하고, 범위 밖 UV·배경 depth·역투영 실패·유리 앞/접촉 표면 검사는 유지한다.

• 최신 시점 굴절 보정: 기본 Mosaic에만 시점에 반응하는 셀 내부 굴절 이동을 더한다. 같은 현재 곡면 법선과 중앙 시점 굴절의 기울기 차이를 사용하고, 셀 경계는 고정하며 내부는 축별 cosine envelope로 움직인다. signed curvatureScale로 방향을 제어하고, atlas/final에 동일 계산을 적용한다. 이 항은 현재 평면 교점 광학 모델 안의 연출 근사다. 자동 구도, 입력 감도, 사진/Depth 배치와 다른 유리 효과는 바꾸지 않는다.

• 최신 Ref1 색면 보정: 큰 사각 얼굴·몸 색면과 적은 어두운 눈·코 형태를 우선한다. 기존 4색 palette에 셀별 최적 단일 축 분할(신뢰도 기반)과 radial grouping fallback을 사용한다. 어두운 눈·코는 palette 내 안전한 어두운 색으로 보호하고, 안전 palette 색이 없을 때만 해당 픽셀 원본색을 남긴다. 전체 셀 단색화, 원본 저해상도 확대, 전체 블러는 금지한다. region 0과 Distortion 0의 기존 동작을 유지하며, 시점 gain .18은 함께 유지한다. 상세 QA: docs/ref1-shape-review.md.

• 최신 시점/분할 전환 보정: Camera Offset 기본값은 .50, 최대값은 .90이며 입력 sensitivity 범위와 처리는 유지한다. 기본 Mosaic 외곽 taper는 1.25셀로 넓히고 다른 유리 모드는 .75셀을 유지한다. 셀 축 분할의 이산 메타데이터가 아니라 8×8 premultiplied 색·confidence field만 ping-pong history에서 70ms 지수 수렴시킨다. 카메라 이동은 history를 초기화하지 않으며 사진·depth·구도·격자·굴곡·강도·효과/모드·비활성화 변경은 초기화한다. 사진 구도 자동 변경은 금지한다. 실기기 FPS 및 영상 flicker 측정은 별도다. 상세 QA: docs/ref1-shape-review.md.

• 2026-09-14 최신 시점 일관성 지시: 셀마다 독립된 사진 정보를 가진 듯한 임의 확대·크롭 표현을 배제한다. 조각 유리는 공통 장면과 카메라 광선, 부호 있는 곡면 법선에서 굴절 샘플 위치를 계산한다. 과거의 셀별 무작위 샘플 배율·중심 이동 지시와 충돌하면 이 지시를 우선한다. 강한 블러로 불일치를 숨기지 않는다.

• 2026-09-14 재보정: 사용자는 과도한 흐림으로 사진/유리의 느낌이 사라지는 결과를 지적했다. 셀별 확대·위치 변화는 유지하되 눈·코 조각 내부 윤곽을 흐림으로 지우지 않는다. 해상감 저하를 일괄적인 강한 블러로 해석하지 않는다.

• 2026-09-14 추가: Ref2처럼 유리 투과 시 셀별 세부 정보가 크게 줄고 눈·코 조각의 크기와 위치가 달라지는 표현을 강화한다. 전체 출력 해상도 저하나 단색 pixelation으로 대체하지 않는다. Ref1 | Ref2 아래 작업 이미지 비교 배치는 개발 모드와 로컬 배포 미리보기 모두에서 유지한다. 상세 기준은 docs/glass-resolution-task.md.

• Mosaic 셀 굴곡은 관찰자 기준 -1=사진 쪽 오목, 0=셀 내부 평탄, +1=관찰자 쪽 볼록이다. 기본값 +0.65를 유지하며 부호가 있는 같은 곡면 법선을 굴절과 반사에 공유한다. 굴곡 0에서도 기존 셀별 기울기와 샘플링 효과는 유지한다.

• 과거 Ref2 주 기준 지시는 위 최신 Ref1 변경으로 대체되었다. 사진 구도는 RGB/Depth에 같은 변환을 적용하고 원본 파일을 바꾸지 않는다.

• 반복 쿠션형 인상을 줄이기 위해 중앙이 비교적 평탄하고 셀마다 약하게 비대칭인 곡면을 사용한다. 반사는 공통의 부드러운 직사각형 광원 형태를 근사하며 기존 조명 XY/광택 조절로 제어한다. 사진 리라이팅이나 시간 기반 반짝임은 추가하지 않는다.

• 셀 내부는 얕은 사각 곡면으로 표현하고 같은 표면 법선을 굴절과 광택에 공유한다. 광택을 꺼도 곡면에 의한 사진 윤곽 변화가 남아야 한다. 격자는 화면 너비가 아닌 유리판 기준이며, 셀 샘플 영역을 과도하게 줄여 단색 블록이 되는 결과를 피한다. 모바일/데스크톱 같은 설정, 정지 화면 눈·코 식별, 드래그 시 유리 좌표 일관성을 시각 검증한다.

• MVP에서는 사진 리라이팅을 제외한다. 사진의 기존 촬영 조명은 유지하고, 추가 광원은 Mosaic 유리 표면의 셀별 반사에만 적용한다. 공통 광원의 가로·세로 위치와 광택 강도를 조절하며, 셀별 반사는 시점에 따라 변하고 시간에 따른 임의 반짝임은 사용하지 않는다. 광택 0은 기존 Mosaic, Distortion 0은 기존 무효과 출력을 유지한다.

• 최신 시각 보정 목표: 참고 이미지처럼 사각 셀마다 눈·코·얼굴 조각의 위치와 배율이 달라져야 한다. 원형 물결 왜곡과 검은 격자선만 강해지는 결과는 완료로 인정하지 않는다.

• Mosaic 보정은 기존 Depth/RenderTarget을 유지하고 셀별 샘플 영역·확대·압축과 미세한 퍼짐을 조절한다. 단색 pixelation으로 대체하지 않는다. 같은 사진·같은 구도의 정지 화면에서 시각 목표를 먼저 비교하고 시점 변화도 재검증한다.

• 최신 수정 지시서는 docs/depth-task-brief.txt이다. 기존 평면 기반 설명과 충돌하면 이 수정 지시서를 우선한다.

• 기존 Mosaic/Reeded/Frosted 렌즈 효과를 보존하면서 PetDepthMesh → WebGLRenderTarget → Glass Shader의 2-pass 구조로 확장한다.

• 반드시 Glass OFF에서 코·눈·얼굴의 실제 카메라 parallax를 먼저 검증하고, 그 다음 RenderTarget과 Glass 효과를 연결한다.

• 사용자가 지정한 테스트 사진은 public/assets/sample-pet.png이다. 테스트 depth는 수작업/절차적 근사임을 명시하며 AI 추정 또는 실제 측정값으로 표현하지 않는다. 사진은 로컬 테스트에만 사용하며 게시 권한으로 간주하지 않는다.

• Depth 내부 규칙은 0=뒤, 1=앞이다. 이번에는 RGB+Depth 입력과 정적 depth를 우선하며 AI 추정 및 영상 매 프레임 depth 추정은 후순위다.

• docs/task-brief.txt에 사용자 작업지시서를 보존한다.

• Vite + TypeScript + Three.js + GLSL, Vanilla TS를 사용한다. React와 별도 백엔드는 사용하지 않는다.

• 미디어 처리는 브라우저 로컬에서 수행한다.

• 핵심은 PetPlane 앞에 위치한 GlassPlane의 시점 의존 굴절이다. Mosaic는 단순 pixelation이나 이미지 전체 평행 이동으로 대체하지 않는다.

• 원문 구현 우선순위를 따른다. Scene → 이미지 Texture → PetPlane → GlassPlane → Pointer drag → Mosaic → 시점 굴절 → VideoTexture → Reeded → Frosted → Gyroscope → UI polish.

• 모바일 우선, 미디어 contain, 자원 dispose/revoke, DPR 상한, 부드러운 시점 보간을 지킨다.

Karpathy Guidelines 적용

• 사용자가 요청한 karpathy-guidelines를 적용한다. 로컬 위치: C:/Users/horoli/.codex/skills/karpathy-guidelines/SKILL.md.
• 코딩 전에 가정과 완료 기준을 명시하고 불확실한 중요한 요구사항을 드러낸다.
• 요구사항을 충족하는 최소 구현을 우선하며 불필요한 추상화와 범위 밖 기능은 추가하지 않는다.
• 기존 코드가 생긴 이후에는 작업과 직접 관련 있는 부분만 수정한다.
• 빌드·타입 검사와 실제 동작 검증을 구분하고, 실행하지 못한 검증을 통과했다고 보고하지 않는다.
• 주요 단계와 최종 결과에 수정 파일, 구현 기능, 미완료 항목, 실행 방법, 셰이더 원리, 다음 개선점을 간단히 보고한다.