render: add native Skia PNG raster backend

[seo-rii]

변경 요약

이번 PR은 render P4 단계로, PageLayerTree를 native Skia로 replay해서 PNG를 만들 수 있는 첫 raster backend를 추가합니다.

P1에서 PageLayerTree 경계를 만들고, P2/P3에서 Canvas layer path와 diff 테스트를 붙였고, 이번에는 그 IR을 native backend에서도 실제로 replay할 수 있는지 확인하는 단계입니다.

주요 변경은 아래와 같습니다.

• LayerRasterRenderer, RasterRenderOptions, RasterRenderOutput 추가
• native-skia feature 추가
• native-only SkiaLayerRenderer 추가
• DocumentCore::render_page_png_native(page) 추가
• PageLayerTree 기반 PNG encode 경로 추가
• page background, clip/group, text/footnote marker, line/path/shape, image replay 처리
• image crop / tile / basic effect replay 처리
• invalid image, placeholder, raw-svg, equation, form object에 대한 fallback replay 처리
• raster size guard 추가
  • invalid page dimension reject
  • invalid scale / dpi reject
  • max dimension / max pixel count 제한
• CI에서 native Skia 테스트를 돌리도록 추가
• README / README_EN에 native Skia 경로와 비목표 정리

이 PR의 Skia 경로는 아직 완성형 renderer라기보다는 PageLayerTree가 native raster backend까지 갈 수 있는지 검증하는 초기 backend입니다. 그래서 기본 SVG/Canvas 출력은 그대로 두고, native feature를 켰을 때만 PNG export API를 사용할 수 있게 했습니다.

관련 이슈

refs #536

범위

이번 PR에 포함한 범위는 아래 정도입니다.

• native-only Skia PNG backend
• PageLayerTree replay 기반 raster output
• feature-gated native-skia
• 기본 이미지 replay
• raster 생성 안정성 guard
• native Skia unit/smoke test
• CI native Skia test step

비목표

아래는 일부러 이번 PR에 넣지 않았습니다.

• CanvasKit renderer
• browser/WASM public API 변경
• C ABI / CLI PNG export
• resource interning/cache
• complex text shaping parity
• 완전한 equation/raw-svg/form native replay
• Skia visual regression fixture pipeline

특히 equation/raw-svg/form은 이번 PR에서는 placeholder/fallback replay 수준입니다. 실제 native replay는 후속 PR에서 따로 보는 게 맞습니다.

테스트

• git diff --check upstream/devel...origin/render-p4
• cargo test
• cargo clippy -- -D warnings
• cargo check --target wasm32-unknown-unknown --lib
• cargo test --features native-skia skia --lib

SVG 샘플 내보내기와 웹 렌더링 확인은 이번 PR의 직접 범위가 아닙니다. P4는 native-only Skia PNG backend 추가이고, wasm 쪽은 cargo check --target wasm32-unknown-unknown --lib로 native Skia 의존성이 새지 않는지만 확인했습니다.

스크린샷

없음.

이번 PR은 UI 변경이 아니라 native PNG raster backend 추가입니다. 대신 Skia 테스트에서 PNG decode, pixel sampling, clip, image crop/tile/effect, placeholder fallback, raster option guard를 확인합니다.

[edwardkim]

@seo-rii Thanks for the P4 stage — native Skia PNG raster backend ✨

The 9 essential commits have been cherry-picked into devel (f7d5563). PR mergeable=MERGEABLE was true on the surface, but the PR base was 73 commits behind our devel HEAD (PR #571-style base skew). Single merge would have reverted this cycle's work, so we cherry-picked commit-by-commit instead — fortunately your Skia commits live entirely in new files (src/renderer/skia/ + layer_renderer.rs + image_conv.rs) with zero overlap against the cycle's other PRs, so cherry-pick was clean.

Merged

• ✅ 9 commits cherry-picked, author preserved as seorii <me@seorii.page>
• ✅ cargo test --features native-skia skia 20 passed
• ✅ cargo test --lib --release 1134 passed (regression 0)
• ✅ Docker WASM build 4,581,465 bytes (default build unchanged — native-skia feature gate verified)
• ✅ Wide pagination sweep: 164 fixtures / 1,614 pages / regression 0

Maintainer follow-up fixes (876d820)

To make the PNG backend usable for our environment (Korean exam fixtures), we added 5 follow-up areas on top of your cherry-picked branch. All within the same src/renderer/skia/renderer.rs and adjacent files — no conflict with your design. Sharing the diff so you can incorporate the patterns in future PRs:

1. Korean font fallback chain in draw_text

Your 4cf787f (use font fallback in native skia text) added ["DejaVu Sans", "Arial", "sans-serif"]. We extended with the Korean glyph-bearing chain:

families.extend([
    "Noto Sans KR", "Noto Serif KR", "Noto Sans CJK KR", "Noto Serif CJK KR",
    "Nanum Gothic", "Nanum Myeongjo",
    "Malgun Gothic", "맑은 고딕",
    "Batang", "바탕",
    "Apple SD Gothic Neo", "AppleMyungjo",
    "DejaVu Sans", "Arial", "sans-serif",
]);

This matches the SVG path's CSS font chain and prevents tofu (□) on Korean text when the primary face isn't installed.

2. --font-path dynamic font loading

Added SkiaLayerRenderer::with_font_paths(&[PathBuf]) that loads TTF/OTF/TTC files from user-specified directories into a custom_typefaces: HashMap<String, Typeface> cache, checked before font_mgr.match_family_style. Mirrors the SVG path's --font-path option for Hancom-specific fonts (HY견명조 etc.) that aren't in system fontconfig.

3. Per-character fallback (whitespace tofu fix)

The single canvas.draw_str(text, ...) call rendered NBSP (U+00A0), FIGURE SPACE (U+2007), ZERO WIDTH SPACE (U+200B) etc. as tofu when the primary typeface lacked those glyphs. Replaced with a per-char loop:

for ch in text.chars() {
    let codepoint = ch as i32;
    let primary_has = primary_typeface.as_ref()
        .map(|tf| tf.unichar_to_glyph(codepoint) != 0)
        .unwrap_or(false);
    if primary_has {
        // draw with primary
    } else {
        // try fallback chain; if none has the glyph, advance without drawing
    }
    cursor_x += chosen_font.measure_str(&s, Some(&paint)).0;
}

Whitespace-class codepoints with no glyph in any chain typeface get a default advance (≈ space width) without drawing a .notdef glyph.

4. VLM options for AI pipeline integration

Added PngExportOptions + VlmTarget::Claude (1568 longest edge / 1.15 MP) — auto-calculates scale from page dimensions while staying within both edge and pixel-count limits (with a 0.5% safety margin for ceil / float rounding). CLI surface:

rhwp export-png input.hwp --vlm-target claude
rhwp export-png input.hwp --max-dimension 1024
rhwp export-png input.hwp --scale 2.0

Tracking issue #613 for additional VLM presets (GPT-4V / Gemini / Qwen-VL / LLaVA).

5. export-png CLI command + manual

Wired up your DocumentCore::render_page_png_native (and the new _with_export_options variant) as a CLI command in src/main.rs, gated behind the native-skia feature so default builds are unaffected. Manuals at mydocs/manual/export_png_command.md and mydocs/eng/manual/export_png_command.md.

Tracking issue #614 for --dpi PNG pHYs metadata.

Notes for future P5+ stages

The non-goals from your PR body remain (full equation native replay, complex text shaping parity, CanvasKit, Skia visual regression fixture pipeline). The follow-up fixes above are the minimum to ship a usable PNG backend; the broader text-shaping work is a separate effort.

If you have thoughts on the unichar_to_glyph per-char fallback approach (vs. relying on Skia's make_text_blob shaping or harfbuzz integration), I'd love to hear them — happy to revisit if there's a more idiomatic skia-safe pattern.

Thanks again — the layered-tree → Skia replay design is clean and the feature gate kept the merge surgical.

[edwardkim]

영문 댓글로 답변드린 점 양해 부탁드립니다 — 본 프로젝트 컨트리뷰터 분들께는 한글로 답변드리는 것이 정합인데, 본 PR 의 본질 영역이 영문 코드/주석 중심이라 영문으로 작성했습니다. 한글로도 같이 정리해드립니다.

처리 결과

@seo-rii 님 P4 단계 (native Skia PNG raster backend) cherry-pick 완료되었습니다 (devel merge f7d5563).

Cherry-pick

• ✅ 본질 9 commits 모두 cherry-pick (충돌 0, author seo-rii 보존)
• ✅ PR mergeable=MERGEABLE 표시였으나 PR base 가 본 devel 보다 73 commits 뒤 (PR DIFF update #571 와 같은 base skew). 단순 머지 시 본 사이클 처리분 모두 revert 위험 — commit 단위 cherry-pick 으로 처리
• ✅ 본 PR 의 Skia 본질 영역이 신규 파일 (src/renderer/skia/ + layer_renderer.rs + image_conv.rs) 로 격리되어 있어 본 사이클 처리분과 0 중첩 → 깨끗한 cherry-pick 가능

결정적 검증

• cargo test --features native-skia skia 20 passed
• cargo test --lib --release 1134 passed (회귀 0)
• Docker WASM 4,581,465 bytes (PR fix: Square wrap 표 horz_rel_to=단 속성 정합 (closes #590) #593 baseline +0 — native-skia feature gate 정합 입증)
• 광범위 페이지네이션 sweep: 164 fixture / 1,614 페이지 / 회귀 0

메인테이너 후속 정정 (5개 영역, `876d820`)

PR #599 본질만으로는 본 환경 한컴 fixture 가 정상 표시되지 않아 5개 영역 추가 정정. 향후 PR 에서 같은 패턴 적용에 참고 부탁드립니다.

1. Skia 한글 폰트 fallback chain (`renderer.rs::draw_text`)

`4cf787f` (use font fallback in native skia text) 의 `["DejaVu Sans", "Arial", "sans-serif"]` chain 에 한글 폰트 추가 — Noto Sans KR / Noto Serif KR / Nanum Gothic / Nanum Myeongjo / Malgun Gothic / 맑은 고딕 / Batang / 바탕 / Apple SD Gothic Neo / AppleMyungjo 등.

→ SVG 의 CSS font chain 과 동일 패턴. CharShape.font_family (HY견명조 등) 가 시스템에 없을 때 한글 글리프 미보유 폰트로 fallback → 사각형(豆腐) 표시 결함 정정.

2. `--font-path` 동적 폰트 로딩 (`with_font_paths` API)

`SkiaLayerRenderer::with_font_paths(&[PathBuf])` 추가:

• `custom_typefaces: HashMap<String, Typeface>` 캐시 (사용자 지정 디렉토리의 모든 TTF/OTF/TTC 로드)
• `font_mgr.match_family_style` 보다 먼저 검색 (사용자 지정 우선)
• SVG 의 `--font-path` 와 동일 패턴 — 한컴 전용 폰트 (HY견명조 등) 가 시스템 fontconfig 에 없을 때 ttfs 디렉토리 직접 지정

3. char 단위 fallback (공백 두부 정정)

단일 `canvas.draw_str(text, ...)` 호출이 NBSP (U+00A0) / FIGURE SPACE (U+2007) / ZERO WIDTH SPACE (U+200B) 등을 두부로 표시. char 단위 loop 으로 변경 — primary typeface 가 글리프 미보유 (`unichar_to_glyph==0`) 시 chain 의 다른 typeface 시도, 모두 미보유 시 visible glyph 그리지 않고 일반 공백 너비로 advance.

4. VLM 옵션 (AI 파이프라인 + Vision-Language Model 연동)

`PngExportOptions` + `VlmTarget::Claude` 추가:

```bash
rhwp export-png input.hwp --vlm-target claude # 1568 longest edge / 1.15 MP
rhwp export-png input.hwp --max-dimension 1024 # 한 변 1024 (LLaVA-style)
rhwp export-png input.hwp --scale 2.0 # 직접 배율
```

자동 scale 계산 — max_dimension + max_pixels 결합 (둘 다 한도 안) + 0.5% 안전 마진 (ceil + 부동소수점 오차).

다른 VLM 프리셋 (GPT-4V / Gemini / Qwen-VL / LLaVA) 은 #613 후속 task.

5. `export-png` CLI 명령 + 매뉴얼

`src/main.rs::export_png` 추가 (native-skia feature gate, 기본 빌드 영향 0). 매뉴얼:

• `mydocs/manual/export_png_command.md` (한글)
• `mydocs/eng/manual/export_png_command.md` (영문)

`--dpi` PNG pHYs chunk 메타데이터는 #614 후속 task.

향후 P5+ 단계 참고

PR 본문 §"비목표" 영역 (complex text shaping parity / 완전한 equation native replay / CanvasKit / Skia visual regression fixture pipeline) 은 그대로 유지. 위 5개 영역은 본 환경 PNG backend 가 사용 가능한 수준으로 만들기 위한 최소 정합이며, 더 광범위한 text shaping (kerning / GSUB / GPOS) 작업은 별도 영역으로 정합.

`unichar_to_glyph` per-char fallback 방식이 Skia 의 `make_text_blob` shaping 또는 harfbuzz 통합과 비교해서 더 좋은 idiomatic 패턴이 있다면 알려주세요. 향후 다시 검토 가능합니다.

P3 (PR #498) → P4 (본 PR) 흐름의 일관성 + DTP 엔진 정체성 (`project_dtp_identity` — 다층 레이어 / WebGPU / 마스터 페이지 인프라 토대) 정합 우수했습니다. 감사합니다.