Skip to content

Task #363: native PageRenderTree bridge API#385

Closed
postmelee wants to merge 5 commits into
edwardkim:develfrom
postmelee:feature/issue-363-native-render-tree-api
Closed

Task #363: native PageRenderTree bridge API#385
postmelee wants to merge 5 commits into
edwardkim:develfrom
postmelee:feature/issue-363-native-render-tree-api

Conversation

@postmelee

@postmelee postmelee commented Apr 27, 2026

Copy link
Copy Markdown
Collaborator

요약

  • DocumentCore::build_page_render_tree(page_num) public API를 추가했습니다.
  • DocumentCore::get_bin_data(index) public API를 추가했습니다.
  • native bridge에서 PageRenderTree를 직렬화할 수 있도록 render tree 관련 타입에 serde::Serialize를 정리했습니다.
  • 이미지 bytes는 render tree JSON에 직접 넣지 않고 ImageNode.bin_data_id + get_bin_data(index)로 별도 조회하도록 문서화했습니다.

배경

Issue #363은 이미 존재하는 PageRenderTree 생성 경로를 native viewer/bridge에서 안정적으로 사용할 수 있도록 public API 경계를 정리하는 작업입니다.

기존 WASM getPageRenderTree(pageNum) 경로와 SVG/HTML/Canvas 렌더링 경로는 유지하고, Rust core 사용자용 public API만 추가했습니다.

주요 변경

  • src/document_core/queries/rendering.rs
    • build_page_render_tree(page_num) 추가
    • get_bin_data(index) 추가
    • public API 단위 테스트 2개 추가
  • src/renderer/*, src/model/*
    • render tree 직렬화에 필요한 최소 Serialize derive 추가
    • ImageNode.data, PageBackgroundImage.data는 #[serde(skip)]
  • mydocs/manual/native_render_tree_bridge_api.md
    • native bridge API 사용법과 인덱스 기준 문서화
  • mydocs/tech/hwp_spec_errata.md
    • ImageNode.bin_data_id와 get_bin_data(index) 기준 보강

인덱스 기준

  • ImageNode.bin_data_id: 1-based 참조값
  • DocumentCore::get_bin_data(index): 0-based bin_data_content 배열 인덱스
  • render tree 이미지 노드에서 bytes 조회 시 일반적으로:
document.get_bin_data((image_node.bin_data_id - 1) as usize)

검증

  • cargo build
  • cargo test

결과:

  • lib tests: 1010 passed, 1 ignored
  • integration tests: hwpx_roundtrip_integration 14 passed, hwpx_to_hwp_adapter 25 passed, issue_301 1 passed, svg_snapshot 6 passed, tab_cross_run 1 passed
  • doctest: 0 tests

기존 테스트 경고 4건이 출력되었으나 이번 변경과 무관합니다.

@edwardkim

edwardkim commented Apr 27, 2026

Copy link
Copy Markdown
Owner

PR 검토했습니다.

먼저, 이번에 Firefox AMO 등록 (Task #338, PR #339) 작업해 주셔서 감사합니다. rhwp-firefox 가 정상적으로 스토어에 등록되는 데 큰 도움이 되었습니다.

본 PR (Task #363) 의 변경은 기존 `build_page_tree` 를 감싸는 thin wrapper 형태로 회귀 위험이 낮고, alhangeul-macos 의 검증 commit 으로 사전 확인된 방향이 명확합니다. 다만 head 머지 전에 메인테이너 측 정책 검토 항목이 있어 의견 부탁드립니다:

  1. `PageRenderTree` public API 노출 안정성 — 본 타입이 native bridge 의 release contract 로 노출되면 향후 내부 구조 변경 시 호환성 부담이 발생합니다. 현재 v0.7.x 사이클의 페이지 레이아웃 정정 작업이 `PageRenderTree` 내부에 반영되는 빈도가 높아, 안정성 평가가 필요합니다.

  2. semver 영향 — public API 추가는 minor bump (v0.8.0) 후보입니다. 그러나 v0.7.x 의 페이지네이션 회귀 정정이 진행 중인 시점에서 minor bump 시기 결정도 함께 검토 필요합니다.

  3. native bridge 공식 지원 방향 — alhangeul-macos 외 다른 native viewer use case 도 고려할 가치가 있습니다. 본 API 가 일반적 native bridge 패턴인지, alhangeul-macos 1차 use case 인지에 따라 API 형태가 달라질 수 있습니다.

  4. `serde` 직접 의존성 추가 — 가벼운 표준 의존성이라 정책상 문제는 없어 보입니다.

상기 항목은 작업지시자 (메인테이너) 가 결정합니다. DRAFT 상태로 두신 의도와도 부합하니, 결정 결과를 본 댓글에 추가로 알려드리겠습니다.

상세 검토: `mydocs/pr/pr_385_review.md`

@edwardkim

edwardkim commented Apr 27, 2026

Copy link
Copy Markdown
Owner

정책 검토 결과 정상 머지로 진행합니다. 이전 댓글의 검토 항목 (PageRenderTree 안정성, semver, native bridge 방향, serde 의존성) 은 작업지시자가 진행 가능으로 판단했습니다.

DRAFT 상태이신 PR 을 cherry-pick 방식으로 devel 에 머지하겠습니다 (작성자 attribution 보존). 머지 완료 후 본 PR 은 close 됩니다.

검증 + 머지 진행 후 결과 회신드리겠습니다.

edwardkim added a commit that referenced this pull request Apr 27, 2026
@edwardkim @claude
docs(pr): PR #385 처리 — 정상 머지 (cherry-pick) (@postmelee)
9e0ea1d 
PR #385 (Task #363): DocumentCore::build_page_render_tree + get_bin_data
public API + Serialize derive. native bridge (alhangeul-macos) use case 지원.

cherry-pick 으로 작성자 attribution 보존 (4 commit). orders 수동 통합.
검증: 1014 → 1016 passed (+2 신규 테스트), svg_snapshot 6/6, clippy /
wasm32 check 통과.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
edwardkim added a commit that referenced this pull request Apr 27, 2026
@edwardkim @claude
Merge local/pr385: PR #385 native PageRenderTree bridge API (@postmelee)
e91ecea 
DocumentCore 에 build_page_render_tree + get_bin_data public API 추가.
Serialize derive 로 native bridge JSON 직렬화 지원.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@edwardkim

edwardkim commented Apr 27, 2026

Copy link
Copy Markdown
Owner

cherry-pick 으로 devel 에 머지 완료했습니다 (작성자 attribution 보존, 4 commit).

먼저, 이번에 Firefox AMO 등록 (Task #338, PR #339) 작업해 주셔서 감사합니다. rhwp-firefox 가 정상적으로 스토어에 등록되는 데 큰 도움이 되었습니다.

검증:

  • cargo test --lib: 1014 → 1016 passed (+2 신규 테스트: build_page_render_tree, get_bin_data)
  • cargo test --test svg_snapshot: 6/6
  • cargo test --test page_number_propagation: 2/2
  • cargo clippy / wasm32 check: 통과

`PageRenderTree` 의 native bridge API 가 release contract 로 노출되었습니다. alhangeul-macos 의 use case 검증 결과 반영 부탁드립니다.

상세: `mydocs/pr/pr_385_report.md`
감사합니다.

@edwardkim

edwardkim commented Apr 27, 2026

Copy link
Copy Markdown
Owner

cherry-pick 으로 devel 에 머지 완료.

@edwardkim edwardkim closed this Apr 27, 2026
This was referenced Apr 27, 2026
Closed
Closed
Closed
Closed
edwardkim added a commit that referenced this pull request Apr 27, 2026
@edwardkim @claude
docs: 이슈 #364 검토 (PageLayerTree API 제안, PR 권유)
9c51252 
- 작성자: @postmelee (#363 후속 — PR #385 흡수 후 자연스러운 단계)
- 수락 + CONTRIBUTING.md 절차 안내. 6개 점검/합의 항목 (schema 정리, schemaVersion 정책, 변환 정확성, PR 범위 좁히기, surface 우선순위, 회귀 테스트) 댓글
- enhancement 라벨 추가, 이슈 OPEN 유지 (PR 대기)
- mydocs/feedback/issue_364_pagelayertree_review.md 추가
- mydocs/orders/20260426.md 갱신

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@postmelee postmelee mentioned this pull request Apr 28, 2026
Closed
@postmelee

postmelee commented Apr 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

@edwardkim 안녕하세요.
alhangeul-macos 쪽 use case 검증 결과 공유드립니다.

  • rhwp pin을 PR Task #363: native PageRenderTree bridge API #385 merge commit e91ecea 기준으로 갱신했습니다.
  • RustBridge C ABI symbol set은 기존과 동일하며, rhwp-core.lock artifact verify도 통과했습니다.
  • HostApp Debug build와 기본 render smoke(KTX/request/exam_kor) 모두 통과했습니다.
  • 이미지 포함 샘플(hwp-img-001, pic-in-head-02, pic-in-table-01, tac-img-02)에서 render tree의 bin_data_id를 통해 rhwp_image_data를 조회하는 경로가 정상 동작함을 확인했습니다.
  • 현재 release package 산출물을 설치본으로 교체한 뒤 Finder thumbnail과 Quick Look preview를 직접 확인했습니다. qlmanage thumbnail smoke도 KTX/request/KTX-003/exam_kor 및 이미지 포함 샘플에서 통과했습니다.
  • 최신 release v0.7.7은 build_page_render_tree가 없어 Stable release tag 전환은 아직 보류했고, alhangeul-macos에서는 이번 검증 범위를 Demo/Preview commit pin으로 유지했습니다.

상세내용

This was referenced Apr 29, 2026
Closed
Closed
Closed
@postmelee postmelee deleted the feature/issue-363-native-render-tree-api branch May 2, 2026 07:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@postmelee @edwardkim