# 플레이 중 셰이더 재컴파일 제거 구현 계획 (성능 하위 프로젝트 A)

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 플레이 중 다섯 순간(첫 절단·첫 찍기·곰 누름·메스 긋기·등급 하향)의 그리기 안 셰이더 컴파일 멈춤을 계측하고 0회로 만든다. 실기기 앱에서 전후를 잰다.

**Architecture:** 렌더러 GL 컨텍스트를 감싼 `ShaderStats`가 그리기 안·밖 link와 미완료 첫 사용, 프레임 간격을 기록하고 디버그 API로 노출한다. `ShaderKeeper`는 판에 필요한 셰이더 변형마다 대표 재질 하나를 미리 컴파일해 쥐고 있어, 실제 재질을 버려도 프로그램이 살아 있게 한다. 등급 하향은 새 등급 변형을 보관소에 먼저 등록한 뒤 확정한다.

**Tech Stack:** TypeScript strict, three 0.186.1(WebGL2), Vitest, Playwright 1.64(`connectOverCDP`로 Android WebView 연결), Capacitor 8 Android 디버그 APK, adb.

**Spec:** `docs/superpowers/specs/2026-10-28-shader-recompile-removal-design.md`

## Global Constraints

- 외관 변화 없음. 모든 수정은 컴파일 시점만 옮긴다. 외관이 바뀌는 수정이 필요해지면 멈추고 사용자에게 시각 검수 방식을 묻는다.
- 완료 기준: 측정 구간의 그리기 안 막힘(`inRenderLinks + inRenderPending`) 0회.
- 기존 `forceTier`는 동기 그대로 둔다(기존 E2E 6개 파일 계약).
- 성능 예산(`perf.spec.ts`의 8ms·16ms·34ms, 75판 모바일 10·20ms)은 완화하지 않는다. 회귀 판정은 `docs/superpowers/refactor-baseline.md` 6절(같은 시각 A/B, 중앙값 max(1ms, 20%))이다.
- 실기기에는 절대 ms 예산이 없다. 기준·변경 APK를 번갈아 3회씩 재서 중앙값과 개선 폭만 기록한다.
- 기기 테스트는 기본 `npm run e2e`·`e2e:mobile`·CI에 섞지 않는다. Android 에뮬레이터는 쓰지 않는다.
- 셸 스크립트는 macOS bash 3.2 호환(연관 배열 없음). Android 빌드 JDK는 `/Applications/Android Studio.app/Contents/jbr/Contents/Home`이다.
- 보관소는 현재 판과 준비 중인 다음 판에 필요한 키만 유지한다. 칼자국 재질은 게임 내내 해제하지 않는다.
- `SwipeMode.swipeWarm`은 옮기지 않는다. `FpsGovernor` 임계값(45fps·3초)은 바꾸지 않는다.
- `window.__jellyDebug` 키를 추가하면 `src/core/JellyDebug.ts` 타입과 `e2e/debug-api.spec.ts`의 `EXPECTED_KEYS`를 함께 갱신한다.
- 작업 브랜치에서 구현하고, 마지막에 로컬 main에 머지만 한다. **푸시하지 않는다**(main 푸시 = 운영 배포).
- 코드 주석·커밋 메시지는 한국어.

## Review Focus

1. 컨텍스트 손실이 진행 중인 `keep` 도중에 오면, 손실 뒤 끝난 `keep`이 옛 재질을 다시 등록하지 않아야 한다. Task 4에서 `clear 뒤 끝난 keep 은 등록되지 않는다` 단위 테스트로 고정한다.
2. 같은 키를 다른 판이 다시 요청하면(같은 젤리 종류가 연속), 판을 바꿀 때의 해제가 그 키를 지우지 않아야 한다. Task 4의 `같은 키 재요청은 범위를 새 판으로 옮긴다` 테스트로 고정한다.
3. 긴 세션에서 보관소가 프로그램 수를 계속 늘리지 않아야 한다. 또 비동기 등록 때문에 `memory.spec.ts`의 바퀴 비교가 흔들리지 않아야 한다. Task 5에서 `memory.spec.ts`의 `lap`이 `shadersReady()`를 기다리게 하고 통과를 확인한다.
4. 등급 요청을 기다리는 중에 판이 바뀌면, 확정 시점에 새 판의 변형도 등록돼 있어야 한다. Task 8의 E2E `등급 요청 대기 중 판을 바꿔도 확정 프레임 막힘 0`으로 고정한다.
5. `KHR_parallel_shader_compile`이 없는 환경(WebKit 가능성)에서는 미완료 첫 사용을 셀 수 없다. 단언이 약해진다는 사실이 숨겨지면 안 된다. Task 1의 `확장이 없으면 pending 을 세지 않고 hasParallelCompile 이 거짓` 단위 테스트와, Task 2 E2E의 WebKit 주석으로 고정한다.

---

### Task 1: `ShaderStats` 카운터·프레임 기록

**Files:**
- Create: `src/core/ShaderStats.ts`
- Test: `tests/ShaderStats.test.ts`

**Interfaces:**
- Produces:
  ```ts
  export interface ShaderCounts { inRender: number; inRenderPending: number; outside: number; shaders: number }
  export interface PerfWindow { inRenderLinks: number; inRenderPending: number; outsideLinks: number; maxGapMs: number; frames: number; tierChanged: boolean }
  export class ShaderStats {
    constructor(capacity?: number)            // 기본 600프레임
    attach(gl: WebGL2RenderingContext): void  // 인스턴스의 linkProgram·compileShader·getProgramParameter를 감싼다. 두 번 불러도 한 번만 감싼다
    readonly hasParallelCompile: boolean      // attach 때 KHR_parallel_shader_compile 확장 유무
    beginRender(): void
    endRender(): void
    frame(gapMs: number, tier: string): void  // 프레임 하나 기록(링 버퍼)
    counts(): ShaderCounts
    mark(): number                            // 표식 id
    since(id: number): PerfWindow             // 표식 뒤 기록된 프레임들의 합·최대. 모르는 id면 모두 0
  }
  ```
- 감싸는 규칙:
  - `linkProgram`: 그리기 중이면 `inRender`, 아니면 `outside`를 하나 올린다.
  - `compileShader`: `shaders`를 올린다.
  - `getProgramParameter(p, LINK_STATUS)`: 그리기 중이고 확장이 있을 때, 원래 함수로 `COMPLETION_STATUS_KHR`를 먼저 조회한다. 거짓이면 `inRenderPending`을 올린다.
  - 프레임 기록에는 그 프레임 동안 늘어난 카운트를 담는다.
  - `since`는 링 버퍼에 남은 프레임만 본다(용량을 넘기면 오래된 프레임은 빠진다).
  - `tierChanged`는 표식 뒤 프레임의 tier가 표식 시점과 다른 것이 하나라도 있으면 참이다.

- [ ] **Step 1: 실패하는 단위 테스트 작성** (`tests/ShaderStats.test.ts`, 가짜 GL 객체: `LINK_STATUS`·확장 상수와 호출 기록용 함수, 확장 유무를 선택할 수 있게)
  - `그리기 안·밖 link 를 나눠 센다`: `outside` link 1회 → `beginRender`, link 2회 → `endRender` → `counts()`가 `{ inRender: 2, outside: 1, inRenderPending: 0, shaders: 0 }`
  - `확장이 있으면 그리기 안 미완료 첫 사용을 센다`: 완료 상태가 거짓인 프로그램에 그리기 안에서 `getProgramParameter(p, LINK_STATUS)` → `inRenderPending === 1`. 완료 상태가 참이면 0. 그리기 밖에서는 0
  - `확장이 없으면 pending 을 세지 않고 hasParallelCompile 이 거짓`
  - `원래 함수의 반환값을 그대로 돌려준다`(감싼 `getProgramParameter`가 원래 값 반환)
  - `attach 를 두 번 해도 한 번만 센다`
  - `since 는 표식 뒤 프레임의 link 합과 최대 간격을 낸다`: mark → `frame(16,'medium')`, 그리기 안 link 1회 뒤 `frame(80,'medium')` → `{ inRenderLinks: 1, maxGapMs: 80, frames: 2, tierChanged: false }`
  - `등급이 바뀐 프레임이 있으면 tierChanged`
  - `용량을 넘기면 오래된 프레임은 since 에서 빠진다`(capacity 3, 프레임 5개)

- [ ] **Step 2: 실패 확인** — Run: `npx vitest run tests/ShaderStats.test.ts` / Expected: FAIL(모듈 없음)

- [ ] **Step 3: `src/core/ShaderStats.ts` 구현** — three를 import하지 않는다(순수 GL 래퍼). 링 버퍼는 고정 길이 배열과 증가하는 프레임 번호로 구현한다. 표식은 `{ seq, tier }`를 맵에 저장한다.

- [ ] **Step 4: 통과 확인** — Run: `npx vitest run tests/ShaderStats.test.ts` / Expected: PASS

- [ ] **Step 5: 커밋** — `git add src/core/ShaderStats.ts tests/ShaderStats.test.ts && git commit -m "셰이더 컴파일·프레임 간격 계측기 추가"`

### Task 2: 게임 연결·디버그 API·기준선 E2E

**Files:**
- Modify: `src/core/RenderManager.ts:53` (`render`에 그리기 표시 훅)
- Modify: `src/core/Game.ts` (생성자에서 `ShaderStats` 생성·`attach`, `frame` 루프 `governor.sample` 자리(:1057)에 기록과 `holdTier` 분기, 디버그 문맥 연결)
- Modify: `src/core/GameDebug.ts` (`AppDebug`·`AppDebugDeps` 또는 `GameDebugContext`에 추가), `src/core/JellyDebug.ts`
- Modify: `tests/GameDebug.test.ts`, `e2e/debug-api.spec.ts` (`EXPECTED_KEYS`에 `holdTier`·`perfMark`·`perfSince`·`shaderLinks`)
- Create: `e2e/shader-compile.spec.ts`, `e2e/helpers/shader.ts` (`e2e/helpers.ts`에서 다시 내보냄)
- Modify: `e2e/perf.spec.ts` (기록 전용 테스트 추가)

**Interfaces:**
- Consumes: Task 1 `ShaderStats`
- Produces:
  - `RenderManager.renderHooks: { begin(): void; end(): void } | null`. `render`가 `renderer.render` 앞뒤로 부른다.
  - 디버그 API:
    - `shaderLinks(): ShaderCounts`
    - `perfMark(): number`
    - `perfSince(id: number): PerfWindow`
    - `holdTier(on: boolean): void`: 켜면 `governor.sample`을 부르지 않는다. 기본은 꺼짐이다.
  - E2E 도우미(`e2e/helpers/shader.ts`):
    - `markPerf(page): Promise<number>`
    - `perfSince(page, id): Promise<PerfWindow>`
    - `blocking(w: PerfWindow): number` = `w.inRenderLinks + w.inRenderPending`
    - `logPerf(info, label, w)`: `[perf] <project> <label> blocking=… maxGapMs=… outside=…` 한 줄을 남긴다.

- [ ] **Step 1: `tests/GameDebug.test.ts`에 실패 테스트 추가** — `perfSince 는 문맥의 ShaderStats.since 결과를 그대로 낸다`, `holdTier(true) 는 문맥의 holdTier 를 부른다`(가짜 문맥)
- [ ] **Step 2: 실패 확인** — Run: `npx vitest run tests/GameDebug.test.ts` / Expected: FAIL
- [ ] **Step 3: 연결 구현** — `Game`이 `renderMgr.renderer.getContext()`에 `attach`하고 `renderHooks`를 건다. 프레임마다 `stats.frame(realDt * 1000, this.tier)`를 부른다. `realDt`가 0이거나 0.5초를 넘는 비정상 프레임도 그대로 기록한다(멈춤 측정이 목적).
- [ ] **Step 4: 통과 확인** — Run: `npx vitest run tests/GameDebug.test.ts` / Expected: PASS
- [ ] **Step 5: `e2e/debug-api.spec.ts` 키 목록 갱신 후 통과 확인** — Run: `npx playwright test e2e/debug-api.spec.ts --project=desktop-chromium` / Expected: PASS
- [ ] **Step 6: `e2e/shader-compile.spec.ts` 작성.** 모든 테스트는 `holdTier(true)` 뒤 측정하고, 끝에 `logPerf`로 기록하며, `expect(blocking(w)).toBe(0)`을 단언한다. 아직 고치기 전이므로 각 테스트에 `test.fail()`을 붙인다. 이 표시는 해당 수정 Task가 지운다.
  - `첫 절단: 1판 첫 획부터 조각 교체 뒤 ready 까지 그리기 안 막힘 0`: `openLevel(page,1)` → mark → `cutJellyLine`(기존 첫 판 획) → `ready`/`result` 대기 → `nextFrames(10)` → since
  - `첫 찍기: 40판 첫 탭부터 조각 생성 뒤 10프레임까지 막힘 0`: `stampAt` 첫 칸
  - `곰 누름: 66판 첫 선택부터 누름 주기 끝까지 막힘 0`: `oddJelly().ready` 대기 → mark → `tapOdd` 첫 몸체 → 주기만큼 `advanceOdd` 또는 실제 시간 대기 → since
  - `메스 긋기: 14판 누름·이동·손 뗌 동안 막힘 0`: `page.mouse.down` → 경로 점 10개 이상 `move` → `up` → `ready` 대기
  - `회전판 메스 긋기: 70판 누른 채 1초 멈춰도 막힘 0`: 70판(회전판 곡선, 메스)에서 위와 같되 이동 뒤 1초 대기 후 `up`. 70판이 메스 회전판이 아니면 `CurveStages`에서 메스 회전판 판을 고른다.
  - 테스트 머리 주석: "WebKit 에서 `hasParallelCompile` 이 거짓이면 pending 을 세지 않아 약한 검사다". 각 테스트 시작 때 확장 유무를 `info.annotations`에 남긴다.
- [ ] **Step 7: 기준선 실행·기록** — Run: `npx playwright test e2e/shader-compile.spec.ts --project=desktop-chromium --project=mobile-chromium --project=desktop-webkit`
  - Expected: 다섯 테스트가 모두 "expected to fail"로 통과한다.
  - 하나라도 실제로 막힘 0이면(`test.fail` 위반) 그 순간은 재컴파일이 없는 것이다. 이 경우 계획의 해당 수정 범위를 줄이고 결과를 보고한다.
  - 테스트별 `[perf]` 줄을 이 계획 문서 끝 "측정 기록"에 붙인다.
- [ ] **Step 8: `e2e/perf.spec.ts`에 기록 전용 테스트 추가** — `셰이더 순간 프레임 간격(기록 전용)`: Step 6과 같은 다섯 순간, 그리고 `openLevel(page,1,'medium')`에서 `forceTier('low')` 직후 10프레임의 `maxGapMs`. `[perf]` 줄만 남기고 단언은 두지 않는다.
- [ ] **Step 9: 단위·빌드 확인** — Run: `npm test && npm run build` / Expected: 전부 통과
- [ ] **Step 10: 커밋** — `git commit -m "셰이더 막힘 계측 디버그 API와 기준선 E2E 추가"` (이 커밋이 A/B의 기준 커밋이다. 해시를 측정 기록에 적는다)

### Task 3: 실기기 측정 경로와 기준선

**Files:**
- Create: `playwright.device.config.ts`, `e2e/device/fixtures.ts`, `e2e/device/shader-device.spec.ts`, `scripts/device-ab.sh`
- Modify: `playwright.config.ts` (기능 세 프로젝트의 `testIgnore`를 `[PERF, DEVICE]`로, `const DEVICE = /e2e\/device\//`)

**Interfaces:**
- Consumes: Task 2 디버그 API와 `e2e/helpers/shader.ts`
- Produces:
  - `e2e/device/fixtures.ts`의 `test`: `page`를 앱 WebView 페이지로 바꾼 확장이다. 패키지 `game.steadyloop.jelly`, adb 경로는 `ANDROID_HOME`/`~/Library/Android/sdk/platform-tools/adb`.
  - 종료 때 `browser.close()` 대신 **연결만 끊는다**(탐색에서 연결을 남기면 node가 끝나지 않았다). forward도 지운다.
  - `[device] <scenario> run=<n> apk=<base|head> cache=<cold|warm|none> blocking=… maxGapMs=… tempC=…` 줄.
  - `scripts/device-ab.sh <base-sha> <head-sha> [runs=3]`: 결과를 `test-results/device-ab/<timestamp>/`에 모은다.

- [ ] **Step 1: 설정·픽스처 작성**
  - `playwright.device.config.ts`: `testDir: 'e2e/device'`, `workers: 1`, `fullyParallel: false`, `timeout: 90_000`, `baseURL: 'https://localhost'`, webServer 없음.
  - 픽스처는 pid → 소켓(`webview_devtools_remote_<pid>`) → 빈 포트 `adb forward` → `chromium.connectOverCDP` → `contexts()[0].pages()[0]` 순으로 붙는다. 앱이 안 떠 있으면 `monkey`로 실행한 뒤 소켓을 기다린다.
- [ ] **Step 2: 연결 확인 테스트** — `shader-device.spec.ts`의 첫 테스트 `앱 WebView 에 붙어 디버그 API 를 읽는다`: `?level=21&quality=medium` → `ready` → `tier() === 'medium'`.
  - Run: `npx playwright test -c playwright.device.config.ts -g "디버그 API"` / Expected: PASS
  - 실패하면 기기 연결(`adb devices`)과 USB 디버깅 승인을 사용자에게 요청한다.
- [ ] **Step 3: 포인터 입력 동작 확인**
  - 같은 파일의 `앱 WebView 에서 첫 절단이 된다`: 1판에서 `cutJellyLine` → `pieceCount() >= 2`.
  - 마우스 입력이 안 먹히면 `page.touchscreen` 또는 `dispatchPath`(포인터 이벤트 직접 발생) 중 동작하는 것을 도우미 선택 인자로 쓴다.
- [ ] **Step 4: 시나리오 작성** — Task 2 Step 6의 다섯 순간 + `등급 하향: 1판 forceTier('low') 직후 10프레임`(기준선용. Task 8에서 `requestTier`로 바꾼다).
  - 모두 `quality=medium`, `holdTier(true)`로 측정한다(등급 시나리오 제외).
  - 단언 없이 `[device]` 줄만 남긴다. `perfSince(...).tierChanged`가 참인 실행은 `discarded=1`로 표시한다.
  - 시작 때 `adb shell dumpsys battery`의 temperature(÷10)를 기록한다.
- [ ] **Step 5: GPU 캐시 확인**
  - `adb shell run-as game.steadyloop.jelly find . -maxdepth 4 -type d \( -iname '*GPUCache*' -o -iname '*ShaderCache*' -o -iname '*GrShaderCache*' \)`로 WebView 셰이더 캐시 디렉터리가 있는지 찾는다.
  - 찾은 경로를 측정 기록에 적는다. 찾지 못하면 `cache=none`으로 진행한다.
- [ ] **Step 6: `scripts/device-ab.sh` 작성** (bash 3.2)
  1. 두 sha를 각각 `git worktree add --detach` 한다. `node_modules`는 심볼릭 링크로 잇는다.
  2. 각 worktree에서 `npm run app:sync` → `android/gradlew assembleDebug`(JBR)로 APK를 만든다.
  3. 회차 i=1..runs마다 base→head 순서를 번갈아 바꾼다(홀수 회차 base 먼저).
  4. 실행마다: `adb install -r` → 앱 강제 종료(`am force-stop`) → (캐시 경로가 있으면) `run-as`로 캐시만 삭제 → 앱 실행 → 기기 프로젝트 실행(`cache=cold`). 캐시가 있으면 같은 APK로 한 번 더 실행한다(`cache=warm`).
  5. `[device]` 줄을 `results.txt`로 모으고, 시나리오별·APK별 중앙값 표를 `summary.md`로 만든다.
  6. `trap`으로 성공·실패와 관계없이 worktree를 지운다.
- [ ] **Step 7: 기준선 1회 실행** — Run: `scripts/device-ab.sh <Task2 커밋> <Task2 커밋> 1` (같은 커밋 두 번: 경로 점검 겸 기기 기준선)
  - Expected: `summary.md`가 생기고 다섯 순간 + 등급 하향 값이 기록된다.
  - 결과를 계획 문서 "측정 기록"에 붙인다.
- [ ] **Step 8: 커밋** — `git commit -m "앱 WebView 실기기 셰이더 측정 경로와 A/B 스크립트 추가"`

### Task 4: `ShaderKeeper`

**Files:**
- Create: `src/core/ShaderKeeper.ts`
- Test: `tests/ShaderKeeper.test.ts`

**Interfaces:**
- Produces:
  ```ts
  export interface KeepScope { level: number | null; tier: QualityTierLevel | null }  // null = 판·등급과 무관(게임 내내)
  export interface KeepItem { material: THREE.Material; geometry: THREE.BufferGeometry; depth?: THREE.Material }
  export interface KeepTarget {
    compileAsync(obj: THREE.Object3D): Promise<unknown>   // renderer.compileAsync(obj, camera, scene)
    add(obj: THREE.Object3D): void; remove(obj: THREE.Object3D): void  // 장면에 예열 메시 붙이기·떼기
    nextFrame(): Promise<void>
  }
  export class ShaderKeeper {
    constructor(target: KeepTarget)
    keep(key: string, scope: KeepScope, make: () => KeepItem): Promise<void>
    has(key: string): boolean
    pending(): number
    release(pred: (scope: KeepScope, key: string) => boolean): void
    clear(): void
  }
  export function jellyKeepKey(mat: JellyMaterial, tier: QualityTierLevel): string  // `jelly:${mat.customProgramCacheKey()}:cc${mat.clearcoat > 0 ? 1 : 0}:${tier}`
  export function jellyWarmGeometry(): THREE.BufferGeometry  // position·normal·aCut 삼각형 하나(SwipeMode 예열 지오메트리와 같은 속성)
  ```
- `keep`의 규칙:
  - 키가 이미 있거나 진행 중이면 `make`를 부르지 않고 scope만 새 값으로 바꾼 뒤 같은 promise를 돌려준다.
  - 새 키면 `make()` → 1e-4 크기·`frustumCulled=false`·`castShadow=true` 메시(깊이 재질이 있으면 `customDepthMaterial`)를 만든다 → `compileAsync` → 장면에 붙여 `nextFrame` 두 번 → 떼기 → 재질을 해제하지 않고 쥔다.
  - `release`·`clear`는 쥔 재질(깊이 포함)을 `dispose`한다. 지오메트리는 해제하지 않는다. 호출자는 `jellyWarmGeometry()`·`grooveWarmGeometry()`의 결과를 모듈 단위로 한 번 만들어 공유해 넘긴다.
  - `clear()` 뒤에 끝난 `keep`은 등록하지 않고 재질을 해제한다(세대 번호).

- [ ] **Step 1: 실패하는 단위 테스트 작성** (가짜 `KeepTarget`: `compileAsync`는 수동으로 푸는 promise, `nextFrame`은 즉시 완료, 재질은 `dispose` 호출을 세는 `THREE.MeshBasicMaterial`)
  - `새 키는 컴파일·예열 그리기 뒤 쥔다`: `add`·`remove`가 각각 1회, `has(key)` 참, 재질 dispose 0회
  - `같은 키 재요청은 make 를 다시 부르지 않는다`
  - `같은 키 재요청은 범위를 새 판으로 옮긴다`: level 1로 keep → level 2로 keep → `release(s => s.level === 1)` 뒤에도 `has` 참
  - `release 는 조건에 맞는 재질과 깊이 재질을 해제한다`
  - `clear 뒤 끝난 keep 은 등록되지 않는다`: keep 진행 중 `clear()` → compile promise 해결 → `has` 거짓, 재질 dispose 1회
  - `pending 은 진행 중인 keep 수다`
  - `jellyKeepKey 는 clearcoat 0 과 양수를 구분한다`: `createJellyMaterial('bear', 'medium', { press: true })`의 clearcoat를 0과 0.16으로 바꿔 키가 다른지
- [ ] **Step 2: 실패 확인** — Run: `npx vitest run tests/ShaderKeeper.test.ts` / Expected: FAIL
- [ ] **Step 3: 구현** — `src/core/ShaderKeeper.ts`. `jellyKeepKey`의 `JellyMaterial` 타입은 `src/jelly/JellyMaterial.ts`에서 가져온다.
- [ ] **Step 4: 통과 확인** — Run: `npx vitest run tests/ShaderKeeper.test.ts` / Expected: PASS
- [ ] **Step 5: 커밋** — `git commit -m "셰이더 보관소 추가"`

### Task 5: 게임에 보관소 연결 — 첫 절단·첫 찍기

**Files:**
- Modify: `src/core/Game.ts` (보관소 생성, `keepLevelShaders`, `prepareTable`(:526)·`loadLevel`(:479 부근)·`reprepare`(:387)·손실 콜백(:317)에서 호출·해제)
- Modify: `src/core/modes/GameMode.ts` (`ModeHost.shaders`, `GameMode.keepShaders?`)
- Modify: `src/core/GameDebug.ts`, `src/core/JellyDebug.ts`, `e2e/debug-api.spec.ts` (`shadersReady`)
- Modify: `e2e/shader-compile.spec.ts`(1·40판 `test.fail()` 제거), `e2e/helpers/shader.ts`(`waitShadersReady`), `e2e/memory.spec.ts`(`lap`이 `shadersReady()`를 기다림)
- Test: `tests/KnifeMode.test.ts` 등 가짜 `ModeHost`를 만드는 단위 테스트에 `shaders` 필드 추가(빌드 통과용)

**Interfaces:**
- Consumes: Task 4 `ShaderKeeper`, `jellyKeepKey`, `jellyWarmGeometry`
- Produces:
  - `ModeHost.shaders: ShaderKeeper`
  - `GameMode.keepShaders?(level: LevelDefinition, tier: QualityTierLevel): Promise<void>`: 모드 전용 변형을 등록한다. `Game.keepLevelShaders`가 공통 등록 뒤 부른다.
  - `Game.keepLevelShaders(level: LevelDefinition, tier: QualityTierLevel): Promise<void>`. 공통 등록 대상은 두 가지다. 그다음 `modes.for(level).keepShaders?.(level, tier)`를 부르고, 모두 끝나면 해당 판의 준비 완료 표시를 세운다.
    - `traits.tablePieces`이면 `new StageSession(level).pieces` 각각의 `createJellyMaterial(level.jellyType, tier, mode.materialOptions(level, id))`
    - 옵션 없는 `createJellyMaterial(level.jellyType, tier)`(칼 모드 `swap`과 틀 찍기 `onCut`이 만드는 재질과 같은 키)
    - 형상에 `slowProfile`이나 압착이 있으면 그 깊이 재질도 함께 넘긴다.
  - 디버그 `shadersReady(): boolean` = 지금 판의 `keepLevelShaders`가 끝났고 `shaders.pending() === 0`

- [ ] **Step 1: 단위 테스트 빌드 준비** — 가짜 `ModeHost`를 쓰는 테스트에 `shaders` 필드를 더한다.
  - Run: `npx vitest run` / Expected: 기존 테스트 전부 PASS(아직 동작 변화 없음)
- [ ] **Step 2: 실패 E2E 확인** — 1·40판 테스트에서 `test.fail()`을 지우고 측정 전에 `waitShadersReady`를 넣는다.
  - Run: `npx playwright test e2e/shader-compile.spec.ts -g "첫 절단|첫 찍기" --project=desktop-chromium` / Expected: FAIL(막힘 > 0)
- [ ] **Step 3: 연결 구현**
  - `Game` 생성자에서 `new ShaderKeeper({ compileAsync: o => renderer.compileAsync(o, camera, scene), add/remove: scene, nextFrame: () => clock.nextFrame() })`를 만든다.
  - `prepareTable`: 테이블 조각 루프 뒤 `await this.keepLevelShaders(level, prep.tier)`. stale 검사를 유지한다.
  - `loadLevel`: 새 판의 키만 남기고 해제(`release(s => s.level !== null && s.level !== level.id)`) → `void this.keepLevelShaders(level, this.tier)`(입력을 막지 않는다).
  - 손실 콜백: `shaders.clear()`. `reprepare`: `void this.keepLevelShaders(this.level, this.tier)`.
  - 해제 순서(`PieceSplitter.swap`의 원본 제거)는 바꾸지 않는다.
- [ ] **Step 4: 통과 확인** — Run: `npx playwright test e2e/shader-compile.spec.ts -g "첫 절단|첫 찍기" --project=desktop-chromium --project=mobile-chromium` / Expected: PASS
- [ ] **Step 5: 회귀 확인** — Run: `npx playwright test e2e/memory.spec.ts e2e/context-loss.spec.ts e2e/stamp.spec.ts e2e/split.spec.ts e2e/debug-api.spec.ts --project=desktop-chromium` / Expected: PASS
  - `memory.spec`가 프로그램 수 증가로 실패하면 보관 범위(현재 판·다음 판만)를 확인한다. 예산을 고쳐 통과시키지 않는다.
- [ ] **Step 6: 추가 발견 순간 점검(설계 6절 6번)**
  - `e2e/shader-compile.spec.ts`에 기록 전용 테스트 `판 전환 착지 직후 10프레임(기록)`을 추가한다. 1판 결과 → 자동 진행 → 2판 `ready` 뒤 10프레임의 막힘을 `logPerf`로 남긴다.
  - 막힘이 `loadLevel`에서 새로 만든 `CuttingGuides` 재질 때문이면, 가이드 재질을 `fx:guides` 키(scope null)로 보관해 막고 이 테스트를 0 단언으로 바꾼다.
  - 보관만으로 막히지 않거나 다른 원인이면 측정 기록에 B·C 후보로 적고 단언하지 않는다.
- [ ] **Step 7: 커밋** — `git commit -m "판 준비·진입 때 조각 교체 셰이더를 보관해 첫 절단·찍기 재컴파일 제거"`

### Task 6: 메스 칼자국

**Files:**
- Modify: `src/cutting/ScalpelGroove.ts` (`createGrooveMaterial`·`grooveWarmGeometry` 내보내기, `setPath`가 `createGrooveMaterial` 사용)
- Modify: `src/core/modes/KnifeMode.ts` (`keepShaders`)
- Modify: `e2e/shader-compile.spec.ts`(메스 두 테스트 `test.fail()` 제거)
- Test: `tests/ScalpelGroove.test.ts`(없으면 생성)

**Interfaces:**
- Produces:
  - `export function createGrooveMaterial(uniforms: Record<string, THREE.IUniform>): THREE.ShaderMaterial`: 지금 `setPath` 안의 설정(같은 `vert`·`frag` 문자열, `transparent: true`, `depthWrite: false`, `side: THREE.DoubleSide`)을 옮긴 것이다.
  - `export function grooveWarmGeometry(): THREE.BufferGeometry`: `grooveGeometry`에 두 점을 넣은 결과다.
  - `KnifeMode.keepShaders(level, tier)`: 그 판의 단계 중 하나라도 메스면 `host.shaders.keep('fx:groove', { level: null, tier: null }, …)`. 이 키는 해제하지 않는다.
  - 판정은 `level.tool === 'scalpel'` 또는 단계별 도구 정의 중 메스가 있는지로 한다(`CurveStages`의 단계 도구 필드를 확인).

- [ ] **Step 1: 실패 테스트**
  - `createGrooveMaterial 은 setPath 가 만드는 재질과 같은 셰이더·플래그다`: `setPath`로 만든 칼자국 메시의 재질과 `vertexShader`·`fragmentShader`·`transparent`·`depthWrite`·`side`가 같은지 단위 테스트한다.
  - E2E는 메스 두 테스트에서 `test.fail()`을 지운다.
- [ ] **Step 2: 실패 확인** — Run: `npx vitest run tests/ScalpelGroove.test.ts` / Expected: FAIL(내보내기 없음)
- [ ] **Step 3: 구현** — `setPath`의 재생성 구조와 회전판 매 프레임 재생성은 그대로 둔다(할당 줄이기는 C).
- [ ] **Step 4: 통과 확인** — Run: `npx vitest run tests/ScalpelGroove.test.ts && npx playwright test e2e/shader-compile.spec.ts -g "메스" --project=desktop-chromium --project=mobile-chromium && npx playwright test e2e/scalpel.spec.ts e2e/spin.spec.ts e2e/equipment-curve.spec.ts --project=desktop-chromium` / Expected: PASS
- [ ] **Step 5: 커밋** — `git commit -m "칼자국 셰이더를 보관해 메스 긋기 중 재컴파일 제거"`

### Task 7: 찾기 곰 누름·곰 압착 깊이 재질

**Files:**
- Modify: `src/core/modes/OddJellyMode.ts` (`keepShaders`, `prepare`의 컴파일 루프 뒤 호출)
- Modify: `src/core/modes/BearCrushMode.ts` (`keepShaders`)
- Modify: `e2e/shader-compile.spec.ts`(곰 누름 `test.fail()` 제거)

**Interfaces:**
- Consumes: `ModeHost.shaders`, `jellyKeepKey`, `jellyWarmGeometry`
- Produces:
  - `OddJellyMode.keepShaders(level, tier)`: 판의 몸체마다 `prepare`와 같은 옵션으로 재질 두 개를 만들어 등록한다. 키가 같으면 보관소가 중복을 없앤다.
    - clearcoat 0.16(그대로)
    - clearcoat 0(누름 끝 상태)
    - 깊이 재질 `createPressShadowMaterial`도 함께 넘긴다.
    - `prepare`는 `ready = true` 전에 이것을 `await`한다. 그래서 E2E의 `oddJelly().ready`가 등록 완료를 뜻한다.
  - `BearCrushMode.keepShaders(level, tier)`: `materialOptions`로 만든 판 재질과 압착 깊이 재질을 등록한다. `prepare`에서도 같은 방식으로 `ready` 전에 `await`한다.
  - clearcoat 하한은 바꾸지 않는다(외관 유지).

- [ ] **Step 1: 실패 확인** — `test.fail()`을 지운다. Run: `npx playwright test e2e/shader-compile.spec.ts -g "곰 누름" --project=desktop-chromium` / Expected: FAIL
- [ ] **Step 2: 구현**
- [ ] **Step 3: 통과 확인** — Run: `npx playwright test e2e/shader-compile.spec.ts -g "곰 누름" --project=desktop-chromium --project=mobile-chromium && npx playwright test e2e/odd-jelly.spec.ts e2e/bear-crush.spec.ts e2e/equipment-crush.spec.ts --project=desktop-chromium` / Expected: PASS
- [ ] **Step 4: 커밋** — `git commit -m "찾기 누름 변형과 압착 그림자 셰이더 보관"`

### Task 8: 등급 하향 비동기화

**Files:**
- Modify: `src/core/Game.ts` (`requestTier`, `frame`의 governor 경로, `setTier` 끝에 옛 등급 키 해제, 손실·복구 처리)
- Modify: `src/core/GameDebug.ts`, `src/core/JellyDebug.ts`, `e2e/debug-api.spec.ts` (`requestTier`·`tierPending`)
- Modify: `e2e/shader-compile.spec.ts`, `e2e/perf.spec.ts`, `e2e/device/shader-device.spec.ts` (등급 시나리오를 `requestTier`로)

**Interfaces:**
- Consumes: Task 5 `keepLevelShaders`, 모드 `keepShaders`
- Produces:
  - `Game.requestTier(t: QualityTierLevel): Promise<void>`:
    - `t === this.tier`이거나 같은 등급을 기다리는 중이면 아무것도 하지 않는다.
    - 그 밖에는 세대 번호를 올리고 대기 표시를 한 뒤 다음을 등록한다.
      - `keepLevelShaders(this.level, t)`
      - 지금 살아 있는 조각마다 `createJellyMaterial(p.shape.type, t, this.mode.materialOptions(this.level, p.data.id))`(키로 중복 제거)
    - 끝났을 때 판이 바뀌었으면 새 판으로 등록을 반복한다.
    - 세대가 같고 컨텍스트가 살아 있으면 `setTier(t)`로 확정한다.
  - `setTier`는 끝에 `shaders.release(s => s.tier !== null && s.tier !== t)`를 부른다(`forceTier` 경로도 같다).
  - 손실: 세대를 올려 대기를 취소한다. 복구(`reprepare`) 뒤 `governor.current !== this.tier`이면 `requestTier(governor.current)`.
  - 디버그: `requestTier(t)`, `tierPending(): QualityTierLevel | null`. `forceTier`는 그대로 동기다.
  - `frame`: `holdTier`가 꺼져 있을 때 `const t = governor.sample(realDt); if (t) void this.requestTier(t);`

- [ ] **Step 1: 실패 E2E 작성** (`e2e/shader-compile.spec.ts`)
  - `등급 하향: <판> requestTier 확정 프레임 막힘 0`(1·40·66·59판, `quality=medium`)
    1. 준비 완료(`shadersReady`, 66·59는 각 모드 `ready`)를 기다린다.
    2. mark → `requestTier('low')`
    3. `tier() === 'low'`가 될 때까지 기다린 뒤 10프레임
    4. since → 막힘 0
  - `등급 요청 대기 중 판을 바꿔도 확정 프레임 막힘 0`: 1판 `requestTier('low')` 직후 `gotoLevel(2)` → `tier()==='low'`·새 판 `ready` 뒤 mark → 첫 절단 → 막힘 0
  - 천천히 썰기(5판)·휘둘러 베기(46판)는 같은 절차로 `logPerf`만 남기고 단언하지 않는다(설계 6절 5번).
- [ ] **Step 2: 실패 확인** — Run: `npx playwright test e2e/shader-compile.spec.ts -g "등급" --project=desktop-chromium` / Expected: FAIL(`requestTier` 없음)
- [ ] **Step 3: 구현**
- [ ] **Step 4: 통과·회귀 확인** — Run: `npx playwright test e2e/shader-compile.spec.ts e2e/context-loss.spec.ts e2e/debug-api.spec.ts e2e/slow-feel.spec.ts e2e/stamp.spec.ts e2e/odd-jelly.spec.ts e2e/bear-crush.spec.ts --project=desktop-chromium` / Expected: PASS(기존 `forceTier` 테스트 포함)
- [ ] **Step 5: 기기 시나리오 교체** — `shader-device.spec.ts`의 등급 시나리오를 `requestTier('low')` 확정 기준으로 바꾼다. Task 2·3 기준선 커밋에는 `requestTier`가 없으므로, 스펙은 `typeof __jellyDebug.requestTier === 'function'`이면 그것을 쓰고 아니면 `forceTier`를 쓴다. 그래야 A/B 양쪽에서 같은 순간을 잰다.
- [ ] **Step 6: 커밋** — `git commit -m "품질 등급 하향을 셰이더 보관 뒤 확정하도록 비동기화"`

### Task 9: 전체 검증·실기기 A/B·문서·머지

**Files:**
- Modify: 이 계획 문서("측정 기록"), `PROGRESS.md`
- Modify: `docs/agent-reference/debug-api.md`(새 디버그 키), `docs/agent-reference/architecture.md`(`ShaderKeeper`·`keepShaders` 훅·`requestTier`), `docs/agent-reference/testing.md`(기기 측정 실행법·`device-ab.sh`)

- [ ] **Step 1: 단위·빌드** — Run: `npm test && npm run build` / Expected: 전부 통과
- [ ] **Step 2: 모바일 기능 E2E** — Run: `npm run e2e:mobile` / Expected: 실패 0. 부하 실패는 해당 파일을 단독 재실행하고, 최초 실패와 재실행 결과를 함께 적는다.
- [ ] **Step 3: 데스크톱·WebKit 셰이더 E2E** — Run: `npx playwright test e2e/shader-compile.spec.ts --project=desktop-chromium --project=desktop-webkit` / Expected: PASS. WebKit의 `hasParallelCompile` 값을 기록한다.
- [ ] **Step 4: 에뮬레이션 성능 A/B** — 기준 Task 2 커밋, 변경 HEAD. `docs/agent-reference/testing.md`의 A/B 절차대로 `perf-desktop-chromium`·`perf-mobile-chromium --no-deps`를 번갈아 3회 돌린다. 측정 중에는 `src`를 고치지 않는다.
  - Expected: 기존 지표가 6절 규칙으로 회귀하지 않는다.
  - 판정선을 넘은 지표는 최대 8회까지 다시 잰다.
- [ ] **Step 5: 실기기 A/B** — Run: `scripts/device-ab.sh <Task2 커밋> HEAD 3`
  - Expected: head의 다섯 순간과 등급 하향의 `blocking=0`.
  - 순간별 `maxGapMs` 중앙값의 전·후 값과 개선 폭을 표로 기록한다. 절대 예산은 없다.
  - `discarded=1` 실행은 빼고 센다.
- [ ] **Step 6: 문서 갱신** — 측정 기록과 위 세 참조 문서를 고친다. `PROGRESS.md`에는 A 완료, 실기기 결과 요약, iPhone 미검증, "main 반영·미배포"를 적는다.
- [ ] **Step 7: 최종 독립 리뷰** — AGENTS.md 기본값으로 전체 브랜치를 리뷰한다. 지정 모델을 쓸 수 없으면 대체하지 않고 제한을 알린다. 지적을 반영한 뒤 Step 1·2를 다시 확인한다.
- [ ] **Step 8: 로컬 main 머지** — `git checkout main && git merge --no-ff <브랜치>`. **푸시하지 않는다.** 머지 후 `git status`가 깨끗하고 `git log origin/main..main`에 이번 커밋들이 있는지 확인해 보고한다.

## 측정 기록

**A/B 기준 커밋: `67c73eb`** (계측 포함, 수정 전).

### Task 2 기준선 (2026-10-28, 로컬 맥, 1회)

`blocking` = 그리기 안 link + 미완료 첫 사용. 기능 E2E 3프로젝트에서 다섯 순간 모두 `test.fail` 예상대로 막힘 > 0.

| 순간 | desktop-chromium | mobile-chromium | desktop-webkit |
|---|---|---|---|
| first-cut(1) | 1 | 1 | 1 |
| first-stamp(40) | 1 | 1 | 1 |
| odd-press(66) | 3 | 1 | 1 |
| scalpel-draw(14) | 70 | 68 | 14 |
| spin-scalpel-hold(70) | 210 | 360~511 | 81 |

성능 프로젝트 `maxGapMs`(자르지 않은 실제 간격, 기록 전용):

| 순간 | perf-desktop | perf-mobile |
|---|---|---|
| first-cut | 132.2 | 94.8 |
| first-stamp | 26.7 | 20.0 |
| odd-press | 28.0 | 18.4 |
| scalpel-draw | 25.5 | 18.5 |
| spin-scalpel-hold | 27.3 | 21.3 |
| tier-drop 1 / 40 / 66 / 59 (forceTier, 막힘) | 19.7(1) / 20.4(1) / 89.1(2) / 20.0(0) | 19.4(1) / 16.8(1) / 18.8(2) / 17.1(0) |

- 59판 등급 하향은 기준선부터 막힘 0이다.
- 데스크톱 Chrome은 프로그램 캐시가 있어 재컴파일 ms가 작게 보인다. 크기 판단은 실기기 결과로 한다.

### Task 3 실기기 기준선 (2026-10-28, S22 Ultra, medium, `67c73eb`)

- GPU 셰이더 디스크 캐시: 앱 데이터(`run-as` 아래)에 GPUCache·GrShaderCache·`com.android.opengl.shaders_cache`가 없다. 실행마다 앱을 강제 종료해 처음 실행 조건(`cache=cold-start`)으로 잰다. warm 보조 지표는 해당 없음.
- 첫 단발 실행(배터리 41.8~42℃): first-cut 34.1ms(막힘 1), first-stamp **218.8ms**(1), odd-press **148.3ms**(3), scalpel-draw 43.6ms(68), spin-scalpel-hold 44.0ms(694), tier-drop-1 **172.7ms**(1).
- 같은 APK를 base·head로 둔 스크립트 점검 1회(아래)에서는 값이 더 낮았다. 단발 값의 흔들림이 커서 판정은 3회 중앙값으로 한다.

| 순간 | base | head(같은 APK) | 막힘 |
|---|---|---|---|
| first-cut | 110.5 | 100.0 | 1 |
| first-stamp | 68.9 | 61.5 | 1 |
| odd-press | 77.5 | 73.8 | 3 |
| scalpel-draw | 41.9 | 40.3 | 68 |
| spin-scalpel-hold | 41.3 | 42.2 | 681~684 |
| tier-drop-1 | 50.0 | 47.6 | 1 |

### Task 9 에뮬레이션 성능 A/B (기준 `67c73eb`, 데스크톱·모바일 성능 프로젝트 번갈아 3회)

- 셰이더 순간 막힘 중앙값은 기준 → 변경으로 모두 0이 됐다.
  - 데스크톱: 첫 절단 1, 첫 찍기 1, 곰 누름 3, 메스 70, 회전판 211, 등급 1·1·3 → 0
  - 모바일: 68·360 등 → 0
- 기존 지표 110개 중 판정선을 넘은 3개를 8회까지 다시 쟀다. 25판 물총 `strokeMaxMs`는 흔들림이었고, 2개는 실제 회귀였다.
  - 데스크톱 45판 `prepMaxMs`: 7.0 → 9.2
  - 모바일 45→46 `loadMs`: 3.2 → 4.2
- 원인: 판 진입 직후 보관소가 여러 셰이더를 한꺼번에 컴파일해 틀 찍기 첫 준비 프레임과 겹쳤고, 진입 프레임에서 이전 판 보관을 해제했다. 진입 시 등록을 끈 HEAD는 콜드 조건에서 기준과 같았다(7.15 vs 7.5).
- 수정(`873c784`): 진입 시 보관을 다음 프레임부터 하나씩 한다. 콜드 4회 A/B에서 45판 준비 7.4(기준) / 7.2(변경), 45→46 로딩 4.2 / 2.8이다.
- 75판 배낭 준비 8ms 예산 초과는 기준·변경 양쪽에서 같은 빈도로 나타나는 기존 경계 흔들림이다.

### Task 9 실기기 A/B (S22 Ultra 앱, medium, `67c73eb` → `873c784`, 번갈아 3회, cold-start, 39~40.3℃)

| 순간 | maxGapMs 기준 | maxGapMs 변경 | 막힘 기준 → 변경 |
|---|---|---|---|
| first-cut | 47.0 | 34.7 | 1 → 0 |
| first-stamp | 61.5 | 57.1 | 1 → 0 |
| odd-press | 40.3 | 23.0 | 3 → 0 |
| scalpel-draw | 39.8 | 32.8 | 68 → 0 |
| spin-scalpel-hold | 44.7 | 41.5 | 687 → 0 |
| tier-drop-1 | 33.3 | 26.4 | 1 → 0 |

실패·제외 실행 0, 36줄. 원본은 `.playwright-mcp/device-ab/20261028-194740/`에 있다(저장소 무시 대상). iPhone은 미측정이다.