# 힐링 모드 파트 2 (212~214판)

## 의도

기존 힐링 판(206~210)은 한 손가락 평행 이동 + 두 손가락 회전으로 조준한다. 플레이 피드백에서 이 조준이 불편하다는 의견이 많았다. 파트 1은 그대로 두고, 212~214판에 **선을 그어 조준하는** 힐링 모드 파트 2를 새로 만든다. 조준 방식은 외부 작품 Spider Melon(three.js)의 손칼 조작을 참고한다. 손가락 하나로 젤리를 가로지르는 선을 그으면, 칼이 그 선 위로 따라와 위치와 방향이 한 번에 정해진다.

힐링 모드에서는 Slice mode(칼을 직접 내려 써는 단계)도 핵심 경험이다. 그래서 아티팩트처럼 손을 떼면 자동으로 자르지 않는다. 손을 떼는 순간 Slice mode로 들어가고, 이후는 플레이어가 직접 칼을 내린다. 젤리는 실제보다 훨씬 예쁜 비현실적인 젤리이며, 단면에는 젤리마다 다른 신비로운 특수 효과를 준다.

## 목표

- 한 번의 선 긋기로 위치와 방향을 정하는 조준. 두 손가락이 필요 없다.
- 선이 지나간 조각들을 칼끝을 기울여 당겨 썰며 차례로 가르는 Slice mode.
- 레퍼런스 세 장을 바탕으로 한 별·고양이·왕관 젤리 세 판. 실제보다 훨씬 예쁘게 만든다.
- 젤리마다 주제가 다른 단면 효과: 열릴 때 반짝임이 크게 퍼졌다가 은은하게 가라앉는다.

## 비목표

- 파트 1(206~210판)의 조작·외관·동작 변경.
- 아티팩트의 soft body 물리(XPBD), 조각 잡아당기기, 거미 같은 캐릭터.
- 새 효과음 자산. 기존 승인 샘플과 소리 규칙을 그대로 쓴다.
- 결과 카드, 제한 시간, 실패, 정확도 평가.

## 반목표 (동작해도 실패로 본다)

- 파트 1 판의 동작이나 화면이 조금이라도 바뀐다.
- 선을 긋는 도중이나 손을 떼는 순간 칼이 저절로 내려가 썰린다. 썰기는 반드시 Slice mode에서 새로 접촉해 드래그해야 시작된다.
- 단면 효과가 젤리 속살을 가려 탁해 보이거나, 효과 때문에 단면 무늬가 조각 위에서 미끄러진다.
- 오목한 단면에 구멍·겹침·찢어짐이 보인다.

## 제약

- 프로젝트 규칙(AGENTS.md)을 따른다. 모드는 `Game`을 import하지 않고 `ModeHost`를 쓴다. `Game`에 모드별 분기를 추가하지 않는다. 순수 기하 로직(`src/geometry/`·`src/stages/`)은 three를 import하지 않는다. 새 조각 메시는 프레임을 나눠 준비하고, 입력 처리 중에 동기 메시를 만들지 않는다. 입력 취소 순서·`GameClock`·`Lifecycle` 규칙을 지킨다.
- 조각은 구멍 없는 단순 다각형(오목 허용) 단면에서 출발한다. 메시·퍼즈 검사의 품질 임계값을 완화하지 않는다.
- 절단음 규칙을 유지한다. long은 썰기 중 반복하고, 도마 접촉 시 기존 `boardTap`을 한 번 낸다. 별도 마무리 소리는 없다.
- 순서 변경은 `src/stages/stage-order.json`에서만 한다. 고유 ID와 `legacy-stage-order.json`은 수정하지 않는다.
- 제품 UI는 영어가 기본이고, 실행 환경의 주 언어가 한국어면 한국어를 표시한다. 문구는 `src/i18n/texts.csv`에 추가한다.
- 게임 자산은 절차 생성한다. 레퍼런스 이미지는 외형 참고 자료로만 쓴다.
- `window.__jellyDebug`에 파트 2 상태를 노출하고 `e2e/debug-api.spec.ts`를 갱신한다.

## 검토한 방식

| 방식 | 내용 | 판단 |
|---|---|---|
| A. 기존 `HealingMode`에 분기 추가 | 장면·연출을 그대로 쓰고 판 설정으로 제스처·형상을 바꾼다. | 코드는 가장 적다. 하지만 1,100줄짜리 `HealingScene`에 분기가 늘고, 오목 단면 처리를 공용 경로에 넣으면 파트 1 동작이 바뀔 수 있다. 파트 1을 그대로 두라는 요구와 충돌한다. |
| **B. 새 `HealingPart2Mode` + 공용 부품 재사용** | 새 GameMode가 선 긋기 조준·당겨 썰기·순차 절단을 맡는다. 칼 자원·착지·배치·진행·튜토리얼 틀은 기존 힐링 모듈을 가져다 쓴다. 오목 절단기와 새 형상은 파트 2 전용으로 둔다. | **사용자 선택.** 파트 1 코드 경로를 거의 건드리지 않고, 새 절단기를 212~214판에서만 검증한다. 공용 부분을 떼어 내는 작업과 일부 중복 코드는 감수한다. |
| C. 일반 모드의 `PieceStore` 사용 | 오목 절단을 이미 지원한다. | 조각을 평면 다각형에 두께를 더한 형태로만 다뤄서, 기울어 누운 조각의 재절단과 왕관 같은 입체 형상을 표현할 수 없다. 제외했다. |

## 편성과 저장

- 편성 맨 끝(무한 자르기 `endless-jelly` 211판 뒤)에 세 판을 추가한다. 표시 번호는 212·213·214다. (처음 설계는 211~213이었으나, 병합 직전 main에 무한 자르기가 211판으로 먼저 배포되어 사용자 결정으로 한 칸씩 뒤로 옮겼다. 2026-11-02)
- 고유 ID와 종류: `healing-star-galaxy`(별 은하), `healing-cat-paws`(발바닥 고양이), `healing-jewel-crown`(보석 왕관). 종류별 고유 ID로 별·진행·도감을 저장한다.
- 파트 1과 같은 진행 규칙을 쓴다. 첫 단면이 실제로 열리는 순간 고정 3별을 한 번 기록하고, 재방문이나 반복 썰기로 별이 쌓이지 않는다. 결과 카드나 자동 이동 없이 이동 버튼을 표시한다. 일반 진행은 `Next Jelly`, 전체 마지막인 214판은 `Finish`, 도감 재방문은 `Back`이다.
- 세 판 모두 상점 장착 상태와 관계없이 파트 1의 힐링 전용 긴 식칼을 쓴다.

## 조작

### 1. 선 긋기 조준

- 한 손가락으로 화면 어디서든 드래그를 시작해 선을 긋는다. 긋는 동안 화면에 점선을 표시한다. 칼은 35% 불투명도로 그 선 위에 떠서 따라온다. 칼 위치는 선의 중점, 방향은 선 방향이고, 부드럽게 따라붙는다.
- 그은 선분이 **실제로 지나간 조각만** 절단 대상이다. 선을 연장한 직선에만 걸리는 조각은 대상이 아니다. 긋는 동안 대상 조각 위에 실제 곡면 절단 경로를 미리 표시한다. 여러 조각이 대상이면 안내에 개수를 표시한다.
- 지나감 판정과 월드 절단선 변환 **(설계자 판단: 플레이어가 보는 대로 고르게 한다)**
  - 지나감은 화면에 보이는 조각 실루엣을 선분이 가로질렀는지로 판정한다.
  - 칼은 곧은 날 하나이므로 모든 대상이 공유하는 월드 연직 절단 평면을 하나 정한다. 화면 선분을 후보 대상들의 윗면 평균 높이의 수평면에 투영한 직선이다.
  - 그 연직 평면이 실제로 나누지 못하는 후보는 대상에서 뺀다. 키 큰 돌출부의 투영 어긋남이 이 단계에서 걸러진다.
- 손잡이는 선을 어느 방향으로 긋든 화면 아래쪽(플레이어 쪽)에 둔다. 선이 화면에서 거의 수평이면 오른쪽에 둔다. 손잡이 자리를 이웃 조각이 막을 때의 처리는 파트 1 규칙(가까운 빈자리로 비키기, 불가능하면 방향을 바꾸라는 안내와 함께 조준 유지)을 따른다.
- 손을 정상적으로 떼는 순간 대상이 하나 이상이면 조준을 확정하고 **Slice mode**로 들어간다. 칼은 불투명해지고 HUD에 Slice mode를 표시한다. 이 순간 칼은 내려가지 않는다.
- 대상이 없으면(허공에 그은 선, 너무 짧은 선, 유효한 두 조각 이상을 만들 수 없는 선) Slice mode로 들어가지 않는다. "젤리를 가로질러 그어 주세요"류의 안내를 튜토리얼 제목 자리에 띄워 다음 선을 시작할 때까지 보이고, 조준 상태를 유지한다. (시각 검수 반영: 긴 문장이 젤리 위 판정 문구 층에서 세로 화면 밖으로 넘쳐, 튜토리얼 제목 자리에 다음 선을 시작할 때까지 보인다.)
- 두 번째 손가락은 무시한다. 포인터 취소·숨김은 조준 확정으로 처리하지 않는다.
- 데스크톱 마우스도 같은 방식으로 드래그해 긋는다. Shift 회전은 없다.

### 2. Slice mode — 당겨 썰기

- 새로 접촉해 화면 아래로 끌면 칼이 내려가고, 위로 끌면 올라온다. 손을 멈추면 그 깊이에 머문다. 끄는 거리에 따른 깊이 비율은 파트 1과 같은 감각으로 시작해 조정한다.
- 칼은 선의 먼 쪽 끝(손잡이 반대쪽)에서 **칼끝을 대각선 아래로 기울인 채** 들어간다. 깊이가 늘수록 칼이 **손잡이 쪽으로 당겨지며** 선을 따라 미끄러진다. 날이 지나는 순서대로 칼끝 쪽 조각부터 손잡이 쪽 조각까지 차례로 갈라진다. 각 조각은 칼이 지나간 윗부분부터 틈이 보인다.
- 칼날 경로에 대상이 아닌 조각이 있으면, 칼이 내려가면서 칼 옆면으로 그 조각을 살짝 밀어 비켜 놓는다(사용자 선택). 선이 지나가지 않은 조각과, 선은 지나갔지만 부스러기 규칙으로 빠진 조각이 모두 해당한다. 밀린 조각은 도마 위에 자리를 잡고 원래 형태를 유지한다. 날이 조각을 뚫고 지나가 보이면 안 된다. 밀 공간이 없을 때는 파트 1의 손잡이 자리 규칙처럼, 방향을 바꾸라는 안내와 함께 조준으로 돌아간다. 위로 끌어 칼이 빠질 때 밀린 조각은 제자리로 돌아오지 않는다. 대신 접촉 전 취소·`Reposition`으로 되돌리면 원래 자리로 돌아온다. **(설계자 판단: 실제 젤리처럼 밀린 자리에 남되, 이번 칼질 자체를 무르면 함께 복원한다.)**
- 대상 조각이 하나일 때도 같은 동작이지만 기울기가 작아 거의 수평으로 내려간다. 칼날보다 긴 선을 그었다면 미끄러지는 거리로 끝 조각까지 덮는다.
- 도마에 닿는 순간(깊이 1) 날은 수평이 되고, 이번 칼질의 대상 조각 전부가 그 자리에 놓인 자세에서 나뉜다. 파트 1처럼 단면이 자동으로 벌어지고 조각이 도마에 눕는다. 이것을 한 번의 칼질로 기록한다.
- 도마 접촉 전에 위로 끌면 같은 경로를 되밟아 칼이 빠지고 조각은 복원된다. 접촉 전 포인터 취소·숨김은 미완 절단을 되돌리고, 접촉 후에는 분리 상태를 보존한다.
- 도마 접촉 전까지는 `Reposition` 버튼으로 조준 단계로 돌아갈 수 있다. Slice mode에서는 드래그가 깊이 조절이라 선을 새로 그을 수 없기 때문이다.
- 썰기 동안 long 절단음이 반복되고, 손을 멈추면 멈춘다. 도마 접촉 시 `boardTap`을 한 번 낸다.
- 절단 후 칼은 도마에서 들어 올려져 대기 위치로 돌아가고, 다시 선 긋기 조준을 기다린다.

## 절단 기하

- 파트 1은 단면을 무게중심에서 부채꼴로 채우고 한 번에 두 조각만 나온다고 가정한다(`HealingSolid.ts`의 캡 생성, `splitConvex`). 파트 2에서는 별의 팔·고양이 귀를 가로지르면 단면이 오목해지고, 한쪽이 떨어진 여러 덩어리가 될 수 있다.
- 파트 2 전용 절단기를 만든다. 요구 사항은 세 가지다.
  - 평면과 메시의 교선을 닫힌 고리들로 추적한다.
  - 각 고리를 오목 다각형 캡으로 채운다. 기존 `CapTriangulator`(제약 들로네) 재사용을 검토한다.
  - 결과를 연결 성분별로 분리해 각각 독립 조각으로 만든다.
- 대상 조각은 그 조각을 지나는 연직 절단 평면 전체로 나눈다. 선분이 조각의 한 팔만 지나도 같은 평면이 다른 팔을 지나면 그 팔도 갈라진다. **(설계자 판단: 실제 칼은 평면으로 내려가고, 선분 끝에서 칼이 끊기는 표현은 부자연스럽다.)**
- 나눈 결과 중 하나라도 최소 크기(면적·두께) 미만의 부스러기가 생기는 조각은 이번 대상에서 제외한다. 남는 대상이 없으면 조준을 확정하지 않는다. 최소 크기는 파트 1 수치에서 시작한다.
- 단면 무늬·내부 장식은 원본 젤리의 입체 좌표로 계산한다. 맞붙은 두 단면의 무늬가 이어지고, 조각이 움직이거나 기울어도 무늬가 표면에서 미끄러지지 않아야 한다. 기울어 누운 조각도 그 자세에서 다시 자를 수 있다.
- 메시 준비는 프레임을 나눠 진행한다. 조준이 바뀌면 이전 준비 결과를 폐기하고, 이전 판의 자원이 새 판으로 넘어가지 않게 한다. 새 절단기는 기존 메시 검증기·퍼즈 테스트 기준을 통과해야 한다.

## 젤리 세 종류

공통: 실제보다 훨씬 예쁜 비현실적인 젤리다. 투명도·광택·굴절을 과장하고, 내부 장식은 맑은 젤리 속에 떠 있는 듯 보여야 한다. 형상은 위에서 본 윤곽마다 높이 함수를 붙여 만든다. 귀·뿔·진주 같은 돌출은 높이로 표현한다. **(설계자 판단: 기존 높이 함수 구조와 맞고, 재절단·착지 계산을 재사용할 수 있다. 표현이 부족하면 구현 중 다시 알린다.)**

| 판 | 레퍼런스 | 자르기 전 | 단면 효과 |
|---|---|---|---|
| 212 별 은하 | `references/HealingJelly/HealingJelly_6.png` | 모서리가 둥근 두툼한 오각 별. 맑은 하늘색~남색 젤리 안에 별자리 점과 작은 별, 파스텔 행성 구슬, 소용돌이 은하가 깊이를 달리해 떠 있다. | 단면이 깊은 남색의 투명한 밤하늘처럼 보이고, 별가루가 깊이를 달리하며 반짝인다. 칼이 지나간 자리에 은하수 띠가 은은하게 흐른다. 행성 구슬을 가르면 구슬 속 줄무늬가 드러난다. |
| 213 발바닥 고양이 | `references/HealingJelly/HealingJelly_7.png` | 웅크린 고양이 모양. 귀가 솟고, 얼굴에 볼록한 눈과 반사광이 있다. 맑은 장밋빛 젤리 안에 노랑·주황·파랑·분홍 발바닥 젤리와 작은 사탕 조각이 박혀 있다. | 장밋빛 속살이 유리처럼 맑게 비친다. 단면 가장자리에 분홍·라벤더 빛무리가 감돌고, 잘린 발바닥 젤리 단면은 파스텔색으로 부드럽게 빛난다. |
| 214 보석 왕관 | `references/HealingJelly/HealingJelly_8.png` | 샴페인 골드 왕관. 아치형 뿔 끝에 진주가 달리고 아래 띠에 작은 진주가 박혀 있다. 아치 사이로 맑은 젤리와 그 안의 빨강·파랑 보석, 반짝이 가루가 보인다. | 투명한 속살에서 보석처럼 무지갯빛이 굴절된다. 잘린 보석 단면은 깎은 면마다 빛을 반사하고, 금빛 반짝이 가루가 단면 위로 흩날리듯 반짝인다. 금빛 외피의 단면은 얇은 금 테두리로 보인다. |

별 은하의 은하수 띠는 칼의 실제 궤적을 저장하지 않는다. 단면(=절단 평면) 위에 원본 입체 좌표로 고정한 띠이며, 시간에 따라 흐르는 것은 띠의 밝기뿐이다. **(설계자 판단: 자원 인계 범위를 늘리지 않고, 무늬가 미끄러지지 않는다는 반목표를 지킨다.)**

단면 효과의 공통 시간 흐름: 단면이 처음 열릴 때 반짝임이 크게 퍼진다(1초 안팎). 그 뒤 은은한 반짝임으로 가라앉아 계속 유지된다. 이미 열린 단면을 다시 잘라 생긴 새 단면도 같은 흐름을 따른다. 저품질 렌더 설정에서는 반짝임 밀도·굴절을 줄이되 각 젤리의 주제 색과 투명감은 유지한다.

## 튜토리얼과 문구

- 파트 1의 튜토리얼 형식(첫 절단 단계 안내, 재절단 때 축소, Help로 다시 펼침)을 유지하고 내용만 바꾼다.
  - 조준: 젤리를 가로질러 선을 긋는다.
  - 손을 떼면 Slice mode가 된다.
  - 아래로 당겨 썬다(위로 끌면 칼이 올라온다).
  - 도마에 닿으면 단면이 열린다. 다음 이동은 직접 고른다.
- 새 문구는 영어·한국어로 `texts.csv`에 추가한다.

## 검증

### 자동 검증

- **단위 테스트**
  - 선분 → 절단선 변환, 짧은 선·허공 선 거부.
  - 선분이 실제로 지나간 조각만 대상으로 고르는지.
  - 오목 단면의 고리 추적·캡 채우기·연결 성분 분리. 별의 두 팔을 동시에 자르는 경우를 포함한다.
  - 메시 검증 통과.
  - 손잡이 방향 규칙.
  - 당겨 썰기에서 깊이 → 칼 자세·조각별 갈라짐 순서.
  - 칼날 경로의 비대상 조각 밀어내기, 밀 공간이 없을 때 조준 복귀, 취소·`Reposition` 시 원위치 복원.
  - 접촉 단발, 접촉 전 되돌리기·취소 경계, 첫 단면 3별의 멱등성.
- **퍼즈**: 새 절단기에 기존 메시 퍼즈 기준을 적용한다.
- **E2E**(모바일 기능 프로젝트 기준): 일반 터치 경로로 다음을 확인한다.
  - 선 긋기 → 손 뗌 → Slice mode 진입. 이때 깊이 0을 유지하는지.
  - 아래로 당겨 썰기, 도마 접촉.
  - 여러 조각을 한 선으로 썰기.
  - `Reposition`.
  - 허공 선 거부.
  - `Next Jelly`·`Finish`·`Back`.
- `__jellyDebug`에 파트 2 상태를 노출한다: 단계, 선분, 대상 조각, 깊이, 칼 자세, 조각별 갈라짐 상태, 단면 효과 시간. 디버그 API 스펙 테스트도 갱신한다.
- 파트 1 회귀: 기존 힐링 단위 테스트와 E2E가 그대로 통과해야 한다.

### 전체 시각 검수 (사용자 선택)

- 범위: 3판 × 상태 5개 × 해상도 2개(모바일 390×844, 데스크톱 1280×800)로 약 30장. 저품질 설정은 모바일에서 단면이 열린 상태 3장을 추가한다.
  - 상태 5개는 대기, 선 긋기 중, 여러 조각 대각선 썰기 중, 단면이 열리는 반짝임, 가라앉은 은은한 반짝임이다.
- 구현자가 캡처해 레퍼런스와 대조하고, 수정·재촬영한다. 결과는 `.playwright-mcp/healing-part2/`에 둔다.
- 범위가 크게 늘면 추가 실행 전에 사용자에게 알린다.
- 반짝임처럼 시간에 따라 변하는 효과와 실기기 촉감·성능은 정지 캡처로 확정할 수 없다. 이 부분은 사용자 직접 확인 항목으로 남긴다.

### 리뷰

- 작업 단위 코드 리뷰를 유지한다.
- **최종 독립 리뷰는 사용자 지정에 따라 Opus 5.5 / High**로 진행한다(AGENTS.md 기본값 대신). 리뷰어는 코드와 시각 검수 캡처를 함께 검토한다.

## 구현자에게 맡기는 것

- 모드·클래스·파일 이름. 예시: `HealingPart2Mode`, `LevelMode`에 `'healing2'` 추가.
- 기존 힐링 모듈에서 공용 부분을 떼어 내는 방식과 범위. 단, 파트 1 동작은 바뀌지 않아야 한다.
- 다음 수치의 조정: 선 최소 길이, 칼이 따라붙는 속도, 깊이 비율, 칼 기울기, 미끄러지는 거리, 최소 조각 크기, 반짝임 지속 시간·밀도.
- 내부 장식(구슬·발바닥·보석·별자리)의 구체적인 배치와 모양. 단, 원본 입체 좌표 기반이어야 한다.
- 각 젤리의 높이 함수와 윤곽의 세부 형태, 카메라 구도. 젤리 높이와 앞쪽 단면이 함께 보여야 한다.