호환성 표의 단위
함수마다 웹·Android·iOS의 존재 여부, 입력과 반환값, 오류, 취소, 권한, 백그라운드 동작을 기록합니다. fetch()처럼 같은 이름을 쓸 때에는 차이를 문서화하고, 동작이 크게 다르면 플랫폼 API로 분리합니다.
보손 / JavaScript API 대응 명세
같은 JavaScript, 다른 실행 환경
V8이 JavaScript 언어를 실행하는 것과 브라우저 API가 존재하는 것은 별개입니다. 보손이 직접 제공할 함수, 모바일에서 달라지는 동작, 모바일 전용 함수와 초기 제외 항목을 분리합니다.
판정 원칙 · 같은 이름을 노출할 때에는 반환값뿐 아니라 오류, 취소, 이벤트 순서, 백그라운드 동작을 정의합니다. 그 계약을 맞출 수 없으면 웹 API를 흉내 내지 않고
@boson/platform의 명시적 API로 제공합니다.01 · 언어 엔진 기능
V8에 포함되는 영역앱에 포함한 V8 버전과 빌드 옵션을 고정한 뒤 확인합니다. 언어 기능의 존재만으로 타이머·네트워크·DOM이 생기지는 않습니다.
| 함수·객체 | 웹과의 관계 | 보손 계약 | 상태 |
|---|---|---|---|
Promise Map Set | ECMAScript 언어 객체 | 선택한 V8 빌드에서 제공. 비동기 작업을 돌릴 마이크로태스크 체크포인트는 보손 호스트가 정합니다. | 엔진 검증 |
JSON ArrayBuffer TypedArray | 언어 수준 데이터 기능 | JS 객체와 Rust·C++ 경계를 넘을 때 복사·소유권·크기 제한은 별도 계약으로 둡니다. | 엔진 검증 |
Intl Date | 언어 기능이지만 로케일·시간대 데이터에 영향 | V8/ICU 빌드, OS 시간대와 언어 데이터를 고정해 실제 결과를 비교합니다. | 조건 검증 |
globalThis | ECMAScript 전역 객체 참조 | 전역 객체 자체는 언어 기능입니다. 여기에 어떤 웹식 API를 설치할지는 보손 호스트 계약으로 구분합니다. | 엔진 검증 |
02 · 보손이 제공할 API
V8 기본 기능이 아님웹과 같은 이름을 목표로 하지만 구현은 보손 호스트에 둡니다. 첫 수직 구현에 필요한 최소 기능부터 제공합니다.
| 함수·객체 | 웹에서의 용도 | 보손 구현·검증 조건 | 첫 목표 |
|---|---|---|---|
setTimeout clearTimeout | 지연 작업·취소 | 호스트 스케줄러와 JS 이벤트 루프에 연결. 취소 후 콜백 수명과 앱 중단 시 동작을 검증합니다. | 수직 구현 |
queueMicrotask | 현재 작업 뒤의 미세 작업 | V8 마이크로태스크 큐와 호스트 콜백 경계의 실행 순서를 고정합니다. | 수직 구현 |
URL URLSearchParams | 주소 파싱·조합 | 표준 형태를 목표로 하며 상대 URL의 기준 주소를 모바일 앱에서 명시합니다. | 도구 확장 |
TextEncoder TextDecoder | 문자열·바이트 변환 | 지원 인코딩·오류 동작을 웹과 비교해 호스트 또는 폴리필로 제공합니다. | 도구 확장 |
AbortController | 비동기 작업 취소 신호 | fetch와 다른 호스트 호출이 취소를 어느 시점에 반영하는지 명시합니다. | 도구 확장 |
console | 로그·오류 조사 | 출력 대상, 오류 스택, 릴리스 로그 정책은 호스트가 정합니다. | 수직 구현 |
Blob File FormData | 바이너리 데이터·업로드 | 메모리 한도, 파일 핸들 수명, fetch 본문·스트림 연동을 정한 뒤 제공하며 초기 존재를 가정하지 않습니다. | 후속 단계 |
crypto.getRandomValues() crypto.randomUUID() | 안전한 난수·식별자 | OS 난수원을 연결하고 실패 및 백그라운드 동작을 검증합니다. V8 언어 엔진만으로 자동 제공되지 않습니다. | 도구 확장 |
03 · 이름은 같고 동작은 다름
호환성 차이를 공개같은 소스가 컴파일되어도 브라우저의 출처·문서·탭 수명주기와 모바일 앱의 권한·백그라운드 규칙은 다릅니다.
| 함수·객체 | 차이의 원인 | 보손에서 정할 계약 | 첫 목표 |
|---|---|---|---|
fetch() | 브라우저의 출처·CORS·쿠키·캐시와 앱 네트워크 권한·저장소가 다릅니다. | 요청/응답 형식은 웹에 맞추되 상대 URL, 쿠키, 캐시, 자격 증명, 취소, 오류를 별도 표로 공개합니다. CORS와 동일하다고 주장하지 않습니다. | 도구 확장 |
WebSocket EventSource | 연결 유지·재연결이 앱 백그라운드 정책과 충돌할 수 있습니다. | 초기에는 제공하지 않습니다. 연결 상태, 인증, 중단·재개, 배터리 비용을 명세한 뒤 도입합니다. | 후속 단계 |
requestAnimationFrame() | 브라우저 문서 프레임 대신 모바일 GPU 표면의 프레임을 사용합니다. | 표시 주기, 콜백 시각, 화면이 가려지거나 앱이 백그라운드일 때의 중단 규칙을 정합니다. | 렌더러 |
setInterval() | 앱 수명주기와 절전 정책에 따라 정지·지연될 수 있습니다. | 백그라운드에서 실행을 보장하지 않으며 재개 시 누락된 틱을 어떻게 처리할지 정의합니다. | 도구 확장 |
performance.now() | 브라우저의 시간 원점과 앱 프로세스 수명이 다릅니다. | 단조 시계의 원점·정밀도·앱 재개 후 연속성을 기록합니다. 벤치마크에는 플랫폼 계측도 함께 씁니다. | 계측 |
| 스토리지 API | 브라우저 출처 단위 저장과 앱 설치·사용자 데이터 수명이 다릅니다. | localStorage 전역을 바로 복제하지 않고 비동기 저장소 계약, 용량, 암호화와 삭제 정책을 설계합니다. | 도구 확장 |
04 · 모바일 전용 API
명시적 모듈 제안아래 이름은 @boson/platform의 API 형태 제안입니다. 웹 빌드에서는 지원 여부를 확인하는 대체 구현 또는 명시적 실패를 제공합니다. 실제 서명은 구현 전에 확정합니다.
| 제안 함수 | 필요한 이유 | 계약에 포함할 조건 | 첫 목표 |
|---|---|---|---|
getSafeAreaInsets() | 노치·상태 막대·제스처 영역 | 화면 회전과 창 크기 변경 시 값 갱신, CSS 안전 영역과의 관계 | 실사용 UI |
onAppStateChange() | 전경·백그라운드·복귀 처리 | 구독 해제, 이벤트 순서, 일시 중단된 JS 작업의 재개 | 수직 구현+ |
onBackPress() | Android 시스템 뒤로 가기 | 라우터에 이전 방문 항목이 있는지 먼저 확인하고, 루트 화면의 동작은 플랫폼 정책으로 명시합니다. iOS·웹은 각각의 뒤로 가기 입력에 연결합니다. | 실사용 UI |
dismissKeyboard() | 모바일 소프트 키보드 제어 | IME 조합 중 취소·확정, 포커스 이동과 이벤트 순서 | 실사용 UI |
requestPermission() | 카메라·사진·위치 등 OS 권한 | 권한 종류, 거절·재요청·설정 이동, 플랫폼별 상태 차이 | 플랫폼 기능 |
hapticFeedback() | 진동·촉각 반응 | 기기 지원 여부와 강도 차이, 무음/절전 상태 | 플랫폼 기능 |
openExternalURL() | 앱 밖의 링크·딥링크 열기 | 허용 스킴, 실패 결과, 앱 복귀와 보안 정책 | 실사용 UI |
현재 검증 상태
기존 V8 동적 트리 PoC는 JS 호출과 이벤트 연결을 확인한 자료입니다. 이 문서의 fetch(), 타이머, 저장소, 모바일 전용 함수가 실제 앱에서 동작한다는 증거는 아닙니다. 먼저 작은 카운터 앱에 필요한 타이머·마이크로태스크 계약을 구현합니다. 기준 자료: V8 임베딩 문서, DOM 표준, Fetch 표준.