# Web Engine Extraction Plan

이 문서는 추후 데모나 실제 게임 구현이 리뷰/검증 페이지의 임시 코드에 다시 의존하지 않도록, 확정된 웹 구현 요소를 `web/engine/`으로 모듈화할 때의 기준을 정리한다.

## 목표

`web/`의 리뷰 페이지에서 검증이 끝난 요소만 `web/engine/`으로 옮긴다. 이후 `web/demo/`나 실제 플레이 페이지는 리뷰 HTML을 직접 참조하지 않고 `web/engine/` API만 사용한다.

## 승격 기준

- EXE, CNS, WLK/MLK, 또는 수동 검증으로 확정된 동작만 엔진으로 승격한다.
- 후보, 추정, 비교용 UI, 임시 smoke 결과는 엔진에 넣지 않는다.
- 리뷰 페이지는 검증과 시각화 용도이고, 엔진은 재사용 가능한 런타임 코드만 가진다.
- 같은 기능이 여러 리뷰 페이지에 흩어져 있으면 가장 최신 확정 구현을 기준으로 하나의 모듈로 합친다.

## 1차 엔진 후보

- `cns/renderer`: CNS 로딩, 팔레트/투명 처리, source rect draw, tilemap draw.
- `map`: 확정 맵 조립, layer0 렌더링, layer1 collision/foreground/conditional foreground/animation flag 해석.
- `field/runtime`: 640x480 frame layout, camera, 3x1 발판 충돌, field actor walking, follower trail.
- `hud`: window/status/icon/face 기반 normal HUD, 메뉴 window template, prompt window, face placement.
- `battle-core`: 전투 공식, 데미지/미스/스침/크리티컬/상태이상/취기 계산.
- `battle/animation`: player/monster frame rect, frame gate 기반 기본 액션 재생, hit/miss/down frame selection.
- `audio`: WLK zero-based id 재생, MLK/MIDI playback, lazy soundfont loading.
- `input`: keyboard/gamepad/touch mapping, confirm/cancel/skill-info/mode-change abstraction.

## 제외 대상

- `*_review.html`의 근거 표, 후보 목록, 디버그 전용 matrix.
- 과거 PNG 산출물에 의존하던 렌더링 경로.
- EXE 근거가 없는 자동 추정 rect, route, scene, object placement.
- 데모 전용 UI 장식 또는 모바일 컨트롤러 레이아웃.

## 권장 구조

```text
web/engine/
  cns/
  map/
  field/
  hud/
  battle/
  audio/
  input/
  data/
```

`data/`에는 사람이 직접 수정하는 임시 JSON이 아니라, 확정 산출물에서 축약한 런타임 manifest만 둔다.

## 현재 승격된 모듈

```text
web/engine/
  audio/midi_bgm_player.js
  audio/midi_soundfont.js
  audio/midi_soundfont_storage.js
  audio/midi_spessasynth_adapter.js
  battle/animation.js
  cns/renderer.js
  field/runtime.js
```

root-level runtime shim(`web/cns_renderer.js`, `web/field_runtime.js`,
`web/midi_*.js`)과 구 엔진 경로(`web/engine/cns_renderer.js`,
`web/engine/field_runtime.js`, `web/engine/battle_animation.js`)는 제거된
상태를 유지한다. 새 페이지는 현재 승격된 모듈을 직접 로드한다.

## 진행 순서

1. 현재 리뷰 페이지에서 실제 런타임에 필요한 함수와 데이터를 식별한다.
2. 같은 기능의 중복 구현을 제거하고 `web/engine/*` 모듈로 이동한다.
3. 리뷰 페이지는 새 엔진 모듈을 사용하도록 역으로 교체한다.
4. 데모/실제 게임 페이지는 엔진 API만 사용한다.
5. 더 이상 쓰지 않는 legacy helper와 중간 산출물은 삭제한다.

## 검증

- 엔진화 전후 리뷰 페이지의 표시가 달라지지 않아야 한다.
- `git diff --check`를 통과해야 한다.
- 가능한 경우 8013 서버에서 핵심 페이지를 열어 canvas/runtime error가 없는지 확인한다.
- 엔진 모듈은 후보 데이터를 확정 데이터처럼 노출하지 않아야 한다.