Skip to content

Task #1197: HWPX 용지 기준 BehindText 그림/표 z-order 보존#1252

Merged
edwardkim merged 11 commits into
edwardkim:develfrom
postmelee:local/task1197
Jun 2, 2026
Merged

Task #1197: HWPX 용지 기준 BehindText 그림/표 z-order 보존#1252
edwardkim merged 11 commits into
edwardkim:develfrom
postmelee:local/task1197

Conversation

@postmelee

@postmelee postmelee commented Jun 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

요약

HWPX 용지/페이지 기준 BehindText 그림·표·도형의 z-order가 타입별 렌더 경로에서 분리되어 보존되지 않던 문제를 수정합니다.

  • Picture/Table/Shape top-level render node가 공통 layer metadata(textWrap, zOrder, stableIndex)를 보존하도록 했습니다.
  • SVG, PaintOp replay, CanvasKit/native Skia/WebCanvas가 같은 layer 계약으로 plane과 z-order를 판단하도록 연결했습니다.
  • rhwp-studio Canvas2D 경로에서 pageBackground -> behindText -> flow -> inFrontOfText 순서로 filtered canvas layer를 합성하도록 보정했습니다.
  • Studio overlay canvas가 공통 CSS의 흰 배경을 상속해 하위 layer를 덮지 않도록 투명 배경을 명시했습니다.
  • HWPX: 용지 기준 BehindText 그림/표의 z-order가 보존되지 않아 텍스트가 겹침 #1197 synthetic z-order 테스트와 Studio layer 합성 회귀 검사를 추가했습니다.

문제

HWPX 문서에서 용지 기준으로 배치된 BehindText 객체가 그림/표/도형 타입별 경로로 렌더되면서 같은 z-order 축에서 합성되지 않았습니다.

그 결과 낮은 z-order 표 텍스트가 전체 페이지 이미지 위에 다시 표시되거나, InFrontOfText 도형과 BehindText 배경 이미지의 상대 순서가 Studio 화면에서 깨질 수 있었습니다.

원인

Rust 렌더 경로에서는 Picture/Table/Shape가 각각 다른 RenderNode와 PaintOp 경로를 거치면서 공통 layer metadata가 충분히 전달되지 않았습니다.

추가로 rhwp-studio Canvas2D 소비자에서는 layer 분리 후에도 overlay canvas가 다음 CSS를 상속했습니다.

#scroll-content canvas {
  background: var(--color-surface);
}

이 때문에 z-index가 가장 높은 front canvas가 흰 배경을 갖게 되었고, 실제로는 01만 그리는 front layer가 아래의 page background/behind/flow layer 전체를 덮어 버렸습니다.

변경 내용

영역 내용
src/renderer/render_tree.rs / layout.rs 용지/페이지 기준 Picture/Table/Shape top-level node에 layer metadata 부여
src/renderer/svg.rs RenderNode.layer를 우선 사용해 plane/z-order 정렬
src/paint/* LayerNode.layer 보존 및 inherited layer 기준 PaintOp replay plane 판정
src/renderer/web_canvas.rs / src/wasm_api.rs filtered render에 background plane 추가
rhwp-studio/src/view/page-renderer.ts background/behind/front filtered canvas layer 합성 및 overlay canvas 투명 배경 고정
rhwp-studio/src/view/canvaskit/* TypeScript CanvasKit replay도 LayerNode.layer metadata를 상속해 non-image PaintOp plane 판정
tests/issue_1197_svg_object_zorder.rs #1197 z-order 회귀 테스트 추가
rhwp-studio/tests/render-backend.test.ts Studio layer 합성 회귀 검사 추가

샘플 파일

저작권 사용 가능 여부는 작업지시자가 확인했습니다.

  • samples/hwpx/[2027] 온새미로 1 본교재.hwpx
  • samples/hwpx/hancom-hwp/[2027] 온새미로 1 본교재.hwp
  • pdf-large/hwpx/[2027] 온새미로 1 본교재.pdf

시각 검증

작업지시자가 rhwp-studio dev server에서 원본 샘플을 로드해 확인했습니다.

확인된 내용:

  • 중앙 배경 이미지 표시
  • 01 전면 layer가 배경 위에 표시
  • 하단 1주차 및 설명 텍스트 표시
  • 기존의 “흰 페이지 위에 01만 보이는” 증상 해소
Before After PDF
image image image

검증

PR 생성 전 최신 upstream/devel 기준으로 rebase한 뒤 다음 명령을 확인했습니다.

  • cargo fmt --all -- --check
  • cargo test
  • cargo clippy -- -D warnings
  • npm test (rhwp-studio/)
  • npm run build (rhwp-studio/)
  • git diff --check

추가로 작업 중 다음 타깃 검증도 수행했습니다.

  • cargo test --test issue_1197_svg_object_zorder -- --nocapture
  • cargo test --test issue_1167_svg_behindtext_zorder -- --nocapture
  • cargo test --lib replay_order
  • wasm-pack build --target web

샘플 파일 추가 후 다음 파일 로드도 확인했습니다.

  • cargo run --bin rhwp -- info 'samples/hwpx/[2027] 온새미로 1 본교재.hwpx'
  • cargo run --bin rhwp -- info 'samples/hwpx/hancom-hwp/[2027] 온새미로 1 본교재.hwp'
  • pdf-large/hwpx/[2027] 온새미로 1 본교재.pdf 페이지 수 확인

참고

제공받은 정답 PDF는 46쪽이고, 현재 rhwp pagination은 대응 HWPX를 47쪽, 대응 HWP를 50쪽으로 계산합니다.

  • PDF 2쪽 MEMO ↔ rhwp 3쪽 MEMO
  • PDF 3쪽 01 / 1주차 ↔ rhwp 4쪽

이 page count 차이는 이번 z-order/layer 합성 수정과 별도인 pagination/partial table 후속 이슈로 분리했습니다.

관련 이슈

Related: #1197

@postmelee postmelee changed the title [codex] Fix HWPX behind-text object z-order rendering Task #1197: HWPX 용지 기준 BehindText 그림/표 z-order 보존 Jun 2, 2026
@edwardkim edwardkim self-requested a review June 2, 2026 14:11
@edwardkim edwardkim added the enhancement New feature or request label Jun 2, 2026
@edwardkim edwardkim added this to the v1.0.0 milestone Jun 2, 2026
@postmelee postmelee marked this pull request as ready for review June 2, 2026 14:28
@edwardkim edwardkim merged commit 2f38167 into edwardkim:devel Jun 2, 2026
@edwardkim

edwardkim commented Jun 2, 2026

Copy link
Copy Markdown
Owner

메인테이너 검증 및 반영 완료했습니다.

  • PR #1252를 local/devel 기준 검증 브랜치에서 병합했습니다.
  • mydocs/orders/20260602.md 충돌을 해소했습니다.
  • 웹 캔버스 시각 판정 통과를 확인했습니다.
  • SVG 시각 판정 중 발견된 바탕쪽(MasterPage) z-plane 문제를 추가 보완했습니다.
    • SVG 출력 순서: PageBackground -> MasterPage -> BehindText -> Flow -> InFrontOfText
    • 바탕쪽 전체 페이지 그림이 BehindText 최종 표를 다시 덮는 문제를 수정했습니다.
  • HWPX/HWP SVG 재판정 모두 통과했습니다.
  • devel에 push 완료했습니다: 3bd66137

검증:

git diff --check origin/devel..HEAD
cargo fmt --all --check
cargo test --test issue_1197_svg_object_zorder -- --nocapture
cargo test --test issue_1167_svg_behindtext_zorder -- --nocapture
cargo test --tests
cd rhwp-studio && npm test && npm run build
docker compose --env-file .env.docker run --rm wasm

기여 감사합니다. 이번 변경은 HWPX paper/page anchored Picture/Table/Shape의 공통 z-order contract를 잡는 데 큰 도움이 되었습니다.

@edwardkim edwardkim mentioned this pull request Jun 2, 2026
Closed
@postmelee postmelee deleted the local/task1197 branch June 3, 2026 03:20
@seo-rii seo-rii mentioned this pull request Jun 6, 2026
Open
59 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@edwardkim edwardkim Awaiting requested review from edwardkim

Assignees

@postmelee postmelee

Labels

enhancement New feature or request

Projects

None yet

Milestone

v1.0.0

Development

Successfully merging this pull request may close these issues.

2 participants

@postmelee @edwardkim