create-saas-starter-workspace 0.1.0

package/templates/workspace/mobile/src/ui/OfflineView.tsx

@@ -0,0 +1,73 @@
+import React from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+
+import { t } from "../i18n";
+
+export type OfflineViewProps = {
+  /** 재시도 콜백 — 셸은 연결 상태를 다시 확인하고(NetInfo) 필요 시 웹뷰를 재로드한다. */
+  onRetry: () => void;
+};
+
+/**
+ * 기기가 오프라인일 때 웹뷰 위에 덮는 오버레이 (DESIGN 결정 21: 오프라인 화면).
+ *
+ * onError는 "로드 실패"만 잡고 로드 후 라이브 연결 끊김은 못 잡으므로, 셸은 NetInfo를
+ * 구독해 연결이 끊기면 이 화면을 띄운다. 에러 화면과 시각적으로 구분되는 별도 문구를 쓴다.
+ */
+export function OfflineView(props: OfflineViewProps): React.JSX.Element {
+  const { onRetry } = props;
+  return (
+    <View style={styles.fill}>
+      <Text style={styles.title}>{t("offline.title")}</Text>
+      <Text style={styles.body}>{t("offline.body")}</Text>
+      <Pressable
+        onPress={onRetry}
+        accessibilityRole="button"
+        style={({ pressed }) => [styles.button, pressed && styles.buttonPressed]}
+      >
+        <Text style={styles.buttonLabel}>{t("offline.retry")}</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  fill: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: "#fff",
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: 24,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: "700",
+    color: "#111",
+    textAlign: "center",
+  },
+  body: {
+    marginTop: 8,
+    fontSize: 13,
+    color: "#666",
+    textAlign: "center",
+  },
+  button: {
+    marginTop: 20,
+    paddingHorizontal: 18,
+    paddingVertical: 11,
+    borderRadius: 10,
+    backgroundColor: "#111",
+  },
+  buttonPressed: {
+    opacity: 0.7,
+  },
+  buttonLabel: {
+    color: "#fff",
+    fontSize: 14,
+    fontWeight: "600",
+  },
+});

package/templates/workspace/mobile/src/webview/Host.tsx

@@ -0,0 +1,353 @@
+import React from "react";
+import { BackHandler, Platform, StyleSheet, View } from "react-native";
+import { WebView } from "react-native-webview";
+import type {
+  ShouldStartLoadRequest,
+  WebViewErrorEvent,
+  WebViewHttpErrorEvent,
+  WebViewMessageEvent,
+  WebViewNavigation,
+  WebViewOpenWindowEvent,
+} from "react-native-webview/lib/WebViewTypes";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import NetInfo, { type NetInfoState } from "@react-native-community/netinfo";
+import * as Linking from "expo-linking";
+import Constants from "expo-constants";
+
+import { handleInbound, helloInjection, type BridgeContext } from "../bridge/router";
+import { ALLOWED_ORIGINS, WEB_ORIGIN } from "../config/env";
+import { classifyLink, toOrigin } from "./linkBoundary";
+import { LoadingView } from "../ui/LoadingView";
+import { ErrorView } from "../ui/ErrorView";
+import { OfflineView } from "../ui/OfflineView";
+
+/**
+ * 네이티브 셸 호스트 — 웹뷰를 감싸 셸 레시피를 구현한다
+ * (DESIGN 결정 21 셸 레시피 전부 + 결정 18 개발 루프). 4.2는 이 셸만으론 부족하다(출발점) — store-release-guide 참고.
+ *
+ * 책임:
+ *  - 안전영역(노치) 여백을 네이티브가 측정해 CSS 커스텀 변수로 웹에 주입 (env() 금지).
+ *  - Android 하드웨어 뒤로가기: 웹뷰 history 우선, 없으면 OS에 위임.
+ *  - 외부 링크 경계: 단일 분류자 classifyLink(linkBoundary)를 navigation·window.open·OPEN_EXTERNAL이 공유.
+ *  - 크래시 복구: key 증가로 통째 재마운트(reload 아님), lastKnownUrl 복원.
+ *  - 오프라인/에러/로딩 오버레이.
+ *  - 브릿지: onMessage → handleInbound, 페이지 도달 후 helloInjection 1회.
+ *
+ * 토큰은 이 채널을 절대 거치지 않는다 — 세션은 서버 Set-Cookie 핸드오프(결정 15·session 슬라이스).
+ */
+
+export type WebViewHostProps = {
+  /**
+   * 웹뷰가 로드할 URL. App이 config/env의 WEB_URL을 넘긴다 — 여기서 하드코딩 금지.
+   *
+   * 앱은 배포된 prod 웹 https URL을 로드한다(실기기는 localhost 도달 불가 + http LAN은
+   * secure-context가 아니라 카메라·Web Crypto·Secure 쿠키가 조용히 깨짐). localhost는
+   * 시뮬레이터에서 셸을 고칠 때만 쓰는 예외이며, 그 분기는 env.ts 가드가 책임진다.
+   */
+  url: string;
+  /** 웹이 세션 없음을 알릴 때(REQUEST_SESSION_INSTALL) 네이티브 로그인 흐름을 시작. */
+  onNeedLogin?: (redirectPath?: string) => void;
+  /** 웹 로그아웃(LOGOUT) 시 네이티브 로컬 세션 사본을 정리. */
+  onLoggedOut?: () => void;
+};
+
+const APP_VERSION = Constants.expoConfig?.version ?? "unknown";
+const PLATFORM: "ios" | "android" = Platform.OS === "ios" ? "ios" : "android";
+
+/** 로드 실패 상태(네트워크 vs HTTP). 오프라인은 별도 NetInfo 상태로 다룬다. */
+type WebError = { kind: "network" | "http"; message?: string };
+
+/**
+ * 안전영역 inset(dp)을 :root 의 CSS 커스텀 변수로 박는 JS 소스를 만든다.
+ *
+ * env(safe-area-inset-*)는 양 플랫폼 다 못 쓴다(Android WebView 138+는 0px, iOS는 첫
+ * 페인트 지연 점프) → 네이티브가 useSafeAreaInsets로 측정한 값을 --ssb-inset-* 변수로
+ * 직접 주입하고, 웹은 그 변수로 패딩한다(결정 21 safe-area: 네이티브=값, 웹=레이아웃).
+ *
+ * inset은 이미 dp(=CSS px와 1:1) 단위이므로 그대로 px로 쓴다. viewport-fit=cover는
+ * 콘텐츠가 노치 영역까지 펼쳐지도록 보장(이 변수 패딩이 의미를 가지려면 필요).
+ */
+function buildInsetInjection(insets: { top: number; right: number; bottom: number; left: number }): string {
+  const { top, right, bottom, left } = insets;
+  return (
+    "try{" +
+    "var d=document.documentElement;" +
+    `d.style.setProperty('--ssb-inset-top','${top}px');` +
+    `d.style.setProperty('--ssb-inset-right','${right}px');` +
+    `d.style.setProperty('--ssb-inset-bottom','${bottom}px');` +
+    `d.style.setProperty('--ssb-inset-left','${left}px');` +
+    // viewport-fit=cover 를 보장(meta가 없으면 추가).
+    "var m=document.querySelector('meta[name=viewport]');" +
+    "if(m){if(m.content.indexOf('viewport-fit')===-1){m.content+=', viewport-fit=cover';}}" +
+    "else{m=document.createElement('meta');m.name='viewport';" +
+    "m.content='width=device-width, initial-scale=1, viewport-fit=cover';" +
+    "document.head.appendChild(m);}" +
+    "}catch(e){}" +
+    " true;"
+  );
+}
+
+export function WebViewHost(props: WebViewHostProps): React.JSX.Element {
+  const { url, onNeedLogin, onLoggedOut } = props;
+  const insets = useSafeAreaInsets();
+
+  const webRef = React.useRef<WebView | null>(null);
+  // 크래시 복구용: key를 올리면 웹뷰가 통째 재마운트된다(Android는 reload로 불충분 —
+  // 죽은 렌더 프로세스 인스턴스를 폐기하고 새로 만들어야 한다. 결정 21 크래시 복구).
+  const [webKey, setWebKey] = React.useState(0);
+  // 첫 로드 완료까지만 로딩 오버레이.
+  const [loading, setLoading] = React.useState(true);
+  const [webError, setWebError] = React.useState<WebError | null>(null);
+  // 오프라인 오버레이. onError는 라이브 연결 끊김을 못 잡으므로 NetInfo로 별도 추적.
+  const [offline, setOffline] = React.useState(false);
+  // Android 뒤로가기 판단용. 최신 값을 ref로 들고 있어야 BackHandler 콜백이 stale을 안 읽는다.
+  const canGoBackRef = React.useRef(false);
+  // 크래시 복구 시 맹목 reload 대신 복원할 마지막 정상 URL.
+  const lastKnownUrlRef = React.useRef<string>(url);
+  // helloInjection 1회 가드 — onLoadEnd가 SPA에서 여러 번 와도 한 번만 보낸다.
+  const helloSentRef = React.useRef(false);
+
+  /**
+   * 내비게이션 경계 — 순수 분류자(classifyLink)의 판정을 웹뷰 boolean으로 옮기고,
+   * "external"이면 시스템 브라우저로 위임한다. onShouldStartLoadWithRequest 와
+   * onOpenWindow 가 공유하므로 규칙은 linkBoundary 한 곳에만 있다 (결정 21 링크 경계).
+   *
+   * 반환 true  = 웹뷰가 in-app으로 직접 로드.
+   * 반환 false = 웹뷰 로드 차단("external"은 OS 위임 후, "block"은 아무 데도 안 넘김).
+   */
+  const routeNavigation = React.useCallback((targetUrl: string): boolean => {
+    const decision = classifyLink(targetUrl, ALLOWED_ORIGINS);
+    if (decision === "in-app") {
+      // 허용 origin → in-app. (동일 origin 필수 true: Android #2819 유령 리로드 회피)
+      return true;
+    }
+    if (decision === "external") {
+      // mailto:/tel:/geo:/intent: + 허용 외 https → OS 위임. 실패는 조용히 무시(앱 미설치 등).
+      Linking.openURL(targetUrl).catch(() => {});
+    }
+    // "external"·"block" 모두 웹뷰 로드는 막는다.
+    return false;
+  }, []);
+
+  /**
+   * 라우터에 넘길 BridgeContext. inject/openExternal은 네이티브 구현으로 채운다.
+   * webRef·콜백 props가 바뀔 때만 재생성.
+   */
+  const bridgeCtx = React.useMemo<BridgeContext>(
+    () => ({
+      appVersion: APP_VERSION,
+      platform: PLATFORM,
+      webOrigin: WEB_ORIGIN,
+      inject: (js: string) => {
+        webRef.current?.injectJavaScript(js);
+      },
+      onNeedLogin: (redirectPath?: string) => {
+        onNeedLogin?.(redirectPath);
+      },
+      onLoggedOut: () => {
+        onLoggedOut?.();
+      },
+      openExternal: (externalUrl: string) => {
+        // OPEN_EXTERNAL = "웹뷰 밖으로"라는 웹의 명시적 명령. 내비게이션과 같은 단일 분류자
+        // (classifyLink)를 '안전 게이트'로 쓴다: 파싱 실패("block")만 막고(깨진 URL을 OS에 안 넘김),
+        // 나머지는 — 허용 origin이라도 — 시스템에 위임한다(웹뷰 escape가 이 메시지의 존재 이유이므로
+        // origin 허용목록이 명시적 명령을 막지 않는다. 결정 21). url은 origin-게이트된 onMessage로만
+        // 들어오고, Linking은 OS에 넘길 뿐 웹뷰에서 실행하지 않는다(스킴 안전성은 이 둘에 기댄다).
+        if (classifyLink(externalUrl, ALLOWED_ORIGINS) !== "block") {
+          Linking.openURL(externalUrl).catch(() => {});
+        }
+      },
+    }),
+    [onNeedLogin, onLoggedOut],
+  );
+
+  // ── 오프라인 감지 (결정 21 오프라인) ─────────────────────────────
+  // onError는 "로드 실패"만 잡고 로드 후 라이브 연결 끊김은 못 잡으므로 NetInfo를 구독한다.
+  // NetInfo.addEventListener는 해제 함수를 반환한다(이 라이브러리는 .remove()가 아니라 호출형).
+  React.useEffect(() => {
+    const unsubscribe = NetInfo.addEventListener((state: NetInfoState) => {
+      // isConnected === false 면 확실한 오프라인. isInternetReachable === false 도 오프라인 취급.
+      // null/unknown(아직 모름)은 온라인으로 둬서 거짓 오프라인 깜빡임을 피한다.
+      const disconnected = state.isConnected === false || state.isInternetReachable === false;
+      setOffline(disconnected);
+    });
+    return () => {
+      unsubscribe();
+    };
+  }, []);
+
+  // ── Android 하드웨어 뒤로가기 (결정 21) ──────────────────────────
+  // 웹뷰 history가 있으면 goBack()+true(소비), 없으면 false로 OS에 위임(예측-뒤로/종료).
+  // RN 0.85: 구독 해제는 subscription.remove() (removeEventListener 제거됨).
+  React.useEffect(() => {
+    if (Platform.OS !== "android") return;
+    const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
+      if (canGoBackRef.current) {
+        webRef.current?.goBack();
+        return true; // 우리가 소비.
+      }
+      return false; // OS 기본 동작(예측-뒤로/앱 종료)에 위임.
+    });
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  // 크래시/에러 복구: key를 올려 통째 재마운트하고 오버레이를 닫는다.
+  const remountWebView = React.useCallback(() => {
+    helloSentRef.current = false;
+    setWebError(null);
+    setLoading(true);
+    setWebKey((prev) => prev + 1);
+  }, []);
+
+  // 오프라인 오버레이의 "다시 시도": 연결을 재확인하고, 회복됐으면 웹뷰를 재로드한다.
+  const retryFromOffline = React.useCallback(() => {
+    NetInfo.fetch().then((state) => {
+      const disconnected = state.isConnected === false || state.isInternetReachable === false;
+      setOffline(disconnected);
+      if (!disconnected) {
+        webRef.current?.reload();
+      }
+    });
+  }, []);
+
+  // ── 이벤트 핸들러 ───────────────────────────────────────────────
+  const onMessage = React.useCallback(
+    (event: WebViewMessageEvent) => {
+      // 1차 방어: 메시지를 보낸 프레임의 origin이 허용 목록일 때만 처리한다. ns 게이트(reader/router)는
+      // 'ssb' 봉투인지'만' 거르지 origin은 못 거른다(postMessage는 어떤 프레임에서도 호출 가능). 링크
+      // 경계가 메인 프레임을 허용 origin에 묶어두므로 정상 경로에선 항상 통과하고, 벗어나면 차단한다.
+      const origin = toOrigin(event.nativeEvent.url);
+      if (origin === null || !ALLOWED_ORIGINS.includes(origin)) {
+        return;
+      }
+      // ns·형식 게이트는 reader/router가 담당(SSB_NS 아닌·깨진 트래픽 → UNKNOWN → 무시, never-throw).
+      handleInbound(event.nativeEvent.data, bridgeCtx);
+    },
+    [bridgeCtx],
+  );
+
+  const onNavigationStateChange = React.useCallback((nav: WebViewNavigation) => {
+    canGoBackRef.current = nav.canGoBack;
+    // 크래시 복구용 마지막 정상 URL 추적(허용 origin인 실제 페이지만; about:blank/오류 제외).
+    const origin = toOrigin(nav.url);
+    if (origin !== null && ALLOWED_ORIGINS.includes(origin)) {
+      lastKnownUrlRef.current = nav.url;
+    }
+  }, []);
+
+  // onLoadEnd는 성공·실패 로드 모두에서 불린다 → 스피너만 내린다(실패면 ErrorView가 위에 뜬다).
+  const onLoadEnd = React.useCallback(() => {
+    setLoading(false);
+  }, []);
+
+  // onLoad는 성공 로드에서만 불린다 → HELLO는 여기서만 1회 주입한다(실패 페이지엔 능력을 광고하지 않음).
+  // (결정 8: 앱이 능력을 광고 → 웹이 feature-detect.)
+  const onLoad = React.useCallback(() => {
+    if (!helloSentRef.current) {
+      helloSentRef.current = true;
+      webRef.current?.injectJavaScript(helloInjection({ appVersion: APP_VERSION, platform: PLATFORM }));
+    }
+  }, []);
+
+  const onError = React.useCallback((event: WebViewErrorEvent) => {
+    setWebError({ kind: "network", message: event.nativeEvent.description });
+  }, []);
+
+  const onHttpError = React.useCallback((event: WebViewHttpErrorEvent) => {
+    const code = event.nativeEvent.statusCode;
+    setWebError({ kind: "http", message: `HTTP ${code}` });
+  }, []);
+
+  const onShouldStartLoadWithRequest = React.useCallback(
+    (req: ShouldStartLoadRequest): boolean => routeNavigation(req.url),
+    [routeNavigation],
+  );
+
+  // _blank/window.open 으로 새 창을 열려는 시도. onOpenWindow가 없으면 빈 페이지가 뜨므로 필수.
+  // 같은 링크 경계로 보내 외부 URL은 시스템 브라우저로 연다(in-app 새 창은 만들지 않음).
+  const onOpenWindow = React.useCallback(
+    (event: WebViewOpenWindowEvent) => {
+      routeNavigation(event.nativeEvent.targetUrl);
+    },
+    [routeNavigation],
+  );
+
+  // 안전영역 inset 주입 JS. inset 값이 바뀌면 새 문자열이 되고, key로 묶어 재로드 시 재적용.
+  // injectedJavaScriptBeforeContentLoaded는 콘텐츠 로드 전에 실행되어 첫 페인트 점프를 막는다.
+  const insetInjection = React.useMemo(
+    () => buildInsetInjection({ top: insets.top, right: insets.right, bottom: insets.bottom, left: insets.left }),
+    [insets.top, insets.right, insets.bottom, insets.left],
+  );
+
+  // inset 값이 런타임에 바뀌면(회전·split view 등) 이미 로드된 페이지에도 다시 주입한다.
+  // 로드 전이면 injectJavaScript는 무해한 no-op이고 첫 적용은 injectedJavaScriptBeforeContentLoaded가
+  // 담당하므로, helloSent 가드 없이 항상 시도한다(첫 onLoad 이전 회전 누락 방지).
+  React.useEffect(() => {
+    webRef.current?.injectJavaScript(insetInjection);
+  }, [insetInjection]);
+
+  return (
+    <View style={styles.fill}>
+      <WebView
+        // key를 올리면 통째 재마운트 → 크래시 복구. 동시에 inset 변경 시 BeforeContentLoaded 재적용.
+        key={webKey}
+        ref={webRef}
+        // 첫 마운트 = 진입 url(lastKnownUrlRef 초기값). webKey가 올라 재마운트되는 크래시
+        // 복구 시엔 마지막 정상 url로 복원한다(맨 처음으로 재진입이 아니라 있던 자리 복원).
+        // `|| url`은 lastKnownUrl이 비어 있을 때의 폴백(정상 경로에선 발생하지 않음).
+        source={{ uri: lastKnownUrlRef.current || url }}
+        // 안전영역 변수를 콘텐츠 로드 전에 :root에 박는다(env() 아님 — 결정 21).
+        injectedJavaScriptBeforeContentLoaded={insetInjection}
+        // 위 주입 스크립트는 메인 프레임에만(서드파티 iframe에 새지 않도록; Android 필수).
+        injectedJavaScriptBeforeContentLoadedForMainFrameOnly
+        injectedJavaScriptForMainFrameOnly
+        // 브릿지: 웹→앱 메시지 수신. ns 게이트는 reader/router가 담당.
+        onMessage={onMessage}
+        onLoad={onLoad}
+        onLoadEnd={onLoadEnd}
+        onError={onError}
+        onHttpError={onHttpError}
+        onNavigationStateChange={onNavigationStateChange}
+        // 외부 링크 경계(단일 판단을 양쪽에 공유).
+        onShouldStartLoadWithRequest={onShouldStartLoadWithRequest}
+        onOpenWindow={onOpenWindow}
+        // 크래시 복구: iOS=프로세스 종료, Android=렌더 프로세스 사망(핸들러 return true 필수).
+        onContentProcessDidTerminate={remountWebView}
+        onRenderProcessGone={() => {
+          remountWebView();
+          return true;
+        }}
+        // 파일 업로드(<input type=file>)와 카메라/미디어 캡처가 동작하도록 (결정 21 파일 업로드).
+        // iOS usage string은 app.config.ts(다른 슬라이스)에 둔다.
+        allowsInlineMediaPlayback
+        mediaCapturePermissionGrantType="grant"
+        // 당겨서 새로고침: iOS는 prop 한 줄(기본 false). Android는 iOS 전용이라 무시되며
+        // RefreshControl 별도 배선이 필요하다(fast-follow; 결정 21 당겨새로고침).
+        pullToRefreshEnabled={Platform.OS === "ios"}
+        // 표준 웹 기능: JS·DOM 저장·쿠키. 세션은 서버 Set-Cookie 핸드오프라 쿠키 공유가 핵심.
+        javaScriptEnabled
+        domStorageEnabled
+        sharedCookiesEnabled
+        thirdPartyCookiesEnabled
+        // iOS 스와이프 뒤로/앞으로 제스처(웹 history 탐색).
+        allowsBackForwardNavigationGestures={Platform.OS === "ios"}
+        // iOS: 웹 폼 입력칸의 자동 포커스·키보드가 막히지 않도록(WKWebView 기본 true가 막음). 결정 21.
+        keyboardDisplayRequiresUserAction={false}
+        style={styles.fill}
+      />
+      {loading ? <LoadingView /> : null}
+      {webError ? <ErrorView message={webError.message} onRetry={remountWebView} /> : null}
+      {/* 오프라인은 가장 위 — 연결이 끊기면 에러/로딩과 무관하게 최우선으로 알린다. */}
+      {offline ? <OfflineView onRetry={retryFromOffline} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  fill: {
+    flex: 1,
+    backgroundColor: "#fff",
+  },
+});

package/templates/workspace/mobile/src/webview/linkBoundary.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { classifyLink, toOrigin } from "./linkBoundary";
+
+const ALLOWED = ["https://app.example.com"] as const;
+
+describe("classifyLink — 단일 링크 경계", () => {
+  it("허용 origin의 https는 in-app", () => {
+    expect(classifyLink("https://app.example.com/path?q=1", ALLOWED)).toBe("in-app");
+  });
+
+  it("허용 origin이라도 http(평문)는 origin이 달라 external", () => {
+    // origin은 scheme을 포함한다 → http://… ≠ https://app.example.com.
+    expect(classifyLink("http://app.example.com/x", ALLOWED)).toBe("external");
+  });
+
+  it("허용 외 https origin은 external", () => {
+    expect(classifyLink("https://other.com/x", ALLOWED)).toBe("external");
+  });
+
+  it("서브도메인 prefix 위장은 다른 origin이라 external (startsWith 아님)", () => {
+    expect(classifyLink("https://app.example.com.evil.com/x", ALLOWED)).toBe("external");
+  });
+
+  it("비-http(s) 안전 스킴(mailto/tel/geo/sms/intent)은 external", () => {
+    for (const u of [
+      "mailto:a@b.com",
+      "tel:+8210",
+      "geo:37.5,127.0",
+      "sms:+8210",
+      "intent://scan/#Intent;scheme=zxing;end",
+    ]) {
+      expect(classifyLink(u, ALLOWED)).toBe("external");
+    }
+  });
+
+  it("파싱 실패(빈 문자열·상대경로·쓰레기)는 block", () => {
+    for (const u of ["", "   ", "/relative/path", "not a url", "::::"]) {
+      expect(classifyLink(u, ALLOWED)).toBe("block");
+    }
+  });
+
+  it("허용목록이 비면 모든 http(s)는 external", () => {
+    expect(classifyLink("https://app.example.com/x", [])).toBe("external");
+  });
+});
+
+describe("toOrigin", () => {
+  it("scheme+host+port를 origin으로 뽑는다", () => {
+    expect(toOrigin("https://app.example.com:443/a/b?c#d")).toBe("https://app.example.com");
+    expect(toOrigin("http://h:8080/x")).toBe("http://h:8080");
+  });
+
+  it("파싱 실패는 null", () => {
+    expect(toOrigin("nonsense")).toBeNull();
+    expect(toOrigin("")).toBeNull();
+  });
+});

package/templates/workspace/mobile/src/webview/linkBoundary.ts

@@ -0,0 +1,58 @@
+/**
+ * 외부 링크 경계 — 순수(부수효과 없음) 분류자 (DESIGN 결정 21).
+ *
+ * 셸의 모든 링크 판단이 이 한 곳의 규칙을 공유한다: 내비게이션
+ * (onShouldStartLoadWithRequest·onOpenWindow)과 브릿지 OPEN_EXTERNAL. 네이티브/expo
+ * import가 없어 Node(vitest)에서 단위 테스트된다 — origin 허용목록·스킴 게이트는 보안
+ * 경계라(🔴) 테스트로 못 박는다.
+ *
+ * 부수효과(Linking.openURL)는 호출자(Host)가 판정을 받아 수행한다 — 여기선 URL을 열지 않는다.
+ */
+
+/**
+ * url에서 origin만 안전하게 뽑는다(파싱 실패 시 null).
+ * 동일 origin 비교는 반드시 origin 등가비교 — startsWith 금지(서브도메인 prefix 위장 회피).
+ */
+export function toOrigin(url: string): string | null {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** url의 scheme(소문자, 콜론 제거). 파싱 실패 시 null. */
+function getScheme(url: string): string | null {
+  try {
+    return new URL(url).protocol.replace(/:$/, "").toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 링크 경계의 세 가지 판정.
+ *  - "in-app"   : 허용 origin의 http(s) → 웹뷰가 직접 로드.
+ *  - "external" : 그 외 파싱되는 URL(허용 외 http(s) + mailto:/tel:/geo:/intent: 등 비-http(s) 스킴)
+ *                 → 시스템에 위임. 이건 파싱·origin 게이트이지 스킴 안전성 필터가 아니다
+ *                 (javascript:/data:도 파싱되면 external) — 호출자가 OS에 위임할 뿐 웹뷰에서 실행하지 않는다.
+ *  - "block"    : 파싱 실패 → 아무 데도(웹뷰에도, OS에도) 넘기지 않는다.
+ */
+export type LinkDecision = "in-app" | "external" | "block";
+
+/**
+ * 단일 링크 분류자. 부수효과 없음 — 판정만 반환한다.
+ *  - 파싱 실패 → "block".
+ *  - http(s) + origin ∈ allowedOrigins → "in-app"(동일 origin 필수: Android #2819 유령 리로드 회피).
+ *  - http(s) + 허용 외 origin → "external".
+ *  - 비-http(s) 스킴(mailto:/tel:/geo:/intent: 등) → "external".
+ */
+export function classifyLink(url: string, allowedOrigins: readonly string[]): LinkDecision {
+  const scheme = getScheme(url);
+  if (scheme === null) return "block";
+  if (scheme === "http" || scheme === "https") {
+    const origin = toOrigin(url);
+    return origin !== null && allowedOrigins.includes(origin) ? "in-app" : "external";
+  }
+  return "external";
+}

package/templates/workspace/mobile/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true
+  },
+  "//": "docs/web-adapter holds WEB-side template code (Next.js / @supabase/ssr) that is NOT part of this app's build — exclude it from typechecking.",
+  "exclude": ["node_modules", "docs"]
+}

package/templates/workspace/mobile/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Tests cover the pure, native-free logic: the bridge contract and tolerant
+ * reader. These run in plain Node — they import no React Native modules.
+ * (Native shell behavior is verified by hand on a dev build / device, per the
+ * dev-loop guide.)
+ */
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/templates/workspace/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "saas-starter-workspace",
+  "version": "0.1.0",
+  "private": true,
+  "description": "워크스페이스 루트 명령. 서비스 코드는 web/·mobile/이 각자 가진다.",
+  "scripts": {
+    "doctor": "node scripts/doctor.mjs"
+  }
+}