feat: rhwpDev 디버깅 툴킷 — showAllIds / search / findNearest (closes #449) by oksure · Pull Request #602 · edwardkim/rhwp

oksure · 2026-05-05T03:48:33Z

목적

서드파티 애플리케이션에서 rhwp 렌더링 뷰어와 연동 시, AI가 제공한 activeId 가 DOM에 없거나 찾지 못하는 매핑 실패 이슈 디버깅 지원.

구현 내용

window.rhwpDev 전역 객체 (모든 모드에서 활성):

메서드	설명
`showAllIds(page?)`	렌더링된 페이지에 문단 ID (s{섹션}:pi={인덱스}) 오버레이
`hideAllIds()`	오버레이 제거
`search(text)`	텍스트 → section/paragraph/charOffset/page 역추적
`findNearest(id, page?)`	유효하지 않은 ID에 가장 가까운 유효 ID 제안
`help()`	콘솔 사용법 안내

사용 예시

// 콘솔에서:
rhwpDev.showAllIds()        // 모든 페이지 ID 표시
rhwpDev.showAllIds(2)       // 3페이지만

rhwpDev.search("기구 및 조직")  // → {section:0, paragraph:18, ...}

rhwpDev.findNearest(11, 0)  // ID 11이 없을 때 → 가장 가까운 ID 제안

파일 변경

rhwp-studio/src/core/rhwp-dev.ts — 신규 (디버깅 툴킷 모듈)
rhwp-studio/src/main.ts — initRhwpDev(wasm) 호출 추가

검증

npx tsc --noEmit: 기존 chrome 타입 에러 외 신규 에러 없음
WASM getPageTextLayout / searchText API 기반 구현

참고

이슈에서 제안된 3가지 기능 중 showAllIds (시각적 오버레이), search (텍스트 역추적), 스마트 에러 로깅 (findNearest) 를 모두 구현
getPageTextLayout 반환 형식에 따라 오버레이 정확도가 달라질 수 있음 — 피드백 후 조정 가능

이 방향이 적절한지 피드백 부탁드립니다.

서드파티 앱 연동 시 activeId 매핑 실패 디버깅을 위한 콘솔 API: - rhwpDev.showAllIds(page?) — 렌더링 영역에 pi 오버레이 표시 - rhwpDev.hideAllIds() — 오버레이 제거 - rhwpDev.search(text) — 텍스트 → section/para/offset 역추적 - rhwpDev.findNearest(id, page?) — 유효하지 않은 ID에 가장 가까운 ID 제안 - rhwpDev.help() — 사용법 안내 window.rhwpDev 로 전역 노출 (모든 모드).

Copilot

Pull request overview

This PR adds a global window.rhwpDev debugging toolkit to the rhwp-studio frontend so third-party integrators can inspect rendered paragraph IDs and troubleshoot activeId ↔ DOM mapping failures.

Changes:

Added a new rhwp-studio/src/core/rhwp-dev.ts module with showAllIds, hideAllIds, search, findNearest, and help.
Initialized the toolkit from rhwp-studio/src/main.ts using the existing WasmBridge instance.
Exposed the toolkit in all modes for integration/debugging workflows.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
rhwp-studio/src/main.ts	Wires the new debugging toolkit into app startup.
rhwp-studio/src/core/rhwp-dev.ts	Implements the global debugging helpers that consume WASM text/layout APIs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    showAllIds(pageNum?: number): void {
+      removeOverlay();
+      const container = createOverlayContainer();
+      const totalPages = wasm.getPageCount();


+        const pageEls = document.querySelectorAll(`[data-page="${p}"]`);
+        const pageEl = pageEls[0] as HTMLElement | undefined;
+        if (!pageEl) continue;


+        const offsetY = pageRect.top - scrollRect.top + getScrollContainer()!.scrollTop;
+
+        for (const run of data.runs) {
+          const label = `s${run.section ?? '?'}:pi=${run.para ?? '?'}`;


+      if (!result) {
+        console.warn(`[rhwpDev] search("${text}"): not found`);
+        return null;
+      }
+      const pos = result as any;


+      const out: SearchResult = {
+        section: pos.section ?? 0,
+        paragraph: pos.paragraph ?? 0,
+        charOffset: pos.charOffset ?? 0,
+        page: pos.page ?? 0,
+        x: pos.x ?? 0,
+        y: pos.y ?? 0,
+      };
+      console.log(`[rhwpDev] search("${text}"): s${out.section}:pi=${out.paragraph} offset=${out.charOffset} page=${out.page}`);


+    },
+
+    findNearest(targetId: number, pageNum?: number): { id: number; distance: number; text: string } | null {
+      const totalPages = wasm.getPageCount();


+
+      let nearest: { id: number; distance: number; text: string } | null = null;
+      for (const run of data.runs) {
+        const id = run.para as number;


+        const pageRect = pageEl.getBoundingClientRect();
+        const scrollRect = getScrollContainer()!.getBoundingClientRect();
+        const offsetX = pageRect.left - scrollRect.left + getScrollContainer()!.scrollLeft;
+        const offsetY = pageRect.top - scrollRect.top + getScrollContainer()!.scrollTop;
+


…ayout) - wasm.getPageCount() → wasm.pageCount (getter) - searchText 반환: { found: boolean, sec, para, charOffset, length } - getPageTextLayout 필드: secIdx/paraIdx/charStart (not section/para) - showAllIds: DOM 오버레이 대신 console.table (canvas 렌더러에 data-page 속성 부재) - findNearest: paraIdx 필드 사용 - 줌 스케일링 이슈 회피 (DOM 오버레이 제거로 해소)

oksure · 2026-05-05T03:58:56Z

Addressed all 8 review comments in 07139be:

wasm.getPageCount() → wasm.pageCount (getter)
searchText return check: result.found instead of null check
getPageTextLayout fields: secIdx/paraIdx/charStart
DOM overlay 제거 → console.table 기반 출력 (canvas 렌더러에 data-page 속성이 없어 DOM 오버레이 불가, 줌 스케일링 이슈도 회피)
findNearest 도 동일하게 paraIdx 필드 사용으로 수정

Canvas 위 시각적 오버레이가 필요하면 별도 overlay canvas layer를 CanvasView에 추가하는 방향으로 후속 구현 가능합니다.

@almet

v0.7.9 후속 patch 사이클 (5/4 ~ 5/6). ## 신규 기능 - **CLI 바이너리 릴리즈** (Issue #608/#612, @almet 의 요청) - 4 플랫폼 GitHub Release 자산 첨부 (Linux x86_64 / macOS x86_64+aarch64 / Windows x86_64) + SHA-256 체크섬 - **PNG raster backend** (PR #599, @seo-rii) — render P4 단계 - native Skia 기반 PageLayerTree → PNG export, native-skia feature gate - **AI 파이프라인 + VLM 연동 도입** (메인테이너 후속 정정): - --vlm-target claude (1568 longest edge / 1.15 MP, Claude Vision 정합) - --scale / --max-dimension (자동 scale 계산) - export-png CLI 명령 + 매뉴얼 (한글 + 영문 dual) - 한글 폰트 fallback chain + char 단위 fallback (공백 두부 정정) + --font-path 동적 로딩 ## 외부 PR cherry-pick (13 PR / 7 컨트리뷰터) - @planet6897 / Jaeook Ryu (협업): PR #587/#589/#561/#564/#570/#575/ #580/#584/#592/#593/#567 - @oksure (Hyunwoo Park): PR #600 (closes #513) - @seo-rii: PR #599 (refs #536) - @cskwork / @johndoekim / @nameofSEOKWONHONG / @jangster77 — 사이클 누적 ## 메인테이너 정정 Skia 폰트 영역 5개 정정 (한글 fallback / font-path / char-fallback / VLM 옵션 / export-png CLI). ## 인프라 - CI 빌드 안정성 (Cargo.toml [[example]] required-features) - 광범위 페이지네이션 회귀 sweep 도구 (164 fixture / 1,614 페이지 자동) ## 후속 이슈 - #613 (VLM 프리셋 확장) - #614 (DPI 메타데이터) - #615 (pua_oldhangul.rs U+F53A 한컴 정합) - #598 (rhwp-studio 각주 삭제, 외부 컨트리뷰터 공개) ## 잔여 PR (v0.7.11 후속 patch) PR #601, #602 (@oksure) / PR #607 (@dicebattle) / PR #609 (@jangster77, Task #604) / PR #611 (@kihyunnn). 상세: CHANGELOG.md (한글) / CHANGELOG_EN.md (영문).

Copilot AI review requested due to automatic review settings May 5, 2026 03:48

Copilot started reviewing on behalf of oksure May 5, 2026 03:49 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: rhwpDev 디버깅 툴킷 — showAllIds / search / findNearest (closes #449)#602

feat: rhwpDev 디버깅 툴킷 — showAllIds / search / findNearest (closes #449)#602
oksure wants to merge 2 commits intoedwardkim:develfrom
oksure:contrib/rhwpdev-toolkit

oksure commented May 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

oksure commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

oksure commented May 5, 2026

목적

구현 내용

사용 예시

파일 변경

검증

참고

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

oksure commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants