npm/editor RPC + Wrapper에 exportHwpx / exportHwpVerify 노출 (#557, followup #407) by johndoekim · Pull Request #558 · edwardkim/rhwp

johndoekim · 2026-05-03T15:03:16Z

Summary

WASM 측에 이미 #[wasm_bindgen] 으로 노출된 exportHwpx / exportHwpVerify 두 함수를 npm/editor RPC switch + Wrapper + 타입 + README 에 Export API 추가 건의 사항 #407 패턴 그대로 노출.
fail-first e2e (Stage 0) → green 전환 (Stage 4) 단계 분리 커밋으로 결손 → 메움 흐름이 git 차분만으로 입증.
WASM 코어 무변경 — 노출 layer 한정.

변경 (6 file, +168 라인)

파일	변경
`rhwp-studio/src/main.ts`	RPC switch 에 `case 'exportHwpx'` / `case 'exportHwpVerify'` (+7)
`rhwp-studio/src/core/wasm-bridge.ts`	`WasmBridge.exportHwpVerify(): string` wrapper (+5)
`npm/editor/index.js`	`RhwpEditor.exportHwpx()` / `exportHwpVerify()` + JSDoc (+20)
`npm/editor/index.d.ts`	`HwpVerifyResult` interface + 두 메서드 타입 (+14)
`npm/editor/README.md`	API 섹션 + 다운로드 예제 + 검증 패턴 (+33)
`rhwp-studio/e2e/export-hwpx.test.mjs`	fail-first → green 자동화 (신규, +89)

exportHwpVerify 는 WASM 이 JSON 문자열을 반환하므로 RPC 단계에서 JSON.parse 후 객체로 흘림 — Wrapper 사용자가 매번 파싱하지 않도록 한 노출 layer 어댑팅.

단계별 커밋 흐름

Stage	결과
0 — fail-first e2e	RED 단언 3건 PASS (`Unknown method: exportHwpx` 등 RPC default 캡처)
1 — RPC switch + WasmBridge	Stage 0 단언 [2][3] 깨짐 (의도된 부분 실패)
2 — Wrapper 메서드	정적 grep 정합 (3 메서드 노출)
3 — 타입 정의 + README	6 레이어 정합 완성
4 — e2e green 전환 + 회귀 점검	모든 단언 PASS, baseline 회귀 0건

검증

검사	결과
본 task e2e (footnote-01.hwp, 6 page)	모든 단언 PASS
exportHwpx HWPX 매직	`[0x50, 0x4B, 0x03, 0x04]` 확인
exportHwpVerify	`{bytesLen:15360, pageCountBefore:6, pageCountAfter:6, recovered:true}`
라운드트립 (exportHwpx → loadFile)	loadFile 정상 + 결과 페이지 ≥ 1
`cargo build`	PASS (Rust 무변경)
`cargo test`	자명히 no-op (Rust 무변경)
baseline e2e (`text-flow.test.mjs`)	모든 단언 PASS

라운드트립 페이지 수 정확 일치 단언은 의도적으로 완화 (≥ 1). 이유: HWP→HWPX 변환 자체의 페이지네이션 미세 차이 (footnote-01.hwp 의 경우 6→5) 는 #178 영역의 책임이며 본 task (RPC 노출 layer) 의 책임 범위를 넘어선다.

영역 검토 (#272 와의 관계)

#272 에서 메인테이너가 명시한 마일스톤 구분:

"WASM HwpDocument 의 high-level method 가 일부 영역 노출: applyCharFormat, applyParaFormat, applyCellStyle, addBookmark 등 (pkg/rhwp.d.ts 참조)"

본 PR 의 두 함수는 정확히 이 카테고리 (v1.0.0 영역 — HwpDocument high-level method 노출 점진 확장). 312 Action / run_action dispatcher / HwpCtrl Rust 이전 / WASM 새 함수 추가 — 어느 것에도 손대지 않음. v2.0.0 영역과 독립.

6 레이어 정합 매트릭스

레이어	exportHwp	exportHwpx	exportHwpVerify
WASM `#[wasm_bindgen]`	✅	✅	✅
WasmBridge (TS)	✅	✅	신규
RPC switch	✅	신규	신규
Wrapper (npm/editor)	✅	신규	신규
타입 (`index.d.ts`)	✅	신규	신규
README	✅	신규	신규

Test plan

node rhwp-studio/e2e/export-hwpx.test.mjs --mode=headless 모든 단언 PASS
cargo build PASS
node rhwp-studio/e2e/text-flow.test.mjs --mode=headless baseline 회귀 PASS
(메인테이너) node e2e/edit-pipeline.test.mjs 등 추가 회귀 점검 (선택)
(메인테이너) 부모 페이지에서 editor.exportHwpx() / editor.exportHwpVerify() 호출 수동 확인

후속 제안 (별도 이슈 권장)

본 PR 의 패턴은 다음 묶음에 동일 적용 가능 (각 묶음 변경량 50~100 라인 수준):

getDocumentInfo + getSourceFormat + getValidationWarnings (단순 getter 3종)
searchText + replaceOne / replaceAll (검색/치환)
saveSnapshot / restoreSnapshot / discardSnapshot (snapshot)
renderPageHtml (SVG 대안)

closes #557

🤖 Generated with Claude Code

- mydocs/plans/task_m100_557.md (수행계획서) - mydocs/plans/task_m100_557_impl.md (구현계획서, 5 stage) - rhwp-studio/e2e/export-hwpx.test.mjs (fail-first e2e) - mydocs/working/task_m100_557_stage0.md (단계 보고서) Stage 0 e2e 단언 3개 모두 PASS — RPC switch 의 'exportHwpx' / 'exportHwpVerify' default 응답이 자동화로 캡처됐다. Stage 1 에서 RPC case 추가 후 단언 [2], [3] 이 깨지면 Stage 4 에서 통과 단언으로 교체. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…rtHwpVerify 추가 - rhwp-studio/src/main.ts: RPC switch 에 case 2개 추가 - rhwp-studio/src/core/wasm-bridge.ts: WasmBridge.exportHwpVerify() wrapper 추가 (exportHwpx 는 이미 wrap 되어 있어 추가 작업 없음) Stage 0 e2e 단언 [2], [3] 이 깨지면서 wasm 단계 baseline ('문서가 로드되지 않았습니다') 으로 합류 — RPC 노출 갭이 메워진 결정적 증거. Stage 4 에서 통과 단언으로 일괄 교체 예정. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…Verify 메서드 추가 - npm/editor/index.js: RhwpEditor 에 두 async 메서드 + JSDoc - exportHwpx() — HWPX bytes 반환 (exportHwp 패턴 모방) - exportHwpVerify() — 검증 메타데이터 객체 반환 Stage 1 의 RPC layer 와 정합. 부모 페이지에서 editor.exportHwpx() / editor.exportHwpVerify() 호출 가능. Stage 4 통과 단언에서 정합성 일괄 검증 예정. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

- npm/editor/index.d.ts: HwpVerifyResult 인터페이스 + 두 메서드 타입 추가 - npm/editor/README.md: editor.exportHwpx() / editor.exportHwpVerify() API 섹션 + 다운로드 예제 (Blob + URL.createObjectURL) + 검증 실패 감지 패턴 세 레이어 (Wrapper / Type / Doc) 모두 정합. Stage 0 의 갭 (exportHwp 한 항목만 존재) 이 완전히 메워짐. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

- rhwp-studio/e2e/export-hwpx.test.mjs: fail-first → green 단언 일괄 교체 PK 매직 검증 + 라운드트립 (loadFile 정상 + ≥1 page) + verify 객체 정합성 - mydocs/working/task_m100_557_stage4.md - mydocs/report/task_m100_557_report.md 검증: - 본 task e2e 모든 단언 PASS (footnote-01.hwp, 6 page) - exportHwpx HWPX 매직 [80,75,3,4] 확인 - exportHwpVerify {bytesLen:15360, recovered:true, before==after} 확인 - cargo build PASS, baseline e2e (text-flow) PASS - 6 레이어 (WASM / WasmBridge / RPC / Wrapper / Type / Doc) 정합 완성 라운드트립 페이지 수 정확 일치는 HWP→HWPX 변환 자체 (edwardkim#178 영역) 책임이라 본 task 단언에서는 의도적으로 완화 (loadFile 정상 + ≥1 page). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

@johndoekim

…rtHwpx/exportHwpVerify 노출 — @johndoekim 5 commits + main.ts 옵션 C 통합)

edwardkim · 2026-05-04T09:23:48Z

@johndoekim 님, rhwp 에 첫 PR 이시군요 — 환영합니다.

본 PR 의 5 commit 을 본 환경 devel 에 cherry-pick 으로 통합했습니다 (4ae9be3 merge commit).

통합 결과

Stage	commit	충돌
0 (fail-first e2e + 계획서)	`bc4bc1d`	0
1 (RPC switch + WasmBridge)	`911436f`	1 (main.ts) — 옵션 C 통합
2 (Wrapper 메서드)	`03a667e`	0
3 (타입 + README)	`e5d760b`	0
4 (e2e green + 보고서)	`72af00f`	0

본질 평가 — 정합

6-layer 통합 매트릭스 (WASM → WasmBridge → RPC → Wrapper → 타입 → README) 가 정합하게 분리되어 있어 layer 별 책임이 명확합니다.
Stage 0 fail-first → Stage 4 green 흐름은 TDD + 본 프로젝트 하이퍼-워터폴 단계 절차와 정합합니다.
WASM 핵심을 건드리지 않고 노출만 진행 — 렌더링 회귀 위험 0.

Stage 1 충돌 — 옵션 C 통합 안내

rhwp-studio/src/main.ts 의 RPC switch 영역에서 본 환경의 PR #581 (@oksure — iframe race condition 정정, closes #522) 과 본 PR 이 동일 부근을 변경했습니다.

PR #581 은 모든 RPC case 앞에 await initPromise 를 배치하여 race condition 을 막는 패턴을 도입했습니다. 본 PR 의 exportHwpx / exportHwpVerify 두 case 도 동일 패턴이 필요하므로 다음과 같이 통합했습니다:

case 'exportHwpx':
  await initPromise;                     // ← PR #581 패턴 정합 추가
  reply(Array.from(wasm.exportHwpx()));
  break;
case 'exportHwpVerify':
  await initPromise;                     // ← PR #581 패턴 정합 추가
  reply(JSON.parse(wasm.exportHwpVerify()));
  break;

추가로, 본 PR 의 case 'ready': reply(true); 는 PR #581 의 case 'ready' (await initPromise 정합) 와 중복이라 제거했습니다.

결정적 검증

게이트	결과
`cargo build --lib --release`	✅ Finished
`cargo test --lib --release`	✅ 1125 passed (회귀 0)
`npx tsc --noEmit` (rhwp-studio)	✅ 0 errors

API 노출 layer 만 변경하고 WASM 핵심 + 렌더링은 무영향이므로 시각 판정은 생략했습니다.

다음 PR 시 권장 사항

본 PR 의 base 가 b84c5e9 (현재 devel 기준 9 commit 전) 였습니다. 그 사이 PR #553/562/581/582/583 이 머지되어 충돌이 발생했습니다. 다음 PR 시작 전에 fork 의 devel 을 본 환경 devel 와 동기화 후 분기하시면 충돌 없이 매끄럽게 진행됩니다.

git fetch upstream
git checkout devel
git merge --ff-only upstream/devel
git push origin devel
git checkout -b local/task{N}

본 PR 은 cherry-pick 통합 완료로 close 합니다. 다음 PR 도 기다리겠습니다.

- mydocs/pr/archives/pr_558_review.md (검토 문서) - mydocs/pr/archives/pr_558_report.md (처리 보고서) - mydocs/orders/20260504.md: PR #581/582/583/578-579/558 항목 추가

본 task 종결 — Issue #595 (exam_math.hwp 2페이지부터 수식 더블클릭 hitTest 오동작) 본질 정정 + 광범위 회귀 sweep + 작업지시자 시각 판정 ★ 통과 + 이슈 본문 정오표 코멘트 등록 (#issuecomment-4389951401). 회귀 위험성 영역 점검 — 관련 CLOSED 이슈 (#236 PageAreas 영역 공식 / #42 머리말 Picture 렌더링 / #36 머리말 표 셀 이미지 / #340 머리말 누출) 모두 회귀 위험 0. 본 정정이 #236 정정의 영역을 일관 활용 (정확성 강화). 관련 함수 (hit_test_in_header_footer_native, get_active_hf_info, find_section_for_page) 무수정. TS 측 호출처 단 2곳 (input-handler-mouse.ts L494 onMouseDown / L784 onDblClick) 모두 정정 후 동작 정확. 보조 메모 영역 (본 task 분리) — 그리드 모드 (zoom ≤ 0.5) 좌표 결함 + hwpctl_Action_Table 꼬리말 hit:false. 정정 전후 동일 (회귀 0) + 사용자 시각 검증 안 됨 + 한컴 호환 진단 필요 → 본 사이클 영역 밖, 등록 보류. 향후 사용자 시각 검증 또는 한컴 호환 비교로 결함 확정 시 별도 task 진입. 산출물: - mydocs/report/task_m100_595_report.md (최종 보고서) mydocs/orders/yyyymmdd.md 는 메인테이너 영역 (PR #558 패턴 정합) — 본 PR 에서 제외, 메인테이너 PR 처리 후속에서 작성. 본 task 단계별 commit: - Stage 1 (54c0af2): 본질 진단 + 재현 단위 테스트 + 광범위 sweep - Stage 2 (0d20917): hit_test_header_footer 영역 정정 + 회귀 sweep - Stage 3 (본 commit): 최종 보고서 + 회귀 위험성 점검 closes #595 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

johndoekim and others added 5 commits May 3, 2026 23:51

edwardkim added the enhancement New feature or request label May 4, 2026

edwardkim added this to the v1.0.0 milestone May 4, 2026

edwardkim added a commit that referenced this pull request May 4, 2026

Merge local/devel: PR #558 cherry-pick (npm/editor RPC + Wrapper expo…

4ae9be3

…rtHwpx/exportHwpVerify 노출 — @johndoekim 5 commits + main.ts 옵션 C 통합)

edwardkim closed this May 4, 2026

edwardkim mentioned this pull request May 4, 2026

npm/editor RPC + Wrapper에 exportHwpx / exportHwpVerify 노출 (#407 후속) #557

Closed

edwardkim added a commit that referenced this pull request May 4, 2026

Merge local/devel: PR #558 처리 후속 보고서 + 오늘할일

5152ac7

johndoekim deleted the feature/issue-557-expose-hwpx branch May 4, 2026 10:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

npm/editor RPC + Wrapper에 exportHwpx / exportHwpVerify 노출 (#557, followup #407)#558

npm/editor RPC + Wrapper에 exportHwpx / exportHwpVerify 노출 (#557, followup #407)#558
johndoekim wants to merge 5 commits into
edwardkim:develfrom
johndoekim:feature/issue-557-expose-hwpx

johndoekim commented May 3, 2026

Uh oh!

edwardkim commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

johndoekim commented May 3, 2026

Summary

변경 (6 file, +168 라인)

단계별 커밋 흐름

검증

영역 검토 (#272 와의 관계)

6 레이어 정합 매트릭스

Test plan

후속 제안 (별도 이슈 권장)

Uh oh!

edwardkim commented May 4, 2026

통합 결과

본질 평가 — 정합

Stage 1 충돌 — 옵션 C 통합 안내

결정적 검증

다음 PR 시 권장 사항

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants