# gdi-hwpx — 설계 노트 / 유지보수

## 무엇인가
딸깍 개발실 `md2hwpx`(+ CeoBriefing 이 쓰는 방식)의 HWPX 생성 엔진을, **헤드리스 브라우저 없이**
Claude Code 세션 안 Node 스크립트로 그대로 돌리는 로컬 스킬. 구 `hwpx-autofill-conversion`
(범용 Python 템플릿-스플라이싱) 스킬의 대체.

## 왜 이렇게 되나 (재사용이 깔끔한 이유)
- `md2hwpx` 의 핵심 3모듈은 브라우저 전역(`window.X = (()=>{})()`)이지만 **DOM 의존이 사실상 0**이다.
  `hwpxBuilder.js` 는 의도적으로 본문을 string-concat 으로 만든다(XMLSerializer 의 hp:/hh: prefix
  파손 함정 회피). 따라서 `{ window: self }` shim + JSZip + marked 만 주입하면 **엔진 0줄 수정**으로 Node 구동.
- 이는 CeoBriefing 이 브라우저에서 하던 경로(`MdParser.parse → PresetManager.analyzeHwpx →
  HwpxBuilder.buildHwpx + 매핑 + 양식`)와 **동일**하다. 단지 런타임만 브라우저 → Node.
- Node 18+ 의 전역 `Blob` 덕에 `generateAsync({type:'blob'})` 도 그대로 동작(소스 무수정).

## 구성
```
gdi-hwpx/
├── SKILL.md            # 사용 시점·방법 + 마크다운 작성 규약
├── build_hwpx.mjs      # CLI 러너 (파싱→분석→매핑→빌드→자가검증)
├── loader.mjs          # {window:self} 샌드박스 로더 (vm)
├── automap.mjs         # 양식 스타일 이름·글머리 자동 매핑 (md2hwpx 휴리스틱 포팅)
├── mapping.gdi.json    # 번들 양식 전용 정밀 매핑 (자동 적용)
├── selftest.mjs        # 헤드리스 회귀 테스트 (22 PASS)
├── engine/             # ★ md2hwpx 엔진 스냅샷 + 벤더 라이브러리
│   ├── parser.js          (md2hwpx/js/parser.js)
│   ├── presetManager.js   (md2hwpx/js/presetManager.js)
│   ├── hwpxBuilder.js     (md2hwpx/js/hwpxBuilder.js)
│   ├── table-fit.js       (shared/table-fit.js — node/browser 듀얼)
│   ├── jszip.min.js       (jszip@3.10.1 UMD)
│   └── marked.min.js      (marked@13.0.0 UMD)
└── templates/
    └── gdi-default.hwpx   # 번들 기본 양식 (사용자 제공 표준 양식)
```

## 엔진 스냅샷 갱신 (GDI-Apps 의 md2hwpx 가 업데이트됐을 때)
스냅샷은 자체완결(GDI-Apps 경로 런타임 의존 X)이라 자동 갱신되지 않는다. md2hwpx 개선분을 반영하려면
GDI-Apps 리포의 최신본을 `engine/` 으로 다시 복사한다:

```bash
SRC=<GDI-Apps 경로>
cp "$SRC/md2hwpx/js/parser.js"        engine/parser.js
cp "$SRC/md2hwpx/js/presetManager.js" engine/presetManager.js
cp "$SRC/md2hwpx/js/hwpxBuilder.js"   engine/hwpxBuilder.js
cp "$SRC/shared/table-fit.js"         engine/table-fit.js
node selftest.mjs    # 회귀 확인 (22 PASS 유지되어야 함)
```
스냅샷 당시 버전: parser v0.5.1 · presetManager v0.3.0 · hwpxBuilder v0.5.0 (2026-06-14 기준 worktree).
JSZip/marked 는 CDN UMD 와 동일 — 거의 갱신 불필요.

## 알려진 한계 / 후속 후보
- 표지(연구진·발행처) 보존 X → 필요 시 CeoBriefing `composeSection` 식 프런트/테일 프레임 보존 추가.
- 이미지 임베드 X(`imageRegistry: null`) → `md2hwpx/js/imageEmbed.js` + 이미지 레지스트리 주입으로 확장 가능.
- TOC 자동 생성 X → 한컴 차례 갱신 또는 마크다운에 목차 포함.

## 의존성
- Node 18+ (전역 Blob/TextEncoder). 권장: 현재 검증 환경 Node 24.
- 외부 npm 설치 불필요 — JSZip/marked 는 `engine/` 에 UMD 로 번들.
