스피논
0.1.0-draft

    0006 · 라우팅과 화면 이동

    상태: 제안 · 명세 버전: 0.1.0-draft

    범위

    라우터는 앱 위치와 방문 기록을 관리하는 선택형 패키지다. UI 트리·GPU 렌더러·V8 엔진은 특정 라우팅 라이브러리에 의존하지 않는다. React·Vue·Svelte 어댑터는 같은 위치·이동 계약을 사용할 수 있어야 한다. 라우터가 없는 앱도 단일 화면으로 실행할 수 있다.

    공통 위치는 경로, 검색 매개변수, 해시, 방문 항목 키로 표현한다. 화면 구성 요소의 상태는 라우터가 자동으로 보존하지 않는다. 라우트별 스크롤·검색·폼 상태를 복원하려면 상태 저장 규칙을 별도로 지정한다.

    이동 계약

    동작웹Android·iOS
    push(to)현재 사이트의 새 방문 항목과 URL을 만든다.새 화면 항목을 앱 스택에 넣는다.
    replace(to)현재 방문 항목과 URL을 바꾼다.현재 화면 항목을 교체한다.
    back()이전 방문 항목으로 이동을 요청한다.앱 스택의 이전 화면으로 이동을 요청한다.
    current() / subscribe()현재 위치를 읽고 변경을 구독한다.동일한 형태의 위치를 읽고 변경을 구독한다.

    위 표는 공개 동작의 의미다. 함수 이름·정확한 TypeScript 서명·완료 시점은 채택 전에 고정한다. push 또는 replace가 끝났다는 신호와 새 픽셀이 화면에 표시됐다는 신호를 혼동하지 않는다.

    링크

    등록된 앱 내부 경로를 가리키는 <a href="/post/42">는 링크 의미와 접근성 이름을 유지하며 라우터 이동으로 연결한다. 외부 URL은 앱 밖으로 열지, 명시적 WebView에서 열지 앱 정책이 정한다. 미등록 내부 경로, 허용되지 않은 URL 스킴, 라우터가 없는 화면의 내부 링크는 조용히 무시하지 않고 오류·진단을 제공한다.

    라우터는 모바일에 window.location이나 window.history 전체를 설치하지 않는다. 브라우저 전용 라이브러리의 직접 DOM·History 접근은 별도 호환 판정 대상이다.

    기존 라우터 연결

    한 앱의 방문 기록은 한 라우터가 소유한다. 기존 라우터를 쓰는 앱에서는 해당 라우터의 위치를 스피논 화면 이동의 기준으로 삼고, 스피논이 별도 방문 스택을 중복 관리하지 않는다. 플랫폼 뒤로 가기·딥링크는 어댑터가 라우터에 전달하고, 라우터의 위치 변경을 화면과 접근성 상태에 반영한다. 웹 빌드에서는 해당 라우터의 브라우저 기록 모드를 사용할 수 있다.

    라이브러리모바일 연결 출발점추가로 필요한 연결
    React RoutercreateMemoryRouter로 브라우저 URL 없이 경로와 방문 기록을 관리한다.스피논 React 렌더러와 RouterProvider 연결, 스피논 링크 컴포넌트, OS 뒤로 가기·딥링크 전달, 데이터 로더와 웹 API 호환 범위 확인
    TanStack Router@tanstack/history의 createMemoryHistory를 라우터에 전달하고, React·Solid 어댑터에서 경로·검색 매개변수·로더를 사용한다.현재 React 설치 문서의 ReactDOM 요구 사항과 링크의 앵커 요소·DOM 의존을 분리해 확인한다. 스피논 렌더러 연결, OS 뒤로 가기·딥링크·스크롤·프리패치 동작을 검증한다.
    Vue RoutercreateMemoryHistory와 RouterLink의 custom 슬롯 또는 useLink로 라우트 상태와 링크 동작을 연결한다.스피논 Vue 렌더러, 첫 경로 설정, OS 뒤로 가기·딥링크 전달, 모바일 화면·기록 동기화
    Svelte 컴포넌트스피논의 위치·이동 계약을 직접 구독하는 라우터 어댑터를 사용한다.Svelte 렌더러와 링크 컴포넌트 연결; 사용하는 독립 라우터마다 별도 호환 판정
    SvelteKit파일 기반 경로와 $app/navigation은 SvelteKit 런타임에 속한다.모바일에서 그대로 재사용하려면 경로 빌드 결과, 탐색, load, 서버 기능의 별도 이식 범위를 정해야 한다. 현재는 직접 호환을 약속하지 않는다.

    메모리 기록 모드가 있다는 사실만으로 해당 라이브러리의 DOM 의존 컴포넌트, 스크롤 복원, 문서 이동, 프리패치, 서버 기능까지 동작하는 것은 아니다. 각 어댑터는 경로·매개변수·중첩 라우트·링크·뒤로 가기·딥링크를 실제 앱에서 확인한 뒤 지원 범위를 공개한다.

    관련 공식 문서: React Router 메모리 라우터, TanStack Router 기록 유형, TanStack Router 설치 요구 사항, Vue Router 기록 모드, Vue Router 링크 확장, SvelteKit 라우팅.

    플랫폼 입력

    • 앱 시작 URL 또는 딥링크를 첫 위치로 변환한다. 지원하지 않는 경로는 앱이 등록한 오류 화면으로 보낸다.
    • Android 시스템 뒤로 가기와 iOS의 뒤로 가기 동작은 앱 스택에 이전 항목이 있으면 라우터로 전달한다. 루트 화면에서의 종료·무시·상위 앱 전달 정책은 플랫폼별로 명시한다.
    • 외부에서 같은 딥링크가 다시 들어왔을 때 push·replace·기존 항목 재사용 중 무엇을 할지는 앱 설정과 적합성 시나리오로 정의한다.
    • 앱 복귀·프로세스 재생성 뒤 복원 가능한 위치와 상태의 범위, 인증이 필요한 경로의 처리, 비동기 이동 취소는 아직 미정이다.

    적합성 시나리오

    1. 같은 /feed/42?tab=comments가 웹 새로고침과 Android·iOS 딥링크 시작에서 같은 라우트 데이터로 해석된다.
    2. 목록 → 상세 → 뒤로 가기에서 경로·화면·접근성 제목이 일치한다. 스크롤 상태는 앱이 복원 계약을 활성화했을 때만 판정한다.
    3. 미등록 경로, 외부 URL, 루트에서의 뒤로 가기, 백그라운드 복귀가 플랫폼별 명시한 결과를 낸다.
    4. 라우터가 없는 단일 화면 앱은 추가 이동 기능 없이 정상 실행된다.