플랫폼 토폴로지
전달 체인
| 단계 | 소유자 | 검증 |
|---|---|---|
| 소스 및 패키지 빌드 | 프런트엔드 모듈 | 패키지 빌드가 예상한 엔트리 파일을 생성합니다. |
| 아티팩트 위치 | 배포 빌드 타깃 | 빌드 명령이 --outDir를 받습니다. Vite가 이를 하드코딩하지 않습니다. |
| Registry 엔트리 | 백엔드 모듈 | view.page 또는 view.component가 생성된 엔트리를 가리킵니다. |
| 서빙되는 URL | 파일시스템 및 HTTP Registry 엔트리 | 에셋을 직접 요청하면 빌드된 JavaScript 또는 HTML이 반환됩니다. |
| 런타임 컨테이너 | Web Host | 페이지는 about:srcdoc를 사용하고, 컴포넌트는 보통 shadow DOM을 갖는 커스텀 엘리먼트를 사용합니다. |
| 컨텍스트 | AppConfig 및 Wippy 패키지 | 라우팅, API 접근, 테마 데이터가 지원되는 패키지를 통해 전달됩니다. |
소스가 존재하거나, 빌드가 성공했거나, Registry 엔트리가 유효하다는 사실이 다음 단계를 보장하지는 않습니다. 각 경계를 개별적으로 검증하십시오.
페이지
view.page는 about:srcdoc iframe에서 실행됩니다. iframe URL은 호스트 라우트가 아닙니다. 호스트 상태를 알아내기 위해 window.location, window.parent.location, 쿼리 파라미터를 조사하지 마십시오. AppConfig와 @wippy-fe/router를 사용하십시오. 이 패키지가 Wippy 라우트 통합을 처리합니다.
iframe CSS 주입은 현재 기본 테마 스크롤바 스타일을 제공합니다. 이름은 역사적인 것이며 현재 용도보다 넓은 의미를 담고 있습니다. 스크롤바 일관성을 위해 활성 상태로 유지하되, 레이아웃 리셋으로 설명하지 마십시오.
웹 컴포넌트
view.component는 호스트 문서에서 실행되며 보통 자체 shadow root를 소유합니다. CSS 셀렉터는 shadow 경계를 넘어 캐스케이드되지 않습니다. Web Host는 컴포넌트 설정에 따라 승인된 스타일시트와 파사드 CSS를 해당 root로 전달할 수 있습니다.
CSS 변수 상속과 스타일시트 주입은 서로 다른 메커니즘입니다:
- 공개된 상속 변수는 호스트에서 shadow 경계를 넘을 수 있습니다.
- 셀렉터 규칙은 해당 shadow root로 전달될 때만 그 root에 영향을 줍니다.
- 전달된다는 사실이 임의의 셀렉터를 이식 가능한 API로 만들어 주지는 않습니다.
테마와 오버레이
파사드가 PrimeVue 테마를 제공합니다. 파사드 custom_css에 있는 공유 .p-* 규칙은 유효한 테마 구현이며, 호스트와 자식 모두를 대상으로 의도한 경우 전역일 수 있습니다. .wippy-host-app은 호스트 전용 크롬에만 사용하십시오.
테마 모드는 AppConfig 상태이며 CSS 클래스 API가 아닙니다. 애플리케이션, 컴포넌트,
픽스처, 브라우저 테스트는 @wippy-fe/proxy의
host.setThemeMode('auto' | 'light' | 'dark')로 모드를 전환한 다음 @theme을
기다리고 host.getThemeMode()로 확인합니다. AppConfig가 호스트에서 자식으로 가는
전송 경로를 통해 변경 사항을 전달합니다. 호스트는 자신의 문서를 갱신하고,
활성 about:srcdoc iframe에 AppConfig를 다시 브로드캐스트하며, 웹 컴포넌트
root에 모드를 미러링합니다. w-theme-dark나 w-theme-light 클래스를 직접
강제하지 마십시오.
w-theme-dark나 w-theme-light 클래스를 직접 강제하지 마십시오.
PrimeVue 오버레이는 teleport될 수 있습니다. 최상위 문서, iframe 문서, 재귀적으로 탐색한 shadow root에서 실제 오버레이 root를 확인하십시오. 일반적인 PrimeVue 배치를 가정하지 마십시오.
런타임 디버깅 순서
- 백엔드가 수신 대기 중인지 확인합니다.
- 예상치 못한 5xx 응답이 있는지 백엔드 로그를 조사합니다.
- Registry 소유자와 서빙되는 에셋 URL을 확인합니다.
- 정확히 어떤 패키지 빌드가 그 에셋을 생성했는지 확인합니다.
- 직접 딥 링크가 지원되지 않는 경우 SPA로 탐색하기 전에 호스트 루트를 로드합니다.
- 탐색과 상호작용 이후의 콘솔 및 네트워크 오류를 조사합니다.
- 테마 시나리오에서는 공개 프록시 테마 메서드를 호출하고
@theme을 관찰한 뒤 스크린샷을 받아들이기 전에host.getThemeMode()를 확인합니다.