overlapAreaMap — 지표 ⑥ 신규 겹침 게이트 해부

0 · 30초 요약

• 무엇을 낸다 — 문서 하나의 Map<"idA|idB", 겹친면적px²>. leaf 쌍 전수 판정.
• 왜 별도 지표인가 — ④ 유휴 여백은 격자 union이라 union = Σ면적 − Σ겹침. 노드를 키우면서 겹치는 알고리즘에서는 면적 증가가 겹침 손실을 덮어 글자가 포개진 문서가 ④ 기준 「개선」으로 찍힌다.
• 판정은 절대량이 아니라 차분 — 컴포넌트에는 원래부터 의도적으로 겹친 장식이 흔하다. expected와 after를 같은 규칙으로 재고 area − baseArea > 100px²인 쌍만 신규로 센다.
• 실전 검증 — 6357697에서 center-text가 만든 텍스트 6쌍 겹침이 이 게이트에 걸렸다. 「중앙 정렬은 방향은 맞지만 겹침 제약 없이는 못 쓴다」는 첫 실험 결론이 이 함수에서 나왔다.

1 · 게이트 파이프라인 — 함수가 있는 자리

overlapAreaMap은 baseline 비교를 모른다. 문서 하나의 겹침 지도만 내놓는 자립 순수 함수이고, 차분은 소비자인 computeLayoutMetrics가 한다.

// metrics.ts · computeLayoutMetrics 내부 (646행~)
const overlapNow  = overlapAreaMap(doc, tight);
const overlapBase = expected ? overlapAreaMap(expected, expectedTight) : null;
for (const [key, area] of overlapNow) {
  const baseArea = overlapBase?.get(key) ?? 0;
  // 새로 겹친 쌍(baseArea = 0)뿐 아니라 **더 많이 겹치게 된 쌍**도 신규로 센다.
  if (overlapBase && area - baseArea > OVERLAP_EPS) {
    newOverlapPairs++;
    newOverlapArea += area - baseArea;
  }
}

2 · 2단계 알고리즘

1단계 — 판정 대상(items) 수집

문서의 노드를 한 번 순회하며 거른다. 살아남은 노드마다 판정 박스와 자기 컨테이너 id를 붙여 둔다.

2단계 — O(n²) 쌍 판정

for (let i = 0; i < items.length; i++) {
  for (let j = i + 1; j < items.length; j++) {
    if (isOwnContainer(a, b) || isOwnContainer(b, a)) continue;  // §3-③
    const area = intersectArea(a.box, b.box);
    if (area <= OVERLAP_EPS) continue;                           // §4 · 100px²
    if (isNested(a, b, area)) continue;                          // §3-⑤
    out.set(pairKey(a.id, b.id), area);                          // 사전순 결합 → 순서 무관
  }
}

pairKey(a,b)는 id를 사전순으로 붙인다(a<b ? "a|b" : "b|a") — 쌍에는 순서가 없으므로 같은 쌍이 두 키로 갈라지지 않게 하기 위함. 케이스 규모(leaf 수십 개)에서 O(n²)는 문제가 아니다.

3 · 제외 규칙 다섯 가지 — 「의도된 겹침」의 목록

이 함수의 정체성은 겹침을 세는 쪽이 아니라 무엇을 겹침으로 치지 않을지에 있다. 다섯 규칙은 전부 「디자이너가 일부러 포개 놓는 패턴」 하나씩에 대응한다.

4 · 상수와 그 값의 이유

판정 박스 — 왜 텍스트만 tight box인가

텍스트의 rendered bounding box는 오토핏 여백까지 포함해서, 글자가 실제로 닿지 않는데도 겹침으로 세는 오탐이 난다. 그래서 tight(= scripts/tight-box-cases.ts가 구워 둔 글리프 실측 박스, 프레임 원점 기준이라 절대 박스를 더해 변환)가 있으면 그걸 우선한다. 도형은 bbox가 곧 실체이므로 절대 박스 그대로.

// judgeBoxOf 의 3분 반환 — 호출 측이 셋을 구분해야 한다
tight 없음            → box        (rendered bbox로 잰다)
tight[id] 없음        → undefined  ("잴 수 없음" — 판정 제외)
tight[id].status≠ok   → null       (빈 텍스트 — 칠해진 게 없으니 제외)
tight[id].status=ok   → 절대좌표로 변환한 glyph extent

5 · 판정 시뮬레이터 — 규칙이 어느 순서로 무는가

도형(컨테이너 타입) 위에 텍스트가 있다. 텍스트를 아래로 끌어내리면 얹힘(⑤) → EPS 접촉 → 겹침 순으로 판정이 바뀐다. 「자기 컨테이너」 토글은 규칙 ③의 효과를 보여준다.

6 · 설계 결정 Q&A

7 · 알려진 구멍 · TODO

• TODO isNested 주석 원문 — "[TODO] 이 규칙이 일반적으로 사용될 수 있는지 확인 필요." 0.95라는 값과 「큰 쪽이 컨테이너 타입」 조건이 케이스 5건에서 맞춰진 것이라, 20건 확장 시 재검증 대상.
• 주의 ⑤ 얹힘 면제는 z-order를 안 본다. 기하로만 판정하므로 「작은 것이 큰 도형 뒤에 완전히 가려진」 병리적 케이스도 얹힘으로 면제된다. 실무에서는 드물다고 보고 수용.
• 주의 회전 노드 — 판정은 AABB(absBoxMap) 기준이다. 회전된 요소는 bbox가 실체보다 커서 과탐 가능. tight box가 있는 텍스트만 완화된다.
• 주의 DECORATION_TYPES는 쌍 전체를 면제한다 — 장식 위에 텍스트를 밀어 넣는 재배치 실수는 이 게이트가 못 잡는다. 의도된 트레이드오프 (상시 오탐 > 드문 미탐).
• 의존 ③은 findTextContainer·containerTypeShim의 정확성에 기대고 있다. shim이 빠지면(정식 반영 시) 컨테이너 판정이 바뀌어 ⑥의 면제 대상도 함께 바뀐다 — 회귀 테스트가 필요한 또 하나의 이유.

8 · W1 회귀 테스트 스펙 (제안)

전부 순수 함수 대상이라 sheetJson 최소 fixture로 만들 수 있다. 각 행이 제외 규칙 하나 또는 경계값 하나에 대응한다.

근거: src/post-replace-layout/relayoutCore/metrics.ts (overlapAreaMap 422행~ · computeLayoutMetrics 차분 646행~ · 상수 55~281행 · judgeBoxOf 111행~) · topology.ts의 상수 공유 · relayout-status-2026-08-18.md §1.4(지표 ⑥) · relayout-workspace.md(케이스 실측) · 커밋 47678d2f(배경판 상수 통합) 33cda32d(findContainer 통합). 데모의 판정 로직은 본문 규칙의 참조 재구현이며 실제 코드와 값(EPS 100 · RATIO 0.95)을 공유한다.