# 힐링 레퍼런스 젤리 세 종류 구현 계획

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans. Native 방식으로 직접 구현하고 마지막에 최종 독립 리뷰를 수행한다.

**Goal:** 기존 용과를 유지하며 1번 은하·2/3번 오팔·5번 비늘 젤리를 208~210판으로 추가한다.

**Architecture:** 기존 HealingScene의 입체 절단·재절단을 재사용한다. 새 높이 프로필과 원본 좌표의 공통 3D 색상장을 추가하고, 조각별 절단 반공간으로 내부 시선 구간을 제한한다. 5번 표면 판은 몸체를 감싸는 독립 메시로 생성하고 기존 평면 절단 연산을 활용한다.

**Tech Stack:** TypeScript, Three.js/WebGL2, GLSL, Vite, Vitest, Playwright. 새 의존성 없음.

**Spec:** `docs/superpowers/specs/2026-11-01-healing-reference-jellies-design.md`

## Global Constraints

- 기존 206판 용과·207판 오로라의 ID·외관·진행 기록 유지. 새 ID는 `healing-galaxy`, `healing-opal`, `healing-crystal-scales`.
- 5번은 특정 과일로 해석하지 않고 레퍼런스의 윤곽·겹친 투명 판·연두색 끝·기포를 구현한다. 과육·씨앗 없음.
- 원본 좌표·조각별 반공간·프레임 분할 자원 준비·취소·해제를 유지한다. 품질 임계값 완화 금지.
- 사용자 승인: 전체 시각 검수, 별도 브랜치, Native 실행. 기존 레퍼런스 이동 등 사용자 파일 변경은 보존한다.
- 캡처는 `.playwright-mcp/healing-reference-jellies/`, 모바일 390×844·데스크톱 1280×800 기본 18장. 최종 독립 리뷰 `gpt-6.1-sol` / `medium`.
- Android/iOS 기기 테스트·배포·main 병합/푸시는 범위 밖. UI 이름은 CSV에 영어·한국어 등록.

## Review Focus

1. 기울어진 조각 재절단에서 반공간을 새 월드 좌표로 오해하여 내부 무늬가 잘못 나오는 경우 — Task 2의 평면 교차 구간·회전 절단 검사.
2. 같은 재질 프로그램을 쓰는 두 조각의 유니폼이 섞이는 경우 — Task 2의 조각별 서로 다른 평면·자원 해제 검사.
3. 5번 판이 잘린 반대편에 다시 나타나거나 손잡이 충돌 외곽에서 누락되는 경우 — Task 3의 판 반공간·면적 보존과 실제 재절단 E2E.
4. 최종 210판에서 Next 버튼을 가정한 기존 E2E가 잘못되는 경우 — Task 4의 마지막 Finish·재방문·저장 검사.
5. 미세 반짝이의 모아레·과도한 반사·단면 색 소실 — Task 4의 양 해상도·저품질 캡처와 시각 독립 리뷰.

## Task 1: 새 종류·형상·편성 연결

**Files:** `src/stages/{LevelDefinition,HealingStages}.ts`, `src/stages/stage-order.json`, `src/core/healing/{HealingGeometry,HealingRender}.ts`, `src/core/modes/HealingMode.ts`, `src/jelly/{JellyShapes,JellyMaterial,JellyPiece}.ts`, `src/ui/JellyThumbnail.ts`, `src/i18n/texts.csv`, `tests/{HealingLevels,HealingGeometry,DestructionLevels}.test.ts`, `tests/meshFuzz.ts`.

**Interfaces:** `HealingKind`에 `'galaxy' | 'opal' | 'crystal-scales'` 추가. `healingHeight(kind, p): {bottom:number; top:number}`와 `healingNormal`은 새 입체 프로필을 지원. 스테이지 ID는 위 Global Constraints와 동일.

- [x] 먼저 편성 테스트를 206~210으로 확장하고 기존 206/207 유지·신규 종류 도감 복원 검사. 형상 테스트는 새 구체의 위·아래 곡면, 유한 정점/법선, 잘린 두 면의 좌표 일치를 검사.
- [x] RED: `npx vitest run tests/HealingLevels.test.ts tests/HealingGeometry.test.ts` — 신규 레벨/형상 부재로 실패 확인.
- [x] 새 종류와 둥근 구체·끝이 좁아지는 5번 프로필, 등록·번역·기본 재질을 연결. 기존 두 종류의 렌더링 코드는 유지.
- [x] GREEN: 위 테스트와 `npm run build` — 통과. 관련 편성의 고정 개수 단언은 기존 항목 보존을 확인한 뒤 수정.
- [x] 관련 파일만 커밋하고 ledger에 결과 기록.

## Task 2: 원본 공간 내부 재질과 조각별 깊이 제한

**Files:** 새 `src/core/healing/HealingVolume.ts`, 새 `src/jelly/shaders/healingReference.glsl.ts`, `src/core/healing/{HealingRender,HealingScene}.ts`, `src/jelly/JellyMaterial.ts`, 새 `tests/HealingVolume.test.ts`.

**Interfaces:** `createHealingVolume(planes: readonly THREE.Plane[])`은 조각별 평면 데이터 텍스처·count 유니폼과 `dispose()`를 제공. `healingReferenceGlsl(kind)`은 원본 좌표의 색·밀도·기포/반짝이 함수를 반환. 새 재질에만 주입하며 일반 미리보기도 같은 색상장 사용.

- [x] RED 테스트: 서로 다른 두 평면 데이터의 독립성·법선/상수 보존·24회 초과 절단 평면 누락 없음·dispose 단발·자른 조각들의 실제 반공간 유지.
- [x] RED: `npx vitest run tests/HealingVolume.test.ts` — 새 구현 부재로 실패.
- [x] 평면을 텍스처로 전달하여 셰이더 재컴파일 없이 현재 조각의 시선 구간을 자른다. 원래 입체와 교차한 구간에서 제한 횟수로 색·밀도를 적분하고 단면은 표면 색상장을 선명하게 표현한다. 평면·텍스처는 makeChunk 준비 및 취소/해제와 함께 관리한다.
- [x] 은하의 구름/반짝이·오팔의 넓은 색 번짐/내부 색층·5번의 분홍 투명도/기포를 별도 매개변수로 구현한다. 화면 미분으로 미세 무늬를 필터링한다.
- [x] GREEN: `npx vitest run tests/HealingVolume.test.ts tests/HealingScene.test.ts tests/HealingMultiCut.test.ts` 및 빌드. 브라우저 실제 GLSL 컴파일은 Task 4에서 확인.
- [x] 관련 파일 커밋·ledger 갱신.

## Task 3: 5번 몸체를 감싸는 판 구조

**Files:** 새 `src/core/healing/HealingScales.ts`, `src/core/healing/{HealingRender,HealingScene}.ts`, `tests/HealingScales.test.ts`.

**Interfaces:** `crystalScales(part: SlicePart, planes?: readonly THREE.Plane[]): THREE.Group`. 기존 `dragonScales`는 변경하지 않는다. 표면 판을 삼각형별 반공간으로 자르는 공통 연산은 필요 시 재사용한다.

- [x] RED: 5번 판의 비스듬한 절단·두 면의 면적 합 보존·재절단의 모든 반공간·유한 법선 검사 추가. 실행: `npx vitest run tests/HealingScales.test.ts`.
- [x] 몸체 곡면을 감싸는 겹친 판을 낮게 밀착시키고 끝만 연두색으로 솟게 한다. 사진처럼 판 경계와 투명한 분홍 두께가 보이게 하며 기존 용과의 길게 뻗은 잎을 복제하지 않는다.
- [x] makeChunk의 판 부착·지지점·손잡이 안전 외곽·변형·해제를 연결.
- [x] GREEN: 비늘·장면·칼 안전성 테스트 통과 및 빌드. 관련 파일 커밋·ledger 갱신.

## Task 4: 실제 입력·시각 검수·최종 리뷰

**Files:** `e2e/healing.spec.ts`, 새 `e2e/healing-reference.spec.ts`, `.playwright-mcp/healing-reference-jellies/`, `PROGRESS.md`, 본 계획 검증 기록.

- [x] 새 세 종류의 실제 입력 첫 절단·재절단·별 3개 단발·다음 이동·마지막 Finish·도감 재방문 검사 추가. 기존 E2E의 마지막 Next 가정은 실제 버튼에 맞게 보정.
- [x] `npm test`·`npm run build` — 전체 단위·strict TypeScript·Vite 통과. 최초 실패는 로그에 남기고 원인/재실행 결과 구분.
- [x] 동일 dist를 읽는 전용 preview 서버에서 힐링 E2E를 모바일·데스크톱 Chromium으로 실행. console/pageerror의 WebGL·GLSL 오류 없음.
- [x] 두 해상도×세 종류×절단 전/첫 단면/재절단 기본 18장 캡처. 레퍼런스와 색·윤곽·판 구조·속살·무늬 연결·화면 가림을 비교하고 필요 시 수정·재촬영. 저품질에서도 종류 식별과 정상 출력 확인.
- [x] 셰이더 통계·준비 시간·프레임 시간·자원 회수를 기록. 실기기 측정과 구분.
- [x] `gpt-6.1-sol` / `medium` 최종 독립 리뷰에 코드·설계·계획·캡처·검증 로그 제공. 중요한 지적은 회귀 테스트 RED→GREEN으로 수정하고 전체 단위 재검증.
- [x] PROGRESS·계획에 실제 결과 및 미검증을 기록하고 작업 브랜치에 커밋. main 병합·푸시는 하지 않는다.


## 실행 기록

- 2026-11-01: 수정 설계와 Native·별도 브랜치 실행 승인. 브랜치 `codex/healing-reference-jellies` 생성. 기존 사용자 ASMR/레퍼런스 파일 변경 보존.

- 기준 전체 단위: 222파일 / 3,350개 통과.
- 최초 전체 단위: 221파일 통과 / 2파일 실패, 3,376개 통과 / 2개 실패. 공장 편성 검사 207→210 반영 및 5번 공통 미리보기 외곽 48→32분할로 수정. 최소각 1° 기준은 유지했고 힐링 퍼즈·공장 21개 단독 통과.
- 신규 E2E: 두 해상도 10개 통과(고품질 절단·재절단·저장·도감·History 재플레이·Back·마지막 Finish, 저품질, 반복 진입 자원). 기존 용과·오로라 회귀 8개 통과. 마지막 비늘 색 조정 뒤 해당 종류 고품질 2개와 저품질 2개 재검증 통과.
- 첫 데스크톱 검사에서 jellyPixelsVisible 실패: 이 도우미는 PieceStore의 경계를 쓰므로 전용 HealingScene에 유효 경계가 없음. 힐링 상태의 실제 경계, 셰이더 오류, 직접 캡처를 사용한다. 이 선택의 한계는 힐링에 기존 자동 픽셀 차이 검사를 적용하지 않는다는 점이다.
- 최초 마지막 Finish 검사 실패: 앞선 미완료 판이 남아 Next Jelly가 정상 표시됨. 전체 완료 저장 fixture를 넣어 실제 마지막 완료·History 재플레이 Back 경로를 각각 검증했다.
- 첫 절단 link 6회는 칼 알파 변형 전환(4회)과 원본 프로그램 참조 조기 해제(같은 소스 재링크 2회)였다. 칼 알파 프로그램 유지·자식 첫 렌더 이후 회수로 수정, 두 회귀 테스트 RED→GREEN. 최종 신규 3종×양 해상도 첫 절단·재절단 링크/미완료 링크 모두 0회.
- 캡처: 기본 18장(고품질, 세 종류×절단 전/첫 단면/재절단×두 해상도) + 저품질 6장. `.playwright-mcp/healing-reference-jellies/` 보관. 모바일 신규 세 종류만 카메라를 확대하고 도움말과 칼·조각 가림을 대조했다.
- 반복 진입 3회에서 같은 시점의 GPU 자원 수 유지(56 geometry / 9 texture / 23 program). 실기기 측정은 아니다.
- 최종 전체 단위: 223파일 / 3,378개 통과(71.17초). strict TypeScript/Vite 빌드 통과. 최종 독립 리뷰 `gpt-6.1-sol` / `medium` 완료, Critical/Important/Minor 각0건. 리뷰 범위 `038ced9..1695416`.

## 최종 리뷰와 판정 결정

- 독립 리뷰는 코드·원본 레퍼런스·양 해상도 접촉 시트·주요 원본 PNG·저품질6장·자원/성능 JSON·테스트 로그를 읽고 병합 준비로 판정했다. 미뤄 둔 Minor는 없다.
- **판정 결정 1:** 기존 `jellyPixelsVisible`은 전용 힐링 경계를 지원하지 않으므로 실제 경계·GLSL 오류·캡처와 독립 시각 리뷰를 사용했다. 이 선택은 자동 픽셀 차이 회귀 검사의 공백을 남기며, 이후 외관 변경에도 실제 캡처 확인이 필요하다.
- **판정 결정 2:** 실기기 외관·성능·촉감은 기본 범위 밖이다. 브라우저 해상도 검사 완료로 기기 검증을 대신하지 않는다. 실제 모바일 GPU의 성능 차이와 촉감은 후속 실기기 확인이 필요하다.
- **판정 결정 3:** 정지 캡처만으로 시간적 반짝임/모아레를 확정하지 않는다. 원본 좌표 고정·화면 미분 필터와 실제 입력 E2E를 확인했지만 움직임의 시각적 체감 판정은 별도 확인 항목이다.
- **판정 결정 4:** 사용자 ASMR·레퍼런스 파일 이동은 구현 커밋에 포함하지 않고 보존했다. 그 이동 자체의 정합성은 이번 최종 리뷰로 보증하지 않는다.
- **판정 결정 5:** 운영 배포는 범위 밖으로 유지했다. 작업 결과는 `codex/healing-reference-jellies` 브랜치에 보관하며, 운영에서의 동작은 배포 후 별도 확인이 필요하다.

## 후속 조정: 세 종류의 투명도 (2026-11-01)

사용자가 세 종류 모두 조금 더 투명하게 조정하도록 요청했다. 같은 브랜치·Native·전체 시각 검수 선택을 유지한다. 기존 종류에는 적용하지 않는다.

- 대상: `src/core/healing/HealingAppearance.ts`의 신규3종 물리 재질 매개변수만 조정한다.
- [x] 외피 투과율을 은하0.72→0.82, 오팔0.25→0.42, 비늘0.91→0.97로 높인다. 흡수 거리1.8→2.5, 단면 투과 배율0.40→0.58로 늘려 두꺼운 부분과 단면에도 빛이 더 통하게 한다. 오팔 우윳빛·입체 무늬·기포는 유지한다.
- [x] `npm run build` 및 기존 신규 젤리 E2E10개로 실제 GLSL·첫 절단/재절단·도감/저장·저품질·자원 회수를 확인한다. 단순 재질 수치 변경을 그대로 복제하는 단위 테스트는 추가하지 않는다.
- [x] 기존 범위의 고품질18장·저품질6장을 다시 캡처하고 이전 PNG(`.playwright-mcp/healing-reference-jellies/transparency-before/`)와 비교한다.
- [x] `gpt-6.1-sol` / `medium` 최종 독립 리뷰 후 실제 검증 결과를 기록하고 작업 브랜치에 커밋한다.

- 후속 빌드 및 양 해상도 E2E10개 통과. 고품질18장·저품질6장을 갱신하여 전후 비교했다. 코드 변경은 신규 재질의 세 매개변수에 한정하며 전체 단위는 반복하지 않았다.

- 후속 독립 리뷰: `gpt-6.1-sol` / `medium`, `0dbc020..9d36563`, Critical/Important/Minor 각0건. 전후 변화는 미세하며 종류별 무늬와 단면 읽힘은 유지한다. 정확한 투명도 선호·실기기·시간적 반짝임 체감은 정지 캡처로 확정하지 않는다.