create-saas-starter-workspace 0.1.0

package/templates/workspace/mobile/src/auth/LoginScreen.tsx

@@ -0,0 +1,192 @@
+/**
+ * Login scaffold (DESIGN decisions 5 & 12).
+ *
+ * v1 login is intentionally a GENERIC SHELL:
+ *   - PRIMARY: "Continue with email" dismisses this Modal and hands the user to the WEB's
+ *     own email/password screen inside the WebView (the web owns auth UI; the shell does
+ *     not duplicate it).
+ *   - SOCIAL (Google / Apple): native one-click sign-in is a FAST-FOLLOW (DESIGN 12), so
+ *     these buttons are present but DISABLED, labelled "coming soon". When you wire them,
+ *     they will call `requestSessionHandoff` (src/session/sessionHandoff.ts) with a native
+ *     idToken and load the returned handoffUrl. See the per-button comments + the store-release-guide skill.
+ *
+ * Apple's 4.8 rule: once a third-party social login (Google) is wired, "Sign in with Apple"
+ * must be offered too — that's why both buttons live here from day one (Apple shown on iOS
+ * only). All user-facing copy goes through i18n `t()`.
+ */
+
+import React from "react";
+import { Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { t } from "../i18n";
+
+interface LoginScreenProps {
+  /** Whether the login Modal is shown. */
+  visible: boolean;
+  /** Dismiss without signing in (close button / Android back / swipe). */
+  onClose: () => void;
+  /** Proceed with email login inside the WebView (dismiss + let the web show its login). */
+  onContinueInWebView: () => void;
+}
+
+export function LoginScreen({ visible, onClose, onContinueInWebView }: LoginScreenProps): React.JSX.Element {
+  // Apple's "Sign in with Apple" is iOS-only; on Android we simply omit it.
+  const showApple = Platform.OS === "ios";
+
+  return (
+    <Modal visible={visible} transparent animationType="slide" onRequestClose={onClose}>
+      {/* Dimmed backdrop; tapping it dismisses, matching the close affordance. */}
+      <Pressable style={styles.backdrop} onPress={onClose} accessibilityRole="button">
+        {/* Absorb taps inside the sheet so they don't reach the backdrop and dismiss. */}
+        <Pressable style={styles.sheet} onPress={() => {}}>
+          <Text style={styles.title}>{t("login.title")}</Text>
+
+          <View style={styles.spacer} />
+
+          {/* PRIMARY — email login lives in the web. Dismiss and let the WebView show it. */}
+          <Pressable
+            style={styles.primaryButton}
+            onPress={() => {
+              onClose();
+              onContinueInWebView();
+            }}
+            accessibilityRole="button"
+            accessibilityLabel={t("login.continueWithEmail")}
+          >
+            <Text style={styles.primaryLabel}>{t("login.continueWithEmail")}</Text>
+          </Pressable>
+
+          <View style={styles.gap} />
+
+          {/*
+           * FAST-FOLLOW — native Google one-click sign-in.
+           * To wire: acquire a Google idToken natively, then
+           *   const r = await requestSessionHandoff({ provider: "google", idToken });
+           *   if (r.ok) // load r.handoffUrl in the WebView (server sets the cookie via the nonce)
+           * Console/credential setup (OAuth client ids, SHA-1, reversed URL scheme): the store-release-guide skill.
+           */}
+          <Pressable
+            style={[styles.socialButton, styles.disabled]}
+            disabled
+            accessibilityRole="button"
+            accessibilityState={{ disabled: true }}
+            accessibilityLabel={`${t("login.continueWithGoogle")} — ${t("login.socialComingSoon")}`}
+          >
+            <Text style={styles.socialLabel}>{t("login.continueWithGoogle")}</Text>
+            <Text style={styles.comingSoon}>{t("login.socialComingSoon")}</Text>
+          </Pressable>
+
+          {showApple ? (
+            <>
+              <View style={styles.gap} />
+              {/*
+               * FAST-FOLLOW — native "Sign in with Apple" (iOS only; Apple 4.8 companion to Google).
+               * To wire: acquire an Apple identity token natively, then
+               *   const r = await requestSessionHandoff({ provider: "apple", idToken });
+               *   if (r.ok) // load r.handoffUrl in the WebView.
+               * Apple Services ID / nonce / KR server-to-server endpoint: the store-release-guide skill.
+               */}
+              <Pressable
+                style={[styles.socialButton, styles.disabled]}
+                disabled
+                accessibilityRole="button"
+                accessibilityState={{ disabled: true }}
+                accessibilityLabel={`${t("login.continueWithApple")} — ${t("login.socialComingSoon")}`}
+              >
+                <Text style={styles.socialLabel}>{t("login.continueWithApple")}</Text>
+                <Text style={styles.comingSoon}>{t("login.socialComingSoon")}</Text>
+              </Pressable>
+            </>
+          ) : null}
+
+          <View style={styles.spacer} />
+
+          {/* Close — dismiss the scaffold without signing in. */}
+          <Pressable
+            style={styles.closeButton}
+            onPress={onClose}
+            accessibilityRole="button"
+            accessibilityLabel={t("login.close")}
+          >
+            <Text style={styles.closeLabel}>{t("login.close")}</Text>
+          </Pressable>
+        </Pressable>
+      </Pressable>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: "rgba(0, 0, 0, 0.4)",
+    justifyContent: "flex-end",
+  },
+  sheet: {
+    backgroundColor: "#ffffff",
+    borderTopLeftRadius: 20,
+    borderTopRightRadius: 20,
+    paddingHorizontal: 24,
+    paddingTop: 24,
+    paddingBottom: 36,
+  },
+  title: {
+    fontSize: 22,
+    fontWeight: "700",
+    color: "#111111",
+    textAlign: "center",
+  },
+  spacer: {
+    height: 20,
+  },
+  gap: {
+    height: 12,
+  },
+  primaryButton: {
+    width: "100%",
+    height: 52,
+    borderRadius: 12,
+    backgroundColor: "#111111",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  primaryLabel: {
+    color: "#ffffff",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  socialButton: {
+    width: "100%",
+    minHeight: 52,
+    borderRadius: 12,
+    borderWidth: 1,
+    borderColor: "#dddddd",
+    backgroundColor: "#ffffff",
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: 8,
+  },
+  socialLabel: {
+    color: "#111111",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  comingSoon: {
+    marginTop: 2,
+    color: "#999999",
+    fontSize: 12,
+  },
+  disabled: {
+    opacity: 0.55,
+  },
+  closeButton: {
+    width: "100%",
+    height: 44,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  closeLabel: {
+    color: "#666666",
+    fontSize: 15,
+    fontWeight: "500",
+  },
+});

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { APP_CAPABILITIES, buildHello } from "./capabilities";
+import { MSG, OutboundSchema, SSB_NS, SSB_PROTOCOL_VERSION } from "./contract";
+
+describe("APP_CAPABILITIES", () => {
+  it("advertises exactly the v1 capability set", () => {
+    expect(APP_CAPABILITIES).toEqual(["session.v1", "external-links.v1"]);
+  });
+});
+
+describe("buildHello", () => {
+  it("returns a valid HELLO OutboundMessage that parses against OutboundSchema", () => {
+    const hello = buildHello({ appVersion: "1.2.3", platform: "ios" });
+
+    const parsed = OutboundSchema.safeParse(hello);
+    expect(parsed.success).toBe(true);
+
+    expect(hello.type).toBe(MSG.HELLO);
+    expect(hello.ns).toBe(SSB_NS);
+    expect(hello.v).toBe(SSB_PROTOCOL_VERSION);
+  });
+
+  it("carries the protocol version, capabilities, appVersion and platform in the payload", () => {
+    const hello = buildHello({ appVersion: "9.9.9", platform: "android" });
+
+    // type-narrowed via the parsed result so payload is typed.
+    const parsed = OutboundSchema.parse(hello);
+    expect(parsed.type).toBe(MSG.HELLO);
+    if (parsed.type !== MSG.HELLO) throw new Error("expected HELLO");
+
+    expect(parsed.payload.protocolVersion).toBe(SSB_PROTOCOL_VERSION);
+    expect(parsed.payload.capabilities).toEqual(["session.v1", "external-links.v1"]);
+    expect(parsed.payload.appVersion).toBe("9.9.9");
+    expect(parsed.payload.platform).toBe("android");
+  });
+
+  it("copies capabilities (does not hand out the readonly source array)", () => {
+    const hello = buildHello({ appVersion: "1.0.0", platform: "ios" });
+    if (hello.type !== MSG.HELLO) throw new Error("expected HELLO");
+
+    expect(hello.payload.capabilities).not.toBe(APP_CAPABILITIES);
+    expect(hello.payload.capabilities).toEqual([...APP_CAPABILITIES]);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * 이 네이티브 셸이 handshake(HELLO)로 광고하는 capability 토큰 목록.
+ *
+ * 웹은 버전 숫자가 아니라 이 목록으로 기능을 게이트한다(DESIGN 결정 8·15: capabilities
+ * 배열로 feature-detect, 버전 분기 금지). 목록은 ADDITIVE-ONLY: 토큰을 추가만 하고
+ * 절대 제거·이름변경하지 않는다 → 구버전 앱(적은 토큰)이 최신 웹에서, 신버전 앱이
+ * 구버전 웹에서 모두 안전하게 동작한다.
+ *
+ *  - session.v1        : 네이티브 로그인 → 서버 Set-Cookie 세션 핸드오프(REQUEST_SESSION_INSTALL).
+ *  - external-links.v1 : 외부 URL을 시스템 브라우저로 여는 능력(OPEN_EXTERNAL).
+ *
+ * 새 네이티브 능력(예: push.v1)을 추가할 때 여기에 토큰을 append 하고, 웹은
+ * hasCapability("push.v1") 게이트 뒤에서만 그 기능을 쓴다.
+ */
+import { MSG, SSB_NS, SSB_PROTOCOL_VERSION, type OutboundMessage } from "./contract";
+
+/** v1 capability 집합. Append-only. */
+export const APP_CAPABILITIES: readonly string[] = ["session.v1", "external-links.v1"] as const;
+
+/**
+ * HELLO 봉투를 만든다. 앱은 웹뷰가 로드되자마자 이 메시지를 주입해
+ * "나 이런 앱이고 이런 능력이 있어요"를 웹에 알린다(DESIGN 결정 8).
+ *
+ * 순수 함수 — 네이티브 import 없음. appVersion·platform은 호출부(셸)가 넘긴다.
+ */
+export function buildHello(args: {
+  appVersion: string;
+  platform: "ios" | "android";
+}): OutboundMessage {
+  return {
+    ns: SSB_NS,
+    v: SSB_PROTOCOL_VERSION,
+    type: MSG.HELLO,
+    payload: {
+      protocolVersion: SSB_PROTOCOL_VERSION,
+      // 광고 시점에 배열 복사를 넘겨 외부에서 readonly 원본을 변형하지 못하게 한다.
+      capabilities: [...APP_CAPABILITIES],
+      appVersion: args.appVersion,
+      platform: args.platform,
+    },
+  };
+}

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

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { InboundSchema, OutboundSchema, SSB_NS, SSB_PROTOCOL_VERSION, MSG } from "./contract";
+
+describe("bridge contract", () => {
+  it("namespace + protocol constants are stable", () => {
+    expect(SSB_NS).toBe("ssb");
+    expect(SSB_PROTOCOL_VERSION).toBe(1);
+  });
+
+  it("InboundSchema accepts AUTH_STATE_CHANGED with a boolean payload", () => {
+    const r = InboundSchema.safeParse({
+      ns: "ssb",
+      v: 1,
+      type: MSG.AUTH_STATE_CHANGED,
+      payload: { authenticated: true },
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("InboundSchema rejects a foreign namespace", () => {
+    const r = InboundSchema.safeParse({ ns: "nope", v: 1, type: MSG.READY });
+    expect(r.success).toBe(false);
+  });
+
+  it("InboundSchema rejects AUTH_STATE_CHANGED with a missing payload", () => {
+    const r = InboundSchema.safeParse({ ns: "ssb", v: 1, type: MSG.AUTH_STATE_CHANGED });
+    expect(r.success).toBe(false);
+  });
+
+  it("OutboundSchema accepts a well-formed HELLO", () => {
+    const r = OutboundSchema.safeParse({
+      ns: "ssb",
+      v: 1,
+      type: MSG.HELLO,
+      payload: { protocolVersion: 1, capabilities: ["session.v1"], appVersion: "1.0.0", platform: "ios" },
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("OutboundSchema rejects an invalid platform", () => {
+    const r = OutboundSchema.safeParse({
+      ns: "ssb",
+      v: 1,
+      type: MSG.HELLO,
+      payload: { protocolVersion: 1, capabilities: [], appVersion: "1.0.0", platform: "windows" },
+    });
+    expect(r.success).toBe(false);
+  });
+});

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

@@ -0,0 +1,146 @@
+import { z } from "zod";
+
+/**
+ * App ↔ Web bridge contract — SINGLE SOURCE OF TRUTH.
+ *
+ * This file is copied byte-for-byte into the web project (docs/web-adapter/contract.ts).
+ * The two MUST stay identical; the web adapter ships a checksum check to enforce it.
+ *
+ * Invariants (never break these):
+ *  1. Every message is namespaced (`ns: "ssb"`) so unrelated postMessage traffic on
+ *     the page is ignored.
+ *  2. The contract is ADDITIVE-ONLY. Add new message `type`s or new OPTIONAL payload
+ *     fields; never remove a type, rename one, or make an existing field required.
+ *     Old apps must keep working against new webs and vice-versa.
+ *  3. Features are gated by HELLO `capabilities` (a string array), NOT by version
+ *     number. The app advertises what it can do; the web feature-detects.
+ *  4. The reader (reader.ts) is tolerant: anything unrecognized becomes UNKNOWN and
+ *     never throws.
+ *  5. Auth tokens NEVER travel over this channel. Session handoff is a server
+ *     Set-Cookie via a one-time nonce (see src/session + docs/web-adapter).
+ */
+
+export const SSB_NS = "ssb" as const;
+export const SSB_PROTOCOL_VERSION = 1 as const;
+
+/** All message type names. Add here (append-only) when extending the contract. */
+export const MSG = {
+  // ── app → web ──
+  /** App announces itself + capabilities as soon as the page is reachable. */
+  HELLO: "HELLO",
+  /** App confirms a web session cookie was installed (after native login handoff). */
+  SESSION_INSTALLED: "SESSION_INSTALLED",
+  /** App confirms it cleared its local session copy after a logout. */
+  LOGOUT_DONE: "LOGOUT_DONE",
+  /** Forward-compat only — push is a fast-follow; defined so the web can feature-detect later. */
+  PUSH_TOKEN_UPDATED: "PUSH_TOKEN_UPDATED",
+
+  // ── web → app ──
+  /** Web acknowledges the bridge is live (handshake completes). */
+  READY: "READY",
+  /** Web has no session and asks the app to run native login + install a session. */
+  REQUEST_SESSION_INSTALL: "REQUEST_SESSION_INSTALL",
+  /** Web tells the app its auth state changed (e.g. user logged in/out inside the webview). */
+  AUTH_STATE_CHANGED: "AUTH_STATE_CHANGED",
+  /** Web asks the app to forget the session (user logged out). */
+  LOGOUT: "LOGOUT",
+  /** Web asks the app to open a URL in the system browser instead of the webview. */
+  OPEN_EXTERNAL: "OPEN_EXTERNAL",
+
+  // ── reader fallback (not a wire message) ──
+  UNKNOWN: "UNKNOWN",
+} as const;
+
+export type MessageType = (typeof MSG)[keyof typeof MSG];
+
+/** Fields shared by every envelope. */
+const envelopeBase = {
+  ns: z.literal(SSB_NS),
+  v: z.number().int(),
+  /** Correlation id, present on request/response pairs. */
+  id: z.string().optional(),
+};
+
+// ───────────────────────── web → app (inbound) ─────────────────────────
+const ReadyMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.READY),
+  payload: z.object({}).optional(),
+});
+
+const RequestSessionInstallMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.REQUEST_SESSION_INSTALL),
+  payload: z.object({ redirectPath: z.string().optional() }).optional(),
+});
+
+const AuthStateChangedMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.AUTH_STATE_CHANGED),
+  payload: z.object({ authenticated: z.boolean() }),
+});
+
+const LogoutMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.LOGOUT),
+  payload: z.object({}).optional(),
+});
+
+const OpenExternalMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.OPEN_EXTERNAL),
+  payload: z.object({ url: z.string() }),
+});
+
+export const InboundSchema = z.discriminatedUnion("type", [
+  ReadyMessage,
+  RequestSessionInstallMessage,
+  AuthStateChangedMessage,
+  LogoutMessage,
+  OpenExternalMessage,
+]);
+export type InboundMessage = z.infer<typeof InboundSchema>;
+
+// ───────────────────────── app → web (outbound) ─────────────────────────
+const HelloMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.HELLO),
+  payload: z.object({
+    protocolVersion: z.number().int(),
+    capabilities: z.array(z.string()),
+    appVersion: z.string(),
+    platform: z.enum(["ios", "android"]),
+  }),
+});
+
+const SessionInstalledMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.SESSION_INSTALLED),
+  payload: z.object({ ok: z.boolean() }),
+});
+
+const LogoutDoneMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.LOGOUT_DONE),
+  payload: z.object({}).optional(),
+});
+
+const PushTokenUpdatedMessage = z.object({
+  ...envelopeBase,
+  type: z.literal(MSG.PUSH_TOKEN_UPDATED),
+  payload: z.object({ token: z.string() }),
+});
+
+export const OutboundSchema = z.discriminatedUnion("type", [
+  HelloMessage,
+  SessionInstalledMessage,
+  LogoutDoneMessage,
+  PushTokenUpdatedMessage,
+]);
+export type OutboundMessage = z.infer<typeof OutboundSchema>;
+
+/**
+ * The tolerant reader's fallback shape. Not a valid wire message — produced only
+ * when an inbound payload cannot be understood. See reader.ts.
+ */
+export type UnknownMessage = { type: typeof MSG.UNKNOWN; raw: unknown };

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

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { buildReceiveInjection } from "./messaging";
+import { MSG, SSB_NS, SSB_PROTOCOL_VERSION, type OutboundMessage } from "./contract";
+
+const helloMsg: OutboundMessage = {
+  ns: SSB_NS,
+  v: SSB_PROTOCOL_VERSION,
+  type: MSG.HELLO,
+  payload: {
+    protocolVersion: SSB_PROTOCOL_VERSION,
+    capabilities: ["session.v1"],
+    appVersion: "1.0.0",
+    platform: "ios",
+  },
+};
+
+describe("buildReceiveInjection", () => {
+  it("embeds the envelope as JSON in the injected source", () => {
+    const js = buildReceiveInjection(helloMsg);
+    expect(js).toContain(JSON.stringify(helloMsg));
+  });
+
+  it("ends with \"true;\" so injectJavaScript has a clean return value", () => {
+    const js = buildReceiveInjection(helloMsg);
+    expect(js.endsWith("true;")).toBe(true);
+  });
+
+  it("delivers via both __ssbBridge.receive and the ssb:message CustomEvent, wrapped in try/catch", () => {
+    const js = buildReceiveInjection(helloMsg);
+    expect(js).toContain("window.__ssbBridge");
+    expect(js).toContain(".receive(");
+    expect(js).toContain('new CustomEvent("ssb:message"');
+    expect(js.startsWith("try{")).toBe(true);
+    expect(js).toContain("catch");
+  });
+
+  it("escapes embedded quotes so the source stays valid JS", () => {
+    const msg: OutboundMessage = {
+      ns: SSB_NS,
+      v: SSB_PROTOCOL_VERSION,
+      type: MSG.PUSH_TOKEN_UPDATED,
+      payload: { token: 'tok"with"quotes' },
+    };
+    const js = buildReceiveInjection(msg);
+    // JSON.stringify escapes the inner quotes; the raw unescaped substring must not appear.
+    expect(js).toContain(JSON.stringify(msg));
+    expect(js).not.toContain('tok"with"quotes');
+  });
+});

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

@@ -0,0 +1,33 @@
+/**
+ * 앱→웹 전달(delivery) — 순수 JS 소스 빌더.
+ *
+ * 전달 규약(아키텍처 계약): 앱은 OutboundMessage 봉투를 웹뷰에 주입(injectJavaScript)하고,
+ * 그 JS가 두 경로로 웹에 봉투를 흘려보낸다.
+ *   1. window.__ssbBridge?.receive(envelope)            — 웹 어댑터가 설치한 콜백(있으면).
+ *   2. window.dispatchEvent(CustomEvent("ssb:message"))  — 어댑터 없이도 듣는 일반 이벤트 경로.
+ * 둘 다 try/catch로 감싸 어느 한쪽이 없거나 던져도 무해하게 무시한다.
+ *
+ * injectJavaScript에 넘기는 소스는 마지막 평가값이 명확해야 iOS WKWebView 경고를 피하므로
+ * 반드시 "true;"로 끝낸다(react-native-webview 권장 패턴).
+ *
+ * 순수 함수 — 네이티브 import 없음. 셸은 결과 문자열을 webRef.injectJavaScript()에 넘긴다.
+ */
+import type { OutboundMessage } from "./contract";
+
+/**
+ * OutboundMessage → injectJavaScript용 JS 소스.
+ *
+ * 봉투는 JSON.stringify로 직렬화해 JS 리터럴로 박는다(따옴표·역슬래시 자동 이스케이프).
+ * 웹의 두 수신 경로(__ssbBridge.receive / "ssb:message" CustomEvent)에 같은 객체를 전달.
+ */
+export function buildReceiveInjection(msg: OutboundMessage): string {
+  const json = JSON.stringify(msg);
+  return (
+    "try{" +
+    `var m=${json};` +
+    "window.__ssbBridge&&window.__ssbBridge.receive(m);" +
+    'window.dispatchEvent(new CustomEvent("ssb:message",{detail:m}));' +
+    "}catch(e){}" +
+    " true;"
+  );
+}

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

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { readInbound } from "./reader";
+import { SSB_NS, SSB_PROTOCOL_VERSION, MSG } from "./contract";
+
+const wire = (type: string, payload?: unknown, extra?: Record<string, unknown>) =>
+  JSON.stringify({ ns: SSB_NS, v: SSB_PROTOCOL_VERSION, type, payload, ...extra });
+
+describe("readInbound — tolerant reader", () => {
+  it("parses a valid READY message", () => {
+    expect(readInbound(wire(MSG.READY)).type).toBe(MSG.READY);
+  });
+
+  it("parses OPEN_EXTERNAL and exposes the url", () => {
+    const r = readInbound(wire(MSG.OPEN_EXTERNAL, { url: "https://example.com" }));
+    expect(r.type).toBe(MSG.OPEN_EXTERNAL);
+    if (r.type === MSG.OPEN_EXTERNAL) expect(r.payload.url).toBe("https://example.com");
+  });
+
+  it("accepts an already-parsed object, not just a JSON string", () => {
+    expect(readInbound({ ns: SSB_NS, v: 1, type: MSG.LOGOUT }).type).toBe(MSG.LOGOUT);
+  });
+
+  it("rejects a foreign namespace as UNKNOWN", () => {
+    expect(readInbound(JSON.stringify({ ns: "other", v: 1, type: MSG.READY })).type).toBe(MSG.UNKNOWN);
+  });
+
+  it("treats OPEN_EXTERNAL without a url as UNKNOWN (missing required field)", () => {
+    expect(readInbound(wire(MSG.OPEN_EXTERNAL, {})).type).toBe(MSG.UNKNOWN);
+  });
+
+  it("treats an unknown future type as UNKNOWN (forward-compat)", () => {
+    expect(readInbound(wire("SOME_FUTURE_THING")).type).toBe(MSG.UNKNOWN);
+  });
+
+  it("treats malformed JSON as UNKNOWN and never throws", () => {
+    expect(() => readInbound("{not json")).not.toThrow();
+    expect(readInbound("{not json").type).toBe(MSG.UNKNOWN);
+  });
+
+  it("handles non-string, non-object input", () => {
+    expect(readInbound(42).type).toBe(MSG.UNKNOWN);
+    expect(readInbound(null).type).toBe(MSG.UNKNOWN);
+    expect(readInbound(undefined).type).toBe(MSG.UNKNOWN);
+    expect(readInbound([]).type).toBe(MSG.UNKNOWN);
+  });
+
+  it("preserves the raw input on UNKNOWN", () => {
+    const r = readInbound("garbage");
+    expect(r.type).toBe(MSG.UNKNOWN);
+    if (r.type === MSG.UNKNOWN) expect(r.raw).toBe("garbage");
+  });
+});

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

@@ -0,0 +1,31 @@
+import { InboundSchema, MSG, type InboundMessage, type UnknownMessage } from "./contract";
+
+export type ReadResult = InboundMessage | UnknownMessage;
+
+/**
+ * Tolerant reader for messages arriving FROM the web (WebView `onMessage`).
+ *
+ * Hard contract: this function NEVER throws. Anything it cannot confidently
+ * understand — wrong namespace, non-JSON string, unknown `type`, missing/invalid
+ * fields, a number, null — collapses to `{ type: "UNKNOWN", raw }`. The native
+ * shell must survive hostile, outdated, or unrelated postMessage traffic.
+ *
+ * `raw` is whatever `event.nativeEvent.data` gave us (usually a JSON string, but
+ * a parsed object is accepted too).
+ */
+export function readInbound(raw: unknown): ReadResult {
+  let candidate: unknown = raw;
+
+  if (typeof raw === "string") {
+    try {
+      candidate = JSON.parse(raw);
+    } catch {
+      return { type: MSG.UNKNOWN, raw };
+    }
+  }
+
+  const parsed = InboundSchema.safeParse(candidate);
+  if (parsed.success) return parsed.data;
+
+  return { type: MSG.UNKNOWN, raw };
+}