iframe 내 픽셀 단위 핀 주석 구현, Washi의 어댑터 아키텍처

Context

iframe의 DOM 격리로 인한 부모 페이지의 직접 조작 불가능. 내부 스크롤 및 요소 좌표가 부모 윈도우와 분리되어 주석 위치 이탈 발생. 동적 HTML 업데이트 시 실시간 좌표 재계산이 어려운 구조적 한계.

Technical Solution

• postMessage 기반의 Adapter Layer를 구축하여 Same-Origin Policy 제한을 우회하고 iframe 내부 DOM 쿼리 수행
• 부모 윈도우와 iframe 내부 좌표 간 오프셋을 계산하는 실시간 Transformation Matrix 적용으로 스크롤·리사이즈 시 핀 위치 고정
• MutationObserver를 활용해 iframe 내 DOM 변경 사항을 감지하고 주석 위치를 동적으로 재보정하는 반응형 업데이트 체계 설계
• 프레임워크 종속성을 제거한 어댑터 구조를 통해 React, Vue, Svelte 및 Vanilla HTML 환경 모두에서 호환 가능한 설계
• 중첩 iframe 구조 대응을 위해 계층별 변환 행렬을 누적 합산하는 좌표 매핑 알고리즘 구현

Key Takeaway

외부 환경을 블랙박스로 취급하고 추상화된 어댑터 층을 통해 통신함으로써, 격리된 런타임 환경에서도 정밀한 상태 동기화를 달성하는 설계 전략.