# 같은 젤리 무한 자르기 구현 계획

> 에이전트 실행: superpowers:executing-plans로 이 세션에서 순서대로 구현한다. 최종 독립 리뷰는 gpt-6.1-sol / medium이다.

**목표:** 208판에서 같은 젤리를 반복 절단하고 도마 전체를 수동 확대·이동한다.
**아키텍처:** three 없는 정규화 볼록 입체 절단·제스처 수학과 Three.js 장면을 분리한다. EndlessMode가 공통 ModeHost의 진행·시간·입력·HUD를 연결한다.
**기술:** 기존 TypeScript 7 / Three.js / Vite / Vitest / Playwright. 새 의존성 없음.
**스펙:** docs/superpowers/specs/2026-11-01-endless-jelly-design.md (2026-11-01 사용자 승인)

## 공통 제약

- 기존 207판 ID·순서와 legacy-stage-order.json 보존, 신규 endless-jelly를 208판에 추가.
- 절단·조각 수·시간에 따른 종료 없음, 확대 1~64배, 초기 피치색 사각 젤리.
- 손 뗌에서 실제 시작–끝 직선으로 절단, 두 번째 포인터 합류 시 전원 해제까지 절단 억제.
- 입력 콜백 메시 생성 0, 한 프레임 자식 메시 최대 1, 전체 후보 원자적 인계.
- 사용자 응답·코드 주석·문서 한국어, UI 영어·한국어 CSV 원본 사용.
- 기초 구현 + 사용자 시각 조정. 반복 캡처/취향 수정 없음. 운영 푸시 없음.

## 리뷰 중점

1. 두 손가락에서 하나만 남은 이동·해제가 칼질로 이어지지 않는가(Task 2/4).
2. 한 선분이 여러 기울어진 조각을 관통하며 일부만 닿는 이웃은 보존하는가(Task 1/3).
3. 준비 중 숨김·Resize·레벨 변경에서 원본과 준비 자식의 소유권이 유일한가(Task 3/4).
4. 확대·이동 후 실제 선과 화면 미리보기·포인터 위치가 일치하는가(Task 2/4).
5. 첫 단면 전 취소·재방문에서 별이 잘못 지급되거나 중복되지 않는가(Task 4/5).

### Task 1: 반복 절단 가능한 정규화 볼록 입체

**파일:** src/core/endless/EndlessSolid.ts, tests/EndlessSolid.test.ts
**인터페이스:** Point3/Vertex/Face/Solid, splitSolid(solid, plane) → 정규화된 자식 두 개 또는 null. 자식 center/scale은 부모 지역 좌표에서의 변환이며 pattern 좌표는 원본 젤리 좌표다. solidVolume(solid), createEndlessSolid().

- [x] 부피 보존·폐합·미관통·얇은 접촉·무늬 연속·1,000회 절단/1,024조각·동일 자식 반복 80회 테스트를 작성하고 실패 확인.
- [x] 면 다각형 반공간 클리핑과 단일 캡 다각형, 지역 좌표 정규화 구현. 기존 HealingSolid의 반복 삼각형 분할에 따른 증가를 피하면서 동일한 실제 평면 분할 원칙 유지.
- [x] 테스트 통과와 초기/반복 자식 형상의 유한성 확인.

### Task 2: 절단·다중 포인터·확대 수학

**파일:** src/core/endless/EndlessGesture.ts, src/core/endless/EndlessZoom.ts, tests/EndlessGesture.test.ts, tests/EndlessZoom.test.ts
**인터페이스:** EndlessGesture.start/move/end/cancel → preview/cut/view 명령. zoomAround(view, size, anchor, factor), panView(view, size, dx, dy), clampView(view). 외부 부작용과 three 없음.

- [x] 단일 드래그 손 뗌, 탭 무효, 두 손가락 합류/한 손 잔류 억제, Shift 이동, cancel, 중점 보존, 64배 제한과 Resize 비율 보존 실패 테스트.
- [x] 제스처 상태와 확대 수학 구현 후 테스트 통과.

### Task 3: 입체 장면·프레임 준비·연출·자원

**파일:** src/core/endless/EndlessScene.ts, EndlessMesh.ts, EndlessIndex.ts, tests/EndlessScene.test.ts
**인터페이스:** EndlessScene.preview(a,b), requestCut(a,b), update(dt), cancel(), dispose(), snapshot(camera,rect). 입력은 도마 Vec2 선분, 완료 이벤트는 update 결과. Task 1의 지역 변환과 Task 2의 명령을 소비.

- [x] 실제 관통/부분 접촉, 동시 절단, 요청 중 메시 0/프레임당 1, 원자적 인계, 실패/취소 원본 보존·해제, 1,024조각 렌더 데이터와 공간 인덱스 테스트를 작성하고 실패 확인.
- [x] 둥근 사각 입체·피치 재질·닫힌 단면·도마·기존 createKnife를 연결. 정지 조각 공유 재질·공간 인덱스·전체 보기 배치 렌더링·선택 영역만 후보 검사.
- [x] 단면 벌림·짧은 착지/기울기, reducedMotion, 작업 토큰/자원 해제 구현 후 테스트 통과.

### Task 4: 모드·208판·HUD·번역·디버그 통합

**파일:** src/core/modes/EndlessMode.ts, Game.ts, GameMode.ts, cutting/PointerInput.ts, ui/EndlessViews.ts, HUD.ts, stages/{LevelDefinition,StageDefinitions,StageVariant,LevelLabels,LevelBadge}.ts, stages/stage-order.json, jelly/JellyShapes.ts, i18n/{texts.csv,labels.ts}, core/{JellyDebug,GameDebug}.ts 및 관련 테스트.
**인터페이스:** mode='endless'; stageId/jellyType='endless-jelly'; pointer wheel 선택 훅; hudInfo의 endless 표시 데이터; __jellyDebug.endless(). 기존 공통 discoverAndOfferExit를 첫 단면에서 한 번 호출.

- [x] 신규 편성·도감·라벨·공통 입력 휠/취소·모드 진행/별/메뉴/Resize·기존 판 순서 보존 테스트를 추가해 실패 확인.
- [x] 전용 모드 등록, camera 훅에서 기본 fitCamera + 확대용 viewOffset, 두 손가락/Shift 이동과 전체 보기 UI, 공통 진행/FeelService 연결.
- [x] CSV 영어·한국어 등록/생성, 신규 디버그 계약 추가. 기존 판 수 고정 검사는 기존 편성 보존을 검증하도록 갱신.
- [x] 관련 단위·타입·번역·빌드 통과.

### Task 5: 기능 E2E·부하 기록·문서·최종 리뷰

**파일:** e2e/endless.spec.ts, e2e/debug-api.spec.ts, PROGRESS.md, DocsSite의 현재 콘텐츠 생성 정보, 본 계획 실행 기록.

- [x] openLevel로 모바일/데스크톱 실제 드래그 절단·재절단·동시 절단·확대 이동·전체 보기·취소·Retry·별·히든·기존 힐링 회귀 확인.
- [x] 전체 단위·strict TypeScript/Vite·번역·문서 검사. 1,000회 및 1,024조각 부하/자원 회수 결과 기록.
- [x] DocsSite 수정 시 docs-site 스킬 적용. 기획서와 PROGRESS의 활성 208판 및 검증 한계 갱신.
- [x] 최종 독립 전체 변경 리뷰(gpt-6.1-sol / medium), 지적 수정과 관련 재검증. 결과와 사용자 시각 조정 위치 인계.

## 실행 기록

- 2026-11-01: 사용자 설계 승인. codex/endless-jelly 브랜치, 기준 038ced9. 미추적 사용자 이미지/output 보존. 이 세션 직접 구현 + 최종 독립 리뷰.
- 결정: 별도 worktree 없이 현재 폴더의 기능 브랜치를 사용한다. 현재 최신화한 폴더에서 이어서 구현해 검수 환경과 사용자 자산을 유지한다.
- 결정: 입체 클리핑은 볼록 면 다각형 기반으로 구현한다. 기존 삼각형 단위 HealingSolid를 1,000회 반복 재사용하면 중복 삼각형이 커질 수 있어, 기존 판을 변경하지 않는 전용 순수 연산으로 분리한다.

- 검증: 전체231파일3379테스트 통과. 이후 소수 픽셀 Resize 앵커 보정은 관련10테스트/타입 재검증. 후속 원자 준비 실패 검사까지 별도 관련 전체를 다시 실행한다.
- 브라우저: 최초 신규+debug 양 Chromium29통과/3사전제외. 첫 기존 힐링/홈/진행 회귀22통과/2제외. 리뷰 후 확대 회전에서 DOM 크기/정수 화면 차이 및 휠 입력 대기 누락이 드러났고, 제품은 NDC 기반 중심 보정·테스트는 실제 확대 완료/현재 좌표 대기를 적용했다. 해당 회전 단독2통과. 같은 회귀 실행의 용과 boardTap 집계1/2 실패는 다른 부하 검사 없이 단독 재실행하여 정상2회 기록을 확인했다. 최종 신규 모드 전체+용과 양 Chromium13통과/1사전제외. 마지막 판/홈/기존 오로라 회귀는 앞 실행의 통과 결과를 유지한다. 전체 모바일 기능·성능 E2E와 네이티브 실기기는 실행하지 않았다.
- 독립 리뷰: gpt-6.1-sol / medium, Critical0/Important2/Minor1. 회전 전 실제 도마 중심 재투영, 첫 인계 프레임에서 발견/3별 기록, 추가 접점 합류 시 전원 해제까지 입력 억제로 모두 수정. 신규4실패 RED→관련10통과 GREEN. DOM 소수 크기 차이도 별도 RED→GREEN 확인했다.
- 부하: CPU 장면1023회 절단/2311조각, 부피3.78144 보존·입력 메시0·프레임당 메시1·해제 통과. 최종 WebGL fixture 양 해상도2311조각/88932정점/4draw call, render CPU평균0.61ms/p95 0.8ms. 프레임간격p95 16.7~16.8ms, 최대desktop66.6ms/mobile viewport16.8ms. geometry2→0·텍스처렌더러/환경 소유5→5. fixture 동기 준비5.2~6.6초와 최초 고밀도 렌더4.4~5.2ms를 구분했다. 최초 측정의 최대5~6초는 동기 fixture 준비 때문에 밀린 rAF를 샘플링한 오류였으며 두 예열 프레임 뒤 다시 측정했다. JSON/스크립트는 .playwright-mcp/endless-render-stress.*. 실제 휴대폰 측정이 아니며 전체 게임 루프/다수 조각 드래그의 60fps 보장은 아니다.
- 문서: DocsSite5테스트통과/OS별2제외, generator/Astro오류0·정적11페이지 링크/본문/Markdown/색인/사이트맵 통과. 샌드박스 Pagefind 접근 거부와 첫 본문이 제목일 때의 검사 오류를 각각 권한 밖 동일 검사와 본문 문장 추가로 해결했다. 역사적200/204판 기록은 보존하고 현재208판 안내를 앞에 추가했다.
- 인계: 기본 구현과 기능 검증 완료. 시각/조작감·Android/iOS 실기기 검수 미완료. codex/endless-jelly의 미커밋 변경으로 보존하며 병합/푸시/배포하지 않는다.

- 최종 추가 검증: 원자 준비 실패 시 앞 후보 자식 해제 검사까지 포함해 신규 모드/공통포인터/기존힐링 단위9파일50개·strict TypeScript 통과. 마지막 source 빌드 통과. DocsSite5테스트/OS별2제외·정적11페이지 검사 통과. 로컬 미리보기 http://127.0.0.1:5188/?level=208&quality=low 를 열어 사용자 시각 조정에 인계한다.

## 후속: 말랑함·탱글함 사용자 조정

- [x] 기존 딱딱한 이동만 있는 상태를 확인하고 눌림/감쇠 복원/부피 보존/바닥 고정/외피와 단면 법선/움직임 줄이기 테스트를 먼저 추가해 실패 확인.
- [x] EndlessSoft의 해석적 감쇠 진동과 시각 전용 행렬, EndlessScene의 유한 활성 조각 갱신, 외피 법선과 반투명 광택 연결. 관련16테스트와 타입 검사 통과.
- [x] 신규 모드/반복 절단 회귀·빌드·양 해상도 실제 입력·움직임 줄이기 검사.
- [x] gpt-6.1-sol / medium 독립 코드 리뷰와 지적 수정 후 현재 미리보기에 인계. 외관 강도는 사용자 확인 범위.

- 후속 검증: 처음 추가한 눌림/복원·부피·바닥·법선·reducedMotion 검사의 실패를 확인한 뒤 구현했다. 관련10파일55테스트·타입·빌드, 신규 모드 전체 양 Chromium15통과/1사전제외. 독립 리뷰 gpt-6.1-sol/medium은 Critical0/Important0/Minor1(탄성 영교차에서 즉시 새 칼질을 취소하면 shear 영구 잔류)을 보고했고, 해당 경계를 실패 테스트로 재현 후 다음 프레임의 REST/버퍼 동시 복원으로 수정했다. 최종 관련10파일56테스트·타입/빌드 통과. 새로운 메시를 만들지 않고 정지 후 갱신을 멈추며 기존1023회/2311조각 부피·원자 준비·해제 검사를 유지한다. 최종 취소/탄성/움직임 줄이기는 별도 E2E 재검증한다. 반복 시각 비교·취향 수정·실기기 검수는 하지 않았다.

- 후속 최종 확인: 취소 영교차 수정 후 숨김/탄성/움직임 줄이기 양 Chromium6개 통과. 전체 신규 모드 E2E15통과/1사전제외 결과와 관련56단위/타입/빌드를 함께 유지한다. 대량 조각 GPU 수치는 이전 버전의 기록이며 이번 탄성 활성 장면에 대한 재측정은 하지 않았다. 시각 강도는 사용자가 현재208판에서 확인한다.

## 후속: 투명 무지개색과 실제 모서리 라운딩

- [x] 현재 단일 평면 베벨을 확인하고 반경0.22 둥근 상자 표면 거리/여섯 면 크기/폐합 테스트를 추가해 실패 확인.
- [x] 볼록 지지 평면으로 모서리·꼭짓점 곡률 추가, 같은 반경으로 외피 법선 갱신, 공유 원본 좌표 무지개 GLSL·높은 투과율/광택 구현. 관련3파일17테스트 통과.
- [x] 도감/이름/메타데이터와 문서를 현재 무지개색으로 갱신하고 반복 절단/빌드/양 해상도 E2E·문서 검증.
- [x] 독립 리뷰(gpt-6.1-sol / medium)와 지적 수정, 사용자 시각 조정에 인계.

- 무지개 후속 결과: 관련10파일57단위(닫힌 실제 라운딩/반경 표면 거리/기존80회 자식 및1023회 장면2168조각 부피 보존 포함), strict TS/Vite 빌드, 양 Chromium 신규 모드15통과/1사전제외, DocsSite5테스트/OS별2제외·정적HTML11페이지 검사 통과. 독립 리뷰 gpt-6.1-sol/medium Critical0/Important0/Minor1(공통 재질의 baked 형상과 analytic 유니폼 불일치). 실제208/도감 SVG에는 영향 없는 공통 경로였으나 실패 테스트로 확인 후 BAKED_SHAPE_GLSL로 수정했고 재질269테스트를 통과했다. 새 형상은2168조각/93552정점이며 CPU 갱신 최대39ms, GPU 대량 부하는 이번 변경에서 재측정하지 않았다. 기존 WebGL 기록을 새 버전의 측정으로 해석하지 않는다.

- 공통 SDF 수정까지 반영한 최종 빌드의 모바일/데스크톱 첫 렌더·반복 절단2E2E도 통과했다. 현재208판 미리보기에 인계하며 시각 강도/실기기는 사용자 확인 범위, 미커밋/미배포 상태를 유지한다.

## 후속: 잘린 조각의 자연스러운 낙하와 착지

- [x] 기존 바닥 높이 보간/고정 작은 회전이 원인임을 확인. 중력·얇은 조각 눕기·30/60/120Hz·큰 시간/움직임 줄이기·공중 재절단 취소 복귀·실제 표면 높이 테스트를 먼저 추가해 실패 확인.
- [x] EndlessFallShape의 질량중심/지지점/관성을 자식 준비 때 계산하고 EndlessFall 고정 적분·도마 반력/마찰·정지를 연결. Scene 원자 인계와 이동 중 취소의 원본 낙하/속도 복귀, 착지 탄성 연결.
- [x] 실제 시각 메시 높이 선택과 장면 좌표 변환, 물리/화면 디버그 항목 추가. 관련3파일19단위·타입 통과.
- [x] 신규 모드 전체/반복 절단/빌드·양 해상도 실제 낙하/눕기/재절단 검증.
- [x] 독립 리뷰(gpt-6.1-sol / medium)와 지적 수정 후 사용자 체감 검수 인계.

- 낙하 후속 결과: 관련11파일63단위·strict TS/Vite 빌드 통과. 장면1023절단/10574조각/390240정점에서 부피3.7298411267 유지·프레임당 준비1/입력 메시0·해제 통과. CPU 최대 갱신100.7ms이며 이전과 조각 수가 달라 직접 성능 비교하지 않는다. 실제 모바일 GPU 부하는 재측정하지 않았다.
- 최초 E2E는 기존 높이0.5 기준 debug 좌표로 첫 절단의 길이를 정해 wait timeout이 발생해 중단했다. 기존 계약을 보존한 surfaceMin/Max를 추가하고 실제 시각 경계를 도우미에 적용한 뒤 단독2개 및 최종 양 Chromium17통과/1사전제외를 확인했다(낙하/눕기/보이는 위치 재절단/탄성/핀치/취소/회전/저장).
- sol/medium 독립 리뷰 Important1건(비스듬한 절단 조각의 접촉 잔진동이120초에도 미정지)을 실패 테스트로 재현하고3.6초 감쇠 뒤 다음 접촉에서 현재 자세로 수면하도록 수정했다. 수정 후 물리/장면/모드3파일20테스트와 타입·E2E 통과. 재리뷰는 추가 결함0건, 독립 물리5테스트 통과. 독립 Scene/Mode 재실행은 제품 assertion 전 SSR 임시캐시 ENOENT여서 부모의 통과 결과를 사용했다. 사용자 외관/조작감과 실기기 검수는 미완료, 미커밋/미배포다.

- 최종 공개 디버그 낙하/실제 표면 좌표 계약도 양 Chromium2개 통과(모드17개와 별도).

## 후속: 어두운 반전색 내부 면과 반짝가루

- [x] 기존 endlessCut 면 표시와 원본3D좌표를 사용해 단면 전용 어두운 보색/낮은 투과/큰 별 홀로그램·각도 반사를 구현한다. 추가 텍스처·메시·시간 갱신은 사용하지 않는다.
- [x] 기존 메시/부피/재질 관련 검사와 strict TS/Vite 빌드, 양 Chromium 첫 렌더·재절단의 실제 셰이더 컴파일을 확인한다.
- [x] gpt-6.1-sol / medium 독립 코드 리뷰와 사용자 시각 조정 인계.

- 사용자 조정: 작은 규칙적 가루 대신 큰 별 홀로그램을 요청했다. 이웃9셀의 전체 위치 난수/확률 배치·크기/각도 난수·다섯 꼭짓점 직선 윤곽·시선별 홀로그램 색을 적용하고 동일 범위로 최종 검증한다. 첫 미세가루 버전은278단위/빌드/양Chromium4E2E·sol/medium 리뷰 결함0건 통과한 중간 상태다.

- 별 홀로그램 최종: 관련4파일289단위·strict TS/Vite·양Chromium 절단/재절단/낙하4E2E 및 셰이더 오류0 통과. sol/medium 재리뷰의 대각선 단면에서 픽셀 미분 축 선택/레이어 경계가 무늬를 바꿀 수 있는 Important1건은 회귀RED→GREEN으로 수정했다. 기존endlessCut를0외피/1·2·3고정축으로 확장해 면별CPU에서 한 번 선택하고 깊이는 연속 이동으로 섞는다. 재리뷰 추가결함0건. 별 크기·배치/가시성/홀로그램 체감은 사용자 검수 미완료이며 최신 대량GPU/실기기 측정은 하지 않았다. 조정 위치는 endless.glsl.ts의6.5밀도/0.19~0.36반경/0.38생성 문턱과EndlessMesh의foil/glint강도다. 미커밋/미배포.

## 후속: 키위 젤리 같은 반투명감

- [x] 키위의 반사/속빛 경로를 확인하고 외피/단면 투과·흡수색/투과광·부드러운 반사와 홀로그램 투과 차단을 조정한다.
- [x] 빌드/기존 관련 단위·양Chromium 실제 셰이더/재절단을 확인한다.
- [x] gpt-6.1-sol / medium 독립리뷰 후 사용자 시각 조정에 인계한다.

- 반투명 최종: 키위의clearcoat0.7/specular0.4/env0.55/ior1.35와 몸통색+약한속빛 경로를 참고했다. 현재 외피투과0.88/단면0.5984/별0.05984, roughness0.10, clearcoat0.7/specular0.45/env0.6, thickness0.48/ior1.35. 밝은 투과색과 색 흡수·약한가장자리속빛을 적용했다. 관련4파일289단위·strict TS/Vite·양Chromium4E2E(셰이더오류0) 통과, sol/medium 독립리뷰 수정 필요0건. 외관 유사성/별 가시성은 사용자 미검수, 최신 대량GPU/실기기 미측정, 미커밋/미배포.

## 로컬 커밋·main 통합·푸시

- 구현을3eb22e3으로 로컬커밋했다. 원격main ca6d8fe의 힐링3종/리소스를 보존하고 endless-jelly를211판으로 추가한다. 공통 번역/젤리타입/도감/퍼즈/표시순서와 카탈로그 기대값을 양쪽 합집합으로 해결한다. 기존 사용자 이미지6개와output/은추적하지않는다. 통합 전 전체 단위는 기준 변경으로 중단했고 문서검사5통과/2OS제외·정적11페이지는 통과했다. 통합결과의 전체단위/문서/필수모바일과 최종독립리뷰를 수행하고main을fast-forward해일반푸시한다.

- 통합 검증 이력: 전체234파일3424검사에서3423통과/EndlessStress1개120초 제한 초과. 해당 검사는1023절단10574조각·부피·자원 assertions를 모두 끝낸 뒤339.6초 소요로 시간 제한에 실패했다. 부하 원인 확인을 위해 단독 재실행한다. 단위 테스트의 벽시계 제한은 품질/성능 임계값과 구분한다. DocsSite는 variant 수25추정 오류를 실제22로 맞추고 신규힐링3종 이름누락을 검사실패로 확인해 연결했다. 최종문서5통과/2OS제외·정적11페이지통과. 최종독립리뷰 Important1건(준비 실패 뒤 Slicing/HUD잔류)은 실패테스트→완료알림으로수정했고 모드/장면16검사 통과, 재리뷰 결함0건.

- 스트레스 시간 예산: 전체 퍼즈와 병렬 시 관찰한339.6초를 허용하도록 해당 기능 스트레스 한 파일의 테스트 제한만120초→600초로 맞췄다. 1023절단·최소1024조각·부피오차·GPU버퍼상한·자원해제·입력메시0 assertions와 메시/퍼즈 품질 임계값은 그대로다. 프레임 성능 예산을 완화하지 않았다.

- 단독 재실행도 기능assertions를완료했으나229.5초로기존120초제한에실패했다. 사용하지않는 화면 경계의 반복 행렬연산을 Scene.describe(visualBounds=false)에서생략하고 공개debug만true로계산해계약을유지했다. 모드/장면16검사·strictTS통과, 최종stress를600초예산으로실행중이며이후필수모바일전체검증을한다.

- 전체 모바일 첫 실행은 같은 작업 폴더에 별도 공장 허용오차 작업이 들어와 진행 중 테스트/소스 기준이 섞여 중단했다. 해당 미커밋 작업은 보존하고 기존main 전용 작업폴더/4175전용서버에서 커밋 기준 전체 모바일을 다시 실행한다. 힐링 소리 검사2실패는 최근20개 soundLog를 누적기록으로 다룬 검사오류였다. 각절단중sliceLoop 관찰과마지막sliceLoop→boardTap순서를확인하도록검사를고치며제품소리/저장계약은유지한다.

- main 전용 작업폴더의 절단음 회귀7개(힐링5종/동시절단/부분접촉)가모두통과했다. sol/medium 독립재리뷰 결함0건. 제품코드는13c90a0그대로이며최근로그검사만수정했다. 최종stress1통과183.45초/전체기존3423통과/복구16검사/strictTS·문서검사를유지하고동일커밋의모바일828항목을4175서버에서전체실행한다.