create-saas-starter-workspace 0.1.0

package/templates/workspace/mobile/src/bridge/router.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from "vitest";
+import { handleInbound, helloInjection, type BridgeContext } from "./router";
+import { MSG, SSB_NS, SSB_PROTOCOL_VERSION } from "./contract";
+
+/** 모든 콜백을 spy로 채운 BridgeContext. 테스트마다 새로 만든다. */
+function makeCtx(): BridgeContext {
+  return {
+    appVersion: "1.0.0",
+    platform: "ios",
+    webOrigin: "https://example.com",
+    inject: vi.fn(),
+    onNeedLogin: vi.fn(),
+    onLoggedOut: vi.fn(),
+    openExternal: vi.fn(),
+  };
+}
+
+/** 봉투를 웹→앱 postMessage가 보내는 형태(JSON 문자열)로 직렬화. */
+function wire(msg: Record<string, unknown>): string {
+  return JSON.stringify({ ns: SSB_NS, v: SSB_PROTOCOL_VERSION, ...msg });
+}
+
+describe("handleInbound", () => {
+  it("REQUEST_SESSION_INSTALL → onNeedLogin(redirectPath)", () => {
+    const ctx = makeCtx();
+    handleInbound(
+      wire({ type: MSG.REQUEST_SESSION_INSTALL, payload: { redirectPath: "/dashboard" } }),
+      ctx,
+    );
+    expect(ctx.onNeedLogin).toHaveBeenCalledTimes(1);
+    expect(ctx.onNeedLogin).toHaveBeenCalledWith("/dashboard");
+  });
+
+  it("REQUEST_SESSION_INSTALL without payload → onNeedLogin(undefined)", () => {
+    const ctx = makeCtx();
+    handleInbound(wire({ type: MSG.REQUEST_SESSION_INSTALL }), ctx);
+    expect(ctx.onNeedLogin).toHaveBeenCalledTimes(1);
+    expect(ctx.onNeedLogin).toHaveBeenCalledWith(undefined);
+  });
+
+  it("LOGOUT → onLoggedOut, then inject a LOGOUT_DONE envelope", () => {
+    const ctx = makeCtx();
+    handleInbound(wire({ type: MSG.LOGOUT }), ctx);
+
+    expect(ctx.onLoggedOut).toHaveBeenCalledTimes(1);
+    expect(ctx.inject).toHaveBeenCalledTimes(1);
+
+    // onLoggedOut must run BEFORE inject (clear local session, then notify web).
+    const loggedOutOrder = (ctx.onLoggedOut as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0];
+    const injectOrder = (ctx.inject as ReturnType<typeof vi.fn>).mock.invocationCallOrder[0];
+    expect(loggedOutOrder).toBeLessThan(injectOrder);
+
+    const js = (ctx.inject as ReturnType<typeof vi.fn>).mock.calls[0][0] as string;
+    expect(js).toContain(MSG.LOGOUT_DONE);
+    expect(js.endsWith("true;")).toBe(true);
+  });
+
+  it("OPEN_EXTERNAL → openExternal(url)", () => {
+    const ctx = makeCtx();
+    handleInbound(wire({ type: MSG.OPEN_EXTERNAL, payload: { url: "https://other.example/x" } }), ctx);
+    expect(ctx.openExternal).toHaveBeenCalledTimes(1);
+    expect(ctx.openExternal).toHaveBeenCalledWith("https://other.example/x");
+  });
+
+  it("READY → noop (no callback fired)", () => {
+    const ctx = makeCtx();
+    handleInbound(wire({ type: MSG.READY }), ctx);
+    expect(ctx.onNeedLogin).not.toHaveBeenCalled();
+    expect(ctx.onLoggedOut).not.toHaveBeenCalled();
+    expect(ctx.openExternal).not.toHaveBeenCalled();
+    expect(ctx.inject).not.toHaveBeenCalled();
+  });
+
+  it("AUTH_STATE_CHANGED → v1 noop (no callback fired)", () => {
+    const ctx = makeCtx();
+    handleInbound(wire({ type: MSG.AUTH_STATE_CHANGED, payload: { authenticated: true } }), ctx);
+    expect(ctx.onNeedLogin).not.toHaveBeenCalled();
+    expect(ctx.onLoggedOut).not.toHaveBeenCalled();
+    expect(ctx.openExternal).not.toHaveBeenCalled();
+    expect(ctx.inject).not.toHaveBeenCalled();
+  });
+
+  it("ignores an unknown message type without throwing or calling any callback", () => {
+    const ctx = makeCtx();
+    expect(() =>
+      handleInbound(wire({ type: "TOTALLY_MADE_UP", payload: { x: 1 } }), ctx),
+    ).not.toThrow();
+    expect(ctx.onNeedLogin).not.toHaveBeenCalled();
+    expect(ctx.onLoggedOut).not.toHaveBeenCalled();
+    expect(ctx.openExternal).not.toHaveBeenCalled();
+    expect(ctx.inject).not.toHaveBeenCalled();
+  });
+
+  it("ignores wrong-namespace traffic (ns mismatch → UNKNOWN)", () => {
+    const ctx = makeCtx();
+    handleInbound(
+      JSON.stringify({ ns: "some-other-bridge", v: 1, type: MSG.LOGOUT }),
+      ctx,
+    );
+    expect(ctx.onLoggedOut).not.toHaveBeenCalled();
+    expect(ctx.inject).not.toHaveBeenCalled();
+  });
+
+  it("ignores garbage (non-JSON string, null, number) without throwing", () => {
+    const ctx = makeCtx();
+    expect(() => handleInbound("}{not json", ctx)).not.toThrow();
+    expect(() => handleInbound(null, ctx)).not.toThrow();
+    expect(() => handleInbound(42, ctx)).not.toThrow();
+    expect(ctx.onNeedLogin).not.toHaveBeenCalled();
+    expect(ctx.onLoggedOut).not.toHaveBeenCalled();
+    expect(ctx.openExternal).not.toHaveBeenCalled();
+    expect(ctx.inject).not.toHaveBeenCalled();
+  });
+});
+
+describe("helloInjection", () => {
+  it("produces injectable JS carrying a HELLO envelope, ending in \"true;\"", () => {
+    const js = helloInjection({ appVersion: "2.0.0", platform: "android" });
+    expect(js).toContain(MSG.HELLO);
+    expect(js).toContain("2.0.0");
+    expect(js).toContain("android");
+    expect(js.endsWith("true;")).toBe(true);
+  });
+});

package/templates/workspace/mobile/src/bridge/router.ts

@@ -0,0 +1,89 @@
+/**
+ * 웹→앱 메시지 라우터 — 순수 디스패처.
+ *
+ * Host(웹뷰 onMessage)가 받은 raw 문자열을 그대로 handleInbound에 넘긴다. 라우터는
+ * tolerant reader(readInbound)로 봉투를 해석한 뒤 MSG.* 별로 BridgeContext 콜백을
+ * 호출한다. 부수효과(로그인 UI·로그아웃·외부 링크·주입)는 전부 ctx 콜백으로 위임하므로
+ * 이 파일은 네이티브/expo import가 전혀 없고 Node에서 단위 테스트된다.
+ *
+ * 보안·견고성(DESIGN 결정 15):
+ *  - 토큰은 이 채널을 절대 거치지 않는다(세션은 서버 Set-Cookie 핸드오프).
+ *  - 모르는/깨진 메시지는 readInbound가 UNKNOWN으로 환원 → 여기서 조용히 무시(never throw).
+ */
+import { MSG, SSB_NS, SSB_PROTOCOL_VERSION, type OutboundMessage } from "./contract";
+import { readInbound } from "./reader";
+import { buildHello } from "./capabilities";
+import { buildReceiveInjection } from "./messaging";
+
+/**
+ * 라우터가 부수효과를 위임하는 콜백 묶음. 셸(웹뷰 Host)이 네이티브 구현을 채워 넘긴다.
+ *  - inject       : injectJavaScript 호출(앱→웹 응답 주입).
+ *  - onNeedLogin  : 웹이 세션 없음을 알릴 때 네이티브 로그인 흐름 시작.
+ *  - onLoggedOut  : 웹 로그아웃 시 네이티브 로컬 세션 사본 정리.
+ *  - openExternal : URL을 시스템 브라우저로 열기.
+ */
+export type BridgeContext = {
+  appVersion: string;
+  platform: "ios" | "android";
+  webOrigin: string;
+  inject: (js: string) => void;
+  onNeedLogin: (redirectPath?: string) => void;
+  onLoggedOut: () => void;
+  openExternal: (url: string) => void;
+};
+
+/**
+ * LOGOUT 완료 후 웹에 되돌려줄 LOGOUT_DONE 봉투. payload 없는 단순 ack(계약상 optional).
+ */
+const LOGOUT_DONE_MESSAGE: OutboundMessage = {
+  ns: SSB_NS,
+  v: SSB_PROTOCOL_VERSION,
+  type: MSG.LOGOUT_DONE,
+};
+
+/**
+ * raw(웹→앱 postMessage 문자열 또는 파싱된 객체)를 해석해 적절한 콜백을 호출한다.
+ * readInbound가 tolerant하므로 절대 throw하지 않는다.
+ */
+export function handleInbound(raw: unknown, ctx: BridgeContext): void {
+  const msg = readInbound(raw);
+
+  switch (msg.type) {
+    case MSG.READY:
+      // 핸드셰이크 ack — 별도 동작 없음(셸이 필요 시 재시도 타임아웃을 따로 관리).
+      break;
+
+    case MSG.REQUEST_SESSION_INSTALL:
+      // 웹이 세션 없음을 알림 → 네이티브 로그인 + 세션 설치 흐름 시작.
+      ctx.onNeedLogin(msg.payload?.redirectPath);
+      break;
+
+    case MSG.AUTH_STATE_CHANGED:
+      // v1 noop 훅 — 미래에 네이티브 측 세션 캐시 동기화 등에 쓸 자리.
+      break;
+
+    case MSG.LOGOUT:
+      // 네이티브 로컬 세션 정리 후, 완료를 웹에 LOGOUT_DONE으로 통지.
+      ctx.onLoggedOut();
+      ctx.inject(buildReceiveInjection(LOGOUT_DONE_MESSAGE));
+      break;
+
+    case MSG.OPEN_EXTERNAL:
+      // 외부 URL을 시스템 브라우저로(웹뷰 in-app 내비게이션 아님).
+      ctx.openExternal(msg.payload.url);
+      break;
+
+    case MSG.UNKNOWN:
+    default:
+      // 미지·깨진 메시지는 조용히 무시(DESIGN 결정 15: never-throw tolerant).
+      break;
+  }
+}
+
+/**
+ * HELLO 봉투를 만들어 주입용 JS 소스로 변환한다. 셸은 웹뷰 로드 직후 이 문자열을
+ * injectJavaScript에 넘겨 "나 이런 앱·능력이에요"를 웹에 알린다(DESIGN 결정 8).
+ */
+export function helloInjection(ctx: { appVersion: string; platform: "ios" | "android" }): string {
+  return buildReceiveInjection(buildHello(ctx));
+}

package/templates/workspace/mobile/src/config/env.ts

@@ -0,0 +1,51 @@
+/**
+ * Client-safe configuration for the native shell.
+ *
+ * `EXPO_PUBLIC_*` variables are inlined at BUILD time (not read at runtime), so
+ * changing the URL means a rebuild — never promise "change the URL without
+ * rebuilding". See the eas-deploy-guide skill (환경 모델).
+ *
+ * Guard rationale (see the dev-loop guide): a missing or malformed web URL must
+ * FAIL LOUDLY here, at startup. An unguarded `.replace()` / silent fallback is
+ * how a release ships a blank white screen.
+ */
+
+const rawWebUrl = process.env.EXPO_PUBLIC_WEB_URL;
+
+if (!rawWebUrl) {
+  throw new Error(
+    "[env] EXPO_PUBLIC_WEB_URL is not set. Copy .env.example to .env (local) or set it " +
+      "in the matching eas.json build profile, pointing at your deployed web URL. " +
+      "See the eas-deploy-guide skill.",
+  );
+}
+
+let parsedUrl: URL;
+try {
+  parsedUrl = new URL(rawWebUrl);
+} catch {
+  throw new Error(`[env] EXPO_PUBLIC_WEB_URL is not a valid URL: "${rawWebUrl}"`);
+}
+
+if (parsedUrl.protocol !== "https:" && parsedUrl.hostname !== "localhost" && parsedUrl.hostname !== "10.0.2.2") {
+  // Real devices require https (secure context): camera, Web Crypto, clipboard and
+  // Secure cookies silently break over http on a device. http is only tolerated for
+  // the simulator/emulator shell fast-loop. See the dev-loop guide.
+  throw new Error(
+    `[env] EXPO_PUBLIC_WEB_URL must be https on real devices (got "${rawWebUrl}"). ` +
+      "http is only allowed for localhost / 10.0.2.2 in the simulator.",
+  );
+}
+
+/** The full URL the WebView loads. */
+export const WEB_URL = rawWebUrl;
+
+/** Origin of WEB_URL, used for the link allow-list and bridge origin checks. */
+export const WEB_ORIGIN = parsedUrl.origin;
+
+/**
+ * Origins the WebView is allowed to navigate to in-app. Everything else opens in
+ * the system browser. This array is the single source of truth for the in-app link
+ * allow-list (native-app-guide §링크 경계 explains it). Same-origin is always included.
+ */
+export const ALLOWED_ORIGINS: readonly string[] = [WEB_ORIGIN];

package/templates/workspace/mobile/src/i18n.ts

@@ -0,0 +1,71 @@
+/**
+ * Tiny, dependency-free i18n for the handful of NATIVE strings the shell shows
+ * (loading / error / offline / the login scaffold). Everything else is the web's
+ * own copy, rendered inside the WebView.
+ *
+ * `t()` is tolerant: an unknown key falls back to English, then to the key
+ * itself — a missing translation degrades gracefully instead of crashing.
+ */
+
+type Locale = "ko" | "en";
+
+function detectLocale(): Locale {
+  try {
+    const tag = String(new Intl.DateTimeFormat().resolvedOptions().locale ?? "");
+    return tag.toLowerCase().startsWith("ko") ? "ko" : "en";
+  } catch {
+    return "ko";
+  }
+}
+
+const LOCALE: Locale = detectLocale();
+
+const MESSAGES = {
+  ko: {
+    loading: "불러오는 중…",
+    "error.title": "문제가 발생했어요",
+    "error.body": "잠시 후 다시 시도해 주세요.",
+    "error.retry": "다시 시도",
+    "offline.title": "인터넷에 연결되어 있지 않아요",
+    "offline.body": "연결 상태를 확인한 뒤 다시 시도해 주세요.",
+    "offline.retry": "다시 시도",
+    "login.title": "로그인",
+    "login.continueWithEmail": "이메일로 계속하기",
+    "login.continueWithGoogle": "Google로 계속하기",
+    "login.continueWithApple": "Apple로 계속하기",
+    "login.socialComingSoon": "소셜 로그인은 준비 중입니다",
+    "login.close": "닫기",
+  },
+  en: {
+    loading: "Loading…",
+    "error.title": "Something went wrong",
+    "error.body": "Please try again in a moment.",
+    "error.retry": "Try again",
+    "offline.title": "You're offline",
+    "offline.body": "Check your connection and try again.",
+    "offline.retry": "Try again",
+    "login.title": "Sign in",
+    "login.continueWithEmail": "Continue with email",
+    "login.continueWithGoogle": "Continue with Google",
+    "login.continueWithApple": "Continue with Apple",
+    "login.socialComingSoon": "Social sign-in is coming soon",
+    "login.close": "Close",
+  },
+} as const;
+
+export type I18nKey = keyof (typeof MESSAGES)["en"];
+
+export function getLocale(): Locale {
+  return LOCALE;
+}
+
+export function t(key: I18nKey | (string & {}), params?: Record<string, string | number>): string {
+  const table = MESSAGES[LOCALE] as Record<string, string>;
+  let out = table[key] ?? (MESSAGES.en as Record<string, string>)[key] ?? String(key);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      out = out.replace(new RegExp(`\\{${k}\\}`, "g"), String(v));
+    }
+  }
+  return out;
+}

package/templates/workspace/mobile/src/session/secureSession.ts

@@ -0,0 +1,63 @@
+/**
+ * Secure session mirror (native layer).
+ *
+ * This is a READ-ONLY MIRROR of the web's session for the native shell — NOT the
+ * source of truth. The WEB owns the session and its refresh (see DESIGN decision 5:
+ * the native shell sets `autoRefreshToken: false`; only the web refreshes, so the two
+ * never race on token rotation). The mirror's INTENDED use is to tell, locally and offline,
+ * whether a handoff has already happened — e.g. to skip the login scaffold on a cold start.
+ *
+ * v1 STATUS — scaffold: only `clearAsync()` is wired (from `requestNativeLogout` on a web LOGOUT).
+ * `getAsync`/`setAsync` have NO callers yet, and there is no cold-start session check. The
+ * write-on-handoff / read-on-cold-start behavior lands when native login is wired (DESIGN 12).
+ *
+ * Stored value: an OPAQUE marker the native shell controls (e.g. "installed" or a
+ * non-sensitive id). It is NOT the Supabase access/refresh token — tokens never live
+ * in the native layer and never cross the bridge (contract.ts invariant 5). expo-secure-store
+ * backs this with the iOS Keychain / Android Keystore.
+ *
+ * API verified against node_modules/expo-secure-store (SDK 56):
+ *   getItemAsync(key, options?) → Promise<string | null>   (null when absent)
+ *   setItemAsync(key, value, options?) → Promise<void>      (rejects on failure)
+ *   deleteItemAsync(key, options?) → Promise<void>
+ */
+
+import * as SecureStore from "expo-secure-store";
+
+/** Keychain/Keystore key. Alphanumerics + `.`/`-`/`_` only (SecureStore constraint). */
+const SESSION_KEY = "ssb.session.mirror";
+
+/**
+ * iOS accessibility: readable after the first unlock, this-device-only (never migrated
+ * to a new device via backup). A session marker should not survive a device restore.
+ */
+const OPTIONS: SecureStore.SecureStoreOptions = {
+  keychainAccessible: SecureStore.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY,
+};
+
+export const secureSession = {
+  /** Returns the stored marker, or `null` if none / on any read error. Never throws. */
+  async getAsync(): Promise<string | null> {
+    try {
+      return await SecureStore.getItemAsync(SESSION_KEY, OPTIONS);
+    } catch {
+      // A read failure (e.g. invalidated key) is treated as "no session" — the worst
+      // case is showing login again, which is safe. Never crash the shell over this.
+      return null;
+    }
+  },
+
+  /** Stores/overwrites the marker. */
+  async setAsync(value: string): Promise<void> {
+    await SecureStore.setItemAsync(SESSION_KEY, value, OPTIONS);
+  },
+
+  /** Removes the marker. Idempotent — clearing an absent key is a no-op, never throws. */
+  async clearAsync(): Promise<void> {
+    try {
+      await SecureStore.deleteItemAsync(SESSION_KEY, OPTIONS);
+    } catch {
+      // Deleting a key that does not exist must not surface as an error.
+    }
+  },
+} as const;

package/templates/workspace/mobile/src/session/sessionHandoff.ts

@@ -0,0 +1,151 @@
+/**
+ * Native → web session handoff (DESIGN decision 5).
+ *
+ * Flow (the "secure handoff"):
+ *   1. The native layer obtains a provider credential (Google/Apple `idToken`).
+ *      ── ⚠️ FAST-FOLLOW: acquiring that idToken (native Google/Apple sign-in) is NOT
+ *         wired in v1 (DESIGN decision 12). The plumbing below is fully implemented and
+ *         tested, but has no caller yet — `LoginScreen` routes users to the web's own
+ *         email/password login instead. See the store-release-guide skill for the wire-up.
+ *   2. We POST { provider, idToken } to `${WEB_ORIGIN}/auth/app-bridge`. The web verifies
+ *      the credential server-side, signs the user in, and mints a ONE-TIME exchange NONCE.
+ *   3. We return a `handoffUrl` of the form `${WEB_URL}<path>?code=<nonce>`. The WebView
+ *      loads it; the web route exchanges the nonce and responds with `Set-Cookie` + a 303
+ *      redirect, installing a normal @supabase/ssr session cookie.
+ *
+ * Why a nonce and not the token:
+ *   - The `code` is a SHORT-LIVED, SINGLE-USE exchange nonce — NOT the session token.
+ *   - A `?token=<jwt>` URL would leak the actual session in history/logs/referrers
+ *     (DESIGN correction 2). The token is set as a cookie server-side and NEVER appears
+ *     in a URL, and NEVER crosses the app↔web message bridge (contract.ts invariant 5).
+ *
+ * The web route (`POST /auth/app-bridge` + the nonce-exchange GET) is installed into the
+ * web project from docs/web-adapter; it is not part of this app.
+ */
+
+import { WEB_ORIGIN, WEB_URL } from "../config/env";
+
+/** Where the web mints the nonce (POST). Relative to WEB_ORIGIN. */
+const APP_BRIDGE_PATH = "/auth/app-bridge";
+
+/** Where the web exchanges the one-time nonce for a session cookie (GET) — see docs/web-adapter. */
+const CONSUME_PATH = "/auth/app-bridge/consume";
+
+/** Default landing path after the cookie is installed, if the caller gives none. */
+const DEFAULT_REDIRECT_PATH = "/";
+
+export type HandoffResult =
+  | { ok: true; handoffUrl: string }
+  | { ok: false; reason: string };
+
+/**
+ * Exchange a verified native credential for a one-time handoff URL the WebView can load.
+ *
+ * @param args.provider     Which native provider minted the idToken.
+ * @param args.idToken      The OIDC id token from the native sign-in (verified server-side).
+ * @param args.redirectPath Optional in-web path to land on after the cookie is set.
+ * @returns `{ ok: true, handoffUrl }` on success, otherwise `{ ok: false, reason }`.
+ *
+ * NOTE: fully implemented, but UNCALLED in v1 (see file header — native idToken acquisition
+ * is the fast-follow). Tokens never cross the bridge; only the nonce does, in the URL.
+ */
+export async function requestSessionHandoff(args: {
+  provider: "google" | "apple";
+  idToken: string;
+  redirectPath?: string;
+}): Promise<HandoffResult> {
+  const { provider, idToken, redirectPath } = args;
+
+  if (!idToken) {
+    return { ok: false, reason: "missing-id-token" };
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(`${WEB_ORIGIN}${APP_BRIDGE_PATH}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ provider, idToken }),
+    });
+  } catch {
+    // Network error / DNS / offline: surface a stable reason, never throw.
+    return { ok: false, reason: "network-error" };
+  }
+
+  if (!response.ok) {
+    return { ok: false, reason: `server-${response.status}` };
+  }
+
+  let data: unknown;
+  try {
+    data = await response.json();
+  } catch {
+    return { ok: false, reason: "invalid-response" };
+  }
+
+  const handoffUrl = buildHandoffUrl(data, redirectPath ?? DEFAULT_REDIRECT_PATH);
+  if (!handoffUrl) {
+    return { ok: false, reason: "invalid-handoff" };
+  }
+
+  return { ok: true, handoffUrl };
+}
+
+/**
+ * Native logout: forget the local session mirror.
+ *
+ * This only clears the NATIVE copy. The authoritative web `signOut` (cookie + Supabase
+ * session) happens via the LOGOUT bridge message handled by the web page — see
+ * src/bridge/router.ts (`onLoggedOut` → LOGOUT_DONE). Logout unwinds BOTH sides
+ * (DESIGN decision 5): the web clears the cookie, the native shell clears this mirror.
+ */
+export async function requestNativeLogout(): Promise<void> {
+  // Imported lazily-by-path to keep this module's surface focused on handoff plumbing.
+  const { secureSession } = await import("./secureSession");
+  await secureSession.clearAsync();
+}
+
+/** Read a non-empty string field off an unknown JSON object. */
+function pickString(data: unknown, key: string): string | null {
+  if (typeof data !== "object" || data === null) return null;
+  const value = (data as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Turn the server response into the on-origin URL the WebView should load.
+ *
+ * The web (docs/web-adapter) owns the consume route + how the nonce is carried, so we
+ * PREFER the server-returned `handoffUrl` (e.g. `/auth/app-bridge/consume?code=<nonce>`)
+ * and fall back to composing `${CONSUME_PATH}?code=<nonce>` from a bare `code`/`nonce`.
+ * The post-cookie landing path travels as `next` (path-only). Everything is resolved
+ * against WEB_ORIGIN and rejected if it would leave the web origin — only the one-time
+ * nonce is ever in the URL, never the session token (DESIGN correction 2).
+ */
+function buildHandoffUrl(data: unknown, redirectPath: string): string | null {
+  const next =
+    redirectPath.startsWith("/") && !redirectPath.startsWith("//") ? redirectPath : DEFAULT_REDIRECT_PATH;
+
+  let url: URL;
+  const serverHandoff = pickString(data, "handoffUrl");
+  if (serverHandoff) {
+    try {
+      url = new URL(serverHandoff, WEB_URL);
+    } catch {
+      return null;
+    }
+  } else {
+    const code = pickString(data, "code") ?? pickString(data, "nonce");
+    if (!code) return null;
+    try {
+      url = new URL(CONSUME_PATH, WEB_URL);
+    } catch {
+      return null;
+    }
+    url.searchParams.set("code", code);
+  }
+
+  if (url.origin !== WEB_ORIGIN) return null;
+  if (!url.searchParams.has("next")) url.searchParams.set("next", next);
+  return url.toString();
+}

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

@@ -0,0 +1,75 @@
+import React from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+
+import { t } from "../i18n";
+
+export type ErrorViewProps = {
+  /** 재시도 콜백 — 셸은 보통 웹뷰 key를 증가시켜 통째 재로드한다. */
+  onRetry: () => void;
+  /** 선택적 상세 메시지(HTTP 코드·네트워크 설명 등). 없으면 i18n 기본 본문. */
+  message?: string;
+};
+
+/**
+ * 로드 실패(네트워크/HTTP 오류) 시 웹뷰 위에 덮는 에러 오버레이 (DESIGN 결정 21: 에러 화면).
+ *
+ * onError / onHttpError가 호출하며, "다시 시도" 버튼은 onRetry로 위임한다. 본문은 선택적
+ * message(있으면 우선) → 없으면 i18n 기본 문구. 모든 사용자 노출 문구는 t()를 거친다.
+ */
+export function ErrorView(props: ErrorViewProps): React.JSX.Element {
+  const { onRetry, message } = props;
+  return (
+    <View style={styles.fill}>
+      <Text style={styles.title}>{t("error.title")}</Text>
+      <Text style={styles.body}>{message ?? t("error.body")}</Text>
+      <Pressable
+        onPress={onRetry}
+        accessibilityRole="button"
+        style={({ pressed }) => [styles.button, pressed && styles.buttonPressed]}
+      >
+        <Text style={styles.buttonLabel}>{t("error.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/ui/LoadingView.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { ActivityIndicator, Platform, StyleSheet, Text, View } from "react-native";
+
+import { t } from "../i18n";
+
+/**
+ * 첫 페이지가 그려지기 전까지 웹뷰 위에 덮어두는 로딩 오버레이 (DESIGN 결정 21: 로딩 화면).
+ *
+ * absolute-fill 흰 배경이라 웹뷰가 그리는 동안의 깜빡임/빈 화면을 가린다. 스피너 아래에
+ * i18n 문구를 두어 "멈춘 게 아님"을 알린다. 색은 중립 회색 — 스타터의 기본값이며 브랜드
+ * 색이 정해지면 이 한 곳만 바꾸면 된다.
+ */
+export function LoadingView(): React.JSX.Element {
+  return (
+    <View style={styles.fill} accessibilityRole="progressbar" accessibilityLabel={t("loading")}>
+      <ActivityIndicator size={Platform.OS === "ios" ? "large" : 40} color="#111" />
+      <Text style={styles.label}>{t("loading")}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  fill: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: "#fff",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  label: {
+    marginTop: 12,
+    fontSize: 13,
+    color: "#666",
+  },
+});