Task #352: dash 시퀀스 Justify 폭 부풀림 — leader-aware advance + elastic 분배

[planet6897]

배경

samples/exam_eng.hwp 5 페이지 32번 문항 빈칸 라인:

__________________________ of being 'stimulus-driven',

29개 ASCII 하이픈으로 구성된 빈칸이 PDF 대비 ~3.5 배 부풀어 후속 텍스트 'stimulus-driven', 의 마지막 콤마가 우측 단 경계를 넘어 잘림.

증상 (수정 전):

• dash advance: 12.11 px/dash (PDF: ~7.4 px)
• 29 dash 시퀀스 폭: 351 px (PDF: ~218 px)
• of being 시작 x: 953 (단 우측 끝, 잘림 발생)

근본 원인

1. HY신명조 폰트 메트릭의 ASCII 하이픈 폭

src/renderer/font_metrics_data.rs:3848 의 FONT_276_LATIN_0[13] (HY신명조 ASCII '-') 가 853/1024 em ≈ 0.83 em 으로 비정상적으로 넓음:

static FONT_276_LATIN_0: [u16; 95] = [341, 426, 426, 853, 640, 938, 853, 256,
512, 512, 512, 853, 298, 853, 298, ...
//                                ^ index 13 (0x2D '-') = 853

비교: 콤마(0x2C)=298, 마침표(0x2E)=298 — 일반 좁은 구두점 대비 dash 만 ~3 배 넓음.

2. Justify Branch A 의 공백 분배 부작용

29 dash × 12.11 px = 351 px 자연 폭으로 라인이 사용 가능 폭(408 px) 초과. Justify Branch A 가 음수 슬랙을 공백 압축으로 회수하려 하나 min-clamp(-2.55 px × 3 spaces) 로 제한되어 약 153 px 잘림 발생.

이슈 본문이 추정한 "Justify Branch B 가산" 가설(공백이 없는 라인의 글자 분배)은 틀림 — interior_spaces=3 이 정상 인식되어 Branch A 발동. 진짜 원인은 메트릭 자체.

3. Stage 2/3 좁은 advance 적용 후 발생한 2 차 회귀

dash advance 를 좁히자 라인에 양수 슬랙이 발생, Branch A 가 슬랙을 공백에 균등 분배하면서 단어 사이 공백이 자연 폭의 2~3 배로 팽창 (작업지시자 피드백 "Q32 이후 폭이 2배"). Stage 5 에서 PDF 의 elastic leader 동작 모방으로 해소.

4. PDF 의 dash 처리 방식 확인

pdftotext -bbox-layout -f 6 -l 6 samples/exam_eng.pdf 결과 PDF Q34 라인:

"34. Centralized, formal rules can"  (xMax=265.02 pt)
"."                                   (xMin=402.24 pt, 그 사이 137 pt)
─ 그 사이 영역의 단어 0개

dash 시퀀스가 단어로 추출되지 않는 것은 PDF 가 dash 를 path/line graphic 으로 직접 그렸다는 강한 증거. 우리 Stage 3 의 SVG <line> 대체 전략이 PDF 와 동일.

PDF dash advance 가변성 측정:

라인	dash 수	영역 폭	per dash	em
Q32	29	218 px	7.49 px	0.49
Q34	40	183 px	4.57 px	0.30

→ PDF 는 dash leader 를 라인 슬랙에 따라 가변 폭으로 elastic 하게 채움.

변경

Stage 1 — 원인 확정 (428b01d)

paragraph_layout.rs:996 와 text_measurement.rs:209 에 임시 eprintln! (RHWP_DEBUG_352 환경변수 게이트) 삽입하여 다음 확인:

• Q32 라인 코드포인트 = [45 × 29, 32, "of being…"] (ASCII U+002D 29 개)
• interior_spaces=3 ≠ 0 → Branch A 발동 (Branch B 아님)
• text_w=561.00, avail=408.21 → 자연 폭 단계에서 153 px 초과
• HY신명조 dash embedded=Some(12.747) (= 0.833 em)

문서: mydocs/troubleshootings/issue_352_root_cause.md + Stage 1 보고서.

Stage 2 — leader-aware 좁은 advance (69e420b)

src/renderer/layout/text_measurement.rs:

fn is_dash_leader_run(chars: &[char], i: usize) -> bool {
    if chars[i] != '-' { return false; }
    // i 좌·우로 같은 dash 가 연속한 길이 카운트, ≥3 이면 true
}

세 char_width 클로저 (estimate_text_width, compute_char_positions, estimate_text_width_unrounded) 에 적용:

let base_w = if is_dash_leader_run(&chars, i) {
    base_w_raw.min(font_size * 0.3)  // 0.3 em 으로 강제 좁힘
} else {
    base_w_raw
};

≥ 3 연속 조건 덕분에 단발 dash(예: "stimulus-driven", "32.-") 영향 없음.

Stage 3 — dash run 시각 라인 통합 (2248752)

src/renderer/svg.rs (line 1882~) + src/renderer/web_canvas.rs (line 1284~):

is_middle_dot 패턴(svg.rs:1924) 모방하여 ≥ 3 연속 dash 클러스터를 감지, 글리프 <text> 출력 스킵 + 단일 <line> 으로 통합 렌더 (underline 부재 시).

// dash leader run 감지 (cluster 인덱스 기준)
let dash_run_groups: Vec<(usize, usize)> = ...;
let suppress_dash_leader_line = !matches!(style.underline, UnderlineType::None);

for (cluster_idx, ...) in clusters.iter().enumerate() {
    if let Some((x1_rel, x2_rel)) = cluster_in_dash_run(cluster_idx) {
        if x1_rel.is_finite() && !suppress_dash_leader_line {
            // 첫 cluster 위치에서 단일 <line> 출력
        }
        continue; // 글리프 출력 스킵
    }
    ...
}

dash 글리프 자체 폭(scale 0.95 후 ~5.4 px) 이 advance(~4.4 px) 를 넘어 시각상 겹치는 문제도 동시 해결.

Stage 4 — 폭 미세 보정 (7f45fc0 + 037cba6)

작업지시자 피드백 ("폭이 조금 짧음 / 1.5 정도") 반영하여 PDF 직접 실측. 0.3 em (134.94 px) → 0.5 em (210.85 px) 로 조정. PDF 218 px 의 96.7% 일치.

Stage 5 — dash leader elastic Justify 분배 (6926c4b)

작업지시자 피드백 ("Q32 이후 폭이 2배 커짐") 의 진짜 원인 (단어 공백 팽창) 해결.

src/renderer/mod.rs — TextStyle 신규 필드:

/// Task #352: dash leader 글자당 추가 간격 (px). PDF elastic leader 모방.
pub extra_dash_advance: f64,

src/renderer/layout/text_measurement.rs — 세 char_width 클로저 갱신:

let is_leader = is_dash_leader_run(&chars, i);
let base_w = if is_leader { base_w_raw.min(font_size * 0.3) } else { base_w_raw };
let mut w = base_w * ratio + style.letter_spacing + style.extra_char_spacing;
if c == ' ' { w += style.extra_word_spacing; }
if is_leader { w += style.extra_dash_advance; }  // ← 추가

(Stage 4 의 0.5 em 은 0.3 em 좁은 base 로 회수, elastic extra 로 PDF 수준 폭 도달)

src/renderer/layout/paragraph_layout.rs Justify 분기:

let count_dash_leaders = |chars: &[char]| -> usize { ... };

let (extra_word_sp, extra_char_sp, extra_dash_sp) = if needs_justify {
    ...
    let leader_dashes = count_dash_leaders(&all_chars[..visible_count]);
    if interior_spaces > 0 {
        let slack = available_width - effective_used;
        if leader_dashes > 0 && slack > 0.0 {
            // dash 가 슬랙 흡수, 공백 자연 폭 유지
            (0.0, 0.0, slack / leader_dashes as f64)
        } else {
            // 기존: 공백 분배 또는 압축
            ...
        }
    } else if total_char_count > 1 {
        // 공백 없는 라인 (CJK 등) 도 leader_dashes 우선
        ...
    }
};

text_style.extra_dash_advance = extra_dash_sp;  // run 별 적용

세 분기 (Branch A, Branch B, Distribute, overflow, cell underflow) 의 반환 튜플을 (extra_word_sp, extra_char_sp, extra_dash_sp) 3-tuple 로 확장.

검증

Q32 측정 (s0 p221 L6, 5 페이지)

항목	v0 (수정 전)	v1 (Stage 2)	v2 (Stage 3)	v3 (Stage 4)	v4 (Stage 5)	PDF 목표
dash advance	12.11 px	4.36 px	4.36 px	7.27 px	7.06 px	~7.4 px
29 dash 폭	351 px	126 px	126 px	211 px	204.7 px	~218 px
dash 글리프	29 개	29 개	0 개 (라인 대체)	0 개	0 개	0 개 (PDF 도 graphic)
, 우측 잘림	발생	해소	해소	해소	해소	정상

p6 Q33 라인 단어 공백 회복 (Stage 5 핵심 회귀 해소)

y=414 의 "to be free, then" 13 글자 폭:

단계	폭	비고
Baseline (devel)	83.6 px	자연 폭 압축 (Branch A min-clamp)
Stage 3 (0.5 em)	125.7 px	공백 +14~24 px 팽창 (사용자 컴플레인)
Stage 5 (elastic)	95.6 px	자연 폭 (압축만 해제) ✓

Stage 3 의 공백 폭증이 완전히 해소되고, 베이스라인 대비 +12 px 차이는 압축 해제 결과 (자연 폭 회복).

Stage 5 디버그 로그 (Q32)

[#352-S5] s0p221 L6 leader_dashes=29 interior_sp=3 text_w=337.00
          effective_used=330.00 avail=408.21 slack=78.21 per_dash_extra=2.697

각 dash advance = 0.3 em × 0.95 + 2.70 = 4.36 + 2.70 = 7.06 px ✓
29 dashes 폭 = 29 × 7.06 = 204.7 px ✓ (SVG underline x1=597.12, x2=801.84)

cargo test --release

전 테스트 스위트 100% 통과:

• lib: 1023 passed, 0 failed, 1 ignored
• svg_snapshot: 6 passed
• tab_cross_run: 1 passed
• 기타 통합 50+ passed

영향 범위 점검

문서 전체 dash 통계 (Stage 1 측정): HY신명조 dash 1017 개, Times New Roman 295 개. is_dash_leader_run 의 ≥ 3 조건 덕분에 단발 dash 미영향:

샘플	dash 글리프 (수정 후)	비고
exam_eng	366	단발 dash 보존
exam_kor	440	정상
exam_math_8	1	정상
aift	460	정상
biz_plan	13	정상

비포함 / 백로그

• HWP cs (line_seg.cs) 필드 활용 — 별 이슈 (현재 미사용 확인)
• – (U+2013), — (U+2014) leader 처리 — 본 이슈 범위 외, 필요시 is_dash_leader_run 에 추가 가능
• _____ underscore leader 일반화 — 우선순위 낮음
• font_metrics_data 의 HY신명조 dash 메트릭 자체 보강 — TTF 실제값 검증 필요, 현 leader-aware 우회로 충분

커밋 목록

6926c4b Task #352 Stage 5: dash leader elastic Justify 분배 (PDF 모방)
037cba6 Task #352 폭 보정: 0.32 em → 0.5 em (PDF 실측 반영)
7f45fc0 Task #352 Stage 4: 최종 결과 보고서 + orders 갱신
2248752 Task #352 Stage 3: dash run 시각 라인 통합 (underline 일치)
69e420b Task #352 Stage 2: dash advance 자연 폭 보정 (leader-aware)
428b01d Task #352 Stage 1: 원인 확정 (HY신명조 dash 메트릭 853/1024 em)

closes #352

[edwardkim]

완료. `devel` 에 Task #352 핵심 7 commits 만 분리 cherry-pick 으로 머지됨 (commit `8daf988`).

이슈 #352 자동 close 됩니다 (PR 본문 `closes #352` 명시).

머지 commit (작성자 attribution 보존)

• `c0a5592` (cherry-pick) — Stage 1: 원인 확정 (HY신명조 dash 메트릭 853/1024 em)
• `61db5d6` (cherry-pick) — Stage 2: dash advance 자연 폭 보정 (leader-aware)
• `5b473f1` (cherry-pick) — Stage 3: dash run 시각 라인 통합 (underline 일치)
• `a515cd9` (cherry-pick) — Stage 4: 최종 결과 보고서 + orders 갱신
• `e77beae` (cherry-pick) — 폭 보정 0.32 em → 0.5 em (PDF 실측)
• `363b7bb` (cherry-pick) — Stage 5: dash leader elastic Justify 분배 (PDF 모방)
• `368849b` (cherry-pick) — WASM 측정 경로 dash leader 패치

분리 cherry-pick 정황

본 PR 의 40 commits 가 다른 OPEN PR 들 (#401, #406, #408, #410, #414) 의 변경분 누적 형태였습니다. 본 task #352 와 직접 관련된 7 commits 만 분리하여 cherry-pick 한 이유:

• PR Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 의 `samples/synam-001.hwp` 회귀 정황 — 작성자 재정정 대기 상태인 회귀가 본 PR 전체 머지 시 함께 도입됨
• 다른 OPEN PR 들은 자체 PR 흐름대로 처리하는 것이 검토 / 회귀 추적 측면에서 적합

확인 결과: cherry-pick 후 `samples/synam-001.hwp` 5 페이지 회귀 정황 발생 안 함 (rows=0..5 정상 유지, 35 페이지 유지).

검증

• `cargo test --lib`: 1037 passed (1031 → +6 신규 Task exam_eng.hwp p5 Q32: dash 시퀀스의 Justify 폭 부풀림 #352 테스트)
• `cargo test --test svg_snapshot`: 6/6 passed
• `cargo test --test issue_418`: 1/1 passed (Task samples/hwpspec.hwp 20 페이지 이미지 이중 출력 (PR 처리 후 회귀) #418 보존)
• `cargo clippy --lib -- -D warnings`: warning 0건
• WASM 빌드 (Docker): 4,117,073 bytes
• 작업지시자 시각 판정 통과 (exam_eng.hwp Q32 dash 시퀀스 처리 정상)

평가

5 단계 진단 (폰트 메트릭 → Justify 분배 → 시각 라인 통합 → PDF 측정 보정 → elastic 분배) + WASM 경로 동기화 모두 양호합니다. Q32 dash advance 12.11 → 7.06 px (PDF ~7.4 px 근접), 29 dash 폭 351 → 204.7 px (PDF ~218 px) 의 정량 결과도 정확합니다.

특히 Stage 3 의 공백 팽창 사용자 컴플레인을 Stage 5 의 elastic 분배로 정정하신 점 — Justify Branch 7 분기에 `extra_dash_advance` 일관 적용 — 이 깊이 있는 정정이었습니다.

다른 OPEN PR 안내

본 PR 에 누적된 다른 task 들의 PR 흐름:

• Task #398: 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 #401 (Task 표 페이지 분할 시 rowspan>1 셀이 분할 단위 산정에서 누락 (2025년 기부·답례품 보고서 양식 1쪽 하단) #398): synam-001.hwp 회귀 정황으로 작성자 재정정 요청 상태
• fix: 동일 문단 내 두 번째 line의 inline 그림이 첫 line과 겹침 (#402) #406 (Task 동일 문단 내 두 번째 line의 inline 그림이 첫 line과 겹침 (페이지 분할 누락) #402 inline 그림 line 겹침), Task #402 inline TAC 그림 페이지네이션 + #404 heading-orphan 보정 #408 (Task 동일 문단 내 두 번째 line의 inline 그림이 첫 line과 겹침 (페이지 분할 누락) #402+헤딩 문단이 후속 콘텐츠와 다른 페이지로 분리됨 (orphan heading) #404 합산): OPEN, BEHIND
• Task #409: TopAndBottom Picture vert=Para 레이아웃/페이지네이션 chart 높이 일관화 + atomic TAC top-fit #410 (Task 21페이지 2x1 표 위치 오류: TopAndBottom Picture 다음 문단에서 vpos 보정이 차트 높이를 이중 반영 #409 TopAndBottom Picture chart 높이): OPEN, BEHIND
• Fix #412: 다단 우측 단 단행 문단 줄간격 누락 (vpos 보정 anchor 도입) #414 (Fix 다단 우측 단 단행 문단 줄간격 누락: vpos 보정 공식의 base 차감 무력화 #412): base=main → devel 정정 필요

향후 다른 PR 작업 시 본 PR 처럼 누적되지 않도록, devel 에서 직접 분기하는 것이 검토 / 충돌 측면에서 깔끔합니다.

좋은 기여 감사합니다.