@pylonsync/create-pylon 0.9.0 → 0.9.2

package/templates/expo/mobile/apps/expo/README.md

@@ -15,9 +15,16 @@ src/session.tsx            boot + state machine
 src/purchases.ts           RevenueCat wrapper, safe in Expo Go
 src/entitlements.ts        usePro() from the synced RcEntitlement rows
 src/analytics.ts           funnel events; wire to your SDK in one place
+src/links.ts               privacy / terms / support URLs, served by apps/api
 STORE.md                   the submission checklist
 ```
 
+The public website (landing page, `/privacy`, `/terms`, `/support`) is served
+by the backend in `apps/api`, on the same host as the API. The links in
+Settings and under the paywall point there with no configuration, which is
+what makes the store requirement satisfiable from a fresh scaffold. Edit its
+copy in `apps/api/lib/site.ts`.
+
 ## Run
 
 ```bash
@@ -26,8 +33,34 @@ bun run dev          # Expo Go: everything except native sign-in and purchases
 eas build --profile development --platform ios && bun run dev   # dev build: everything
 ```
 
-The backend must be running (`cd ../api && bun run dev`) or deployed
-(`EXPO_PUBLIC_PYLON_BASE_URL` in `.env`).
+The backend must be running (`cd ../api && bun run dev`, port 4321) or
+deployed (`EXPO_PUBLIC_PYLON_BASE_URL` in `.env`). An Android emulator
+reaches the host machine at `http://10.0.2.2:4321`; `src/pylon.ts` uses
+that when the variable is unset.
+
+`bun run check` typechecks. `bun run check:bundle` exports the iOS and
+Android bundles without a device; run it after changing dependencies.
+
+Adding an Expo native module (a package with `ios/` or `android/`) needs a
+new development build (`eas build --profile development`). The Metro
+server can keep running.
+
+## Replace the demo
+
+The Notes screens are placeholders. When you replace them, these files
+also carry Notes-specific copy or logic:
+
+- `app/(onboarding)/welcome.tsx`: the three slides.
+- `app/(auth)/sign-in.tsx`: the line under the title.
+- `app/paywall.tsx`: `BENEFITS` and the reason text.
+- `app/(tabs)/settings.tsx`: the delete-account confirmation.
+- `app/(tabs)/index.tsx`: the list, `FREE_LIMIT`, and the sign-in nudge.
+- `app.config.ts`: `name`, `slug`, `scheme`, and the icons in `assets/`.
+- `apps/api/lib/site.ts`: the website copy, store links, and the company
+  details the privacy policy and terms need.
+- `apps/api/functions/deleteMyData.ts`: delete every entity that stores
+  user data, or account deletion leaves rows behind.
+- `apps/api/functions/createNote.ts`: the free-tier cap.
 
 ## Ship
 

package/templates/expo/mobile/apps/expo/STORE.md

@@ -3,7 +3,7 @@
 The order below is the shortest path that App Review and Google Play accept
 on the first try. Each step is one command or one dashboard page.
 
-## 1. Backend live
+## 1. Backend and website live
 
 ```bash
 cd apps/api && pylon deploy
@@ -11,12 +11,15 @@ pylon secrets set PYLON_APPLE_NATIVE_CLIENT_IDS=<bundle id> REVENUECAT_WEBHOOK_A
 ```
 
 Put the deployed URL in `apps/expo/eas.json` (`EXPO_PUBLIC_PYLON_BASE_URL`
-under `preview` and `production`).
+under `preview` and `production`). `app.config.ts` refuses a preview or
+production build until that value, `APP_BUNDLE_ID`, and `EAS_PROJECT_ID`
+are set.
 
 ## 2. Identifiers
 
 - Pick a bundle id (`com.yourco.app`) and set `APP_BUNDLE_ID` in `eas.json`
-  env for every profile, or export it before building.
+  env for `preview` and `production`, or export it before building. The
+  `development` profile appends `.dev` to the `com.example` placeholder.
 - `eas init` prints the project id; set `EAS_PROJECT_ID` the same way.
 - Apple: an App ID with the Sign in with Apple capability. EAS creates it on
   the first `eas build` when you let it manage credentials.
@@ -49,8 +52,12 @@ Test the purchase on TestFlight with a sandbox Apple ID before submitting.
 
 Both stores require, and reviewers check:
 
-- Privacy policy URL and terms URL (`EXPO_PUBLIC_PRIVACY_URL`, `EXPO_PUBLIC_TERMS_URL`).
-  The app shows them in Settings and under the paywall.
+- Privacy policy URL and terms URL. The backend serves them at
+  `<your-backend>/privacy` and `<your-backend>/terms`, and the app links to
+  them from Settings and under the paywall with no configuration. Fill in
+  `apps/api/lib/site.ts` first: the text ships as a draft and a banner stays
+  on the page until you do.
+- A support URL for App Store Connect: `<your-backend>/support`.
 - Account deletion inside the app (Settings → Delete account). Present.
 - Sign in with Apple when any other third-party sign-in is offered. Present.
 - Subscription terms next to the purchase button (price, period, renewal). Present.
@@ -70,8 +77,25 @@ eas submit --platform ios --latest
 eas submit --platform android --latest
 ```
 
-Fill `submit.production.ios.ascAppId` in `eas.json` with the App Store
-Connect app id first.
+For iOS, add the App Store Connect app id to `eas.json` first:
+
+```json
+"submit": { "production": { "ios": { "ascAppId": "1234567890" } } }
+```
+
+Without it `eas submit` asks for the app interactively.
+
+## Before the first store build
+
+- Products: the `pro` entitlement and a `default` offering exist in
+  RevenueCat, and the iOS and Android public keys are in `apps/expo/.env`.
+- Sign-in: `PYLON_APPLE_NATIVE_CLIENT_IDS` (the bundle id) and
+  `PYLON_GOOGLE_NATIVE_CLIENT_IDS` are set on the backend.
+- Legal: `apps/api/lib/site.ts` is filled in, the draft banner is gone from
+  `/privacy` and `/terms`, and a lawyer has read both.
+- Deletion: `apps/api/functions/deleteMyData.ts` removes every entity that
+  stores user data. Test it with a throwaway account.
+- Copy: the "Replace the demo" list in `README.md` is done.
 
 ## After launch
 

package/templates/expo/mobile/apps/expo/app/(auth)/sign-in.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useState } from "react";
 import { Alert, Platform, Text, View } from "react-native";
 import { useLocalSearchParams, useRouter } from "expo-router";
-import { nativeSignIn, sendEmailCode } from "@pylonsync/react-native";
+import { db, nativeSignIn, sendEmailCode } from "@pylonsync/react-native";
 import { track } from "@/analytics";
 import { useAppSession } from "@/session";
 import { space, useTheme } from "@/theme";
@@ -59,12 +59,23 @@ export default function SignIn() {
     });
   }, [apple, google]);
 
-  function done() {
+  async function done() {
     track("sign_in_completed");
+    // Wait for the server to confirm the new session so the route guard
+    // sees `ready` before the navigation, not after it.
+    await db.sync.notifySessionChanged();
     if (params.next) router.replace(params.next as never);
     else router.replace("/(tabs)");
   }
 
+  // "Not now" is reachable from a cold start (no history) as well as from
+  // Settings (history). Fall back to the app when there is nothing to go
+  // back to.
+  function dismiss() {
+    if (router.canGoBack()) router.back();
+    else router.replace("/(tabs)");
+  }
+
   async function withApple() {
     if (!apple) return;
     setBusy("apple");
@@ -81,7 +92,7 @@ export default function SignIn() {
         .filter(Boolean)
         .join(" ");
       await nativeSignIn("apple", credential.identityToken, name || undefined);
-      done();
+      await done();
     } catch (e) {
       if ((e as { code?: string })?.code !== "ERR_REQUEST_CANCELED") {
         Alert.alert("Sign in failed", messageOf(e));
@@ -101,7 +112,7 @@ export default function SignIn() {
       const idToken = result.type === "success" ? result.data.idToken : null;
       if (!idToken) return;
       await nativeSignIn("google", idToken, result.type === "success" ? result.data.user.name : undefined);
-      done();
+      await done();
     } catch (e) {
       Alert.alert("Sign in failed", messageOf(e));
     } finally {
@@ -132,7 +143,7 @@ export default function SignIn() {
       <Spacer h={space.xxl} />
       <Title>Sign in</Title>
       <Body muted style={{ marginTop: space.sm }}>
-        Keep your notes on every device. Anything you made already comes with you.
+        Keep everything on every device. Anything you made already comes with you.
       </Body>
       <Spacer h={space.xxl} />
       <View style={{ gap: space.md }}>
@@ -179,7 +190,7 @@ export default function SignIn() {
           onPress={() => void continueAsGuest().then(() => router.replace("/(tabs)"))}
         />
       ) : (
-        <Button title="Not now" variant="ghost" onPress={() => router.back()} />
+        <Button title="Not now" variant="ghost" onPress={dismiss} />
       )}
       <Spacer />
       <Text style={{ color: t.muted, fontSize: 12, textAlign: "center", lineHeight: 18 }}>

package/templates/expo/mobile/apps/expo/app/(auth)/verify.tsx

@@ -1,7 +1,7 @@
 import React, { useEffect, useRef, useState } from "react";
 import { Alert, TextInput } from "react-native";
 import { useLocalSearchParams, useRouter } from "expo-router";
-import { sendEmailCode, verifyEmailCode } from "@pylonsync/react-native";
+import { db, sendEmailCode, verifyEmailCode } from "@pylonsync/react-native";
 import { track } from "@/analytics";
 import { space } from "@/theme";
 import { Body, Button, Field, Screen, Spacer, Title } from "@/ui";
@@ -26,6 +26,8 @@ export default function Verify() {
     try {
       await verifyEmailCode(email, value);
       track("sign_in_completed", { method: "email" });
+      // See sign-in.tsx: let the route guard observe the session first.
+      await db.sync.notifySessionChanged();
       if (next) router.replace(next as never);
       else router.replace("/(tabs)");
     } catch (e) {

package/templates/expo/mobile/apps/expo/app/(tabs)/settings.tsx

@@ -4,6 +4,7 @@ import { useRouter } from "expo-router";
 import Constants from "expo-constants";
 import { deleteAccount } from "@pylonsync/react-native";
 import { track } from "@/analytics";
+import { PRIVACY_URL, SUPPORT_EMAIL, SUPPORT_URL, TERMS_URL } from "@/links";
 import { usePro } from "@/entitlements";
 import { resetFlags } from "@/flags";
 import { manageSubscriptionUrl, restore } from "@/purchases";
@@ -15,6 +16,11 @@ import { Caption, Row, Screen, Spacer, Title } from "@/ui";
  * Account, subscription, legal, and support. App Review requires an
  * in-app account deletion path when the app offers account creation, and
  * both stores require the privacy policy and terms links.
+ *
+ * Delete account: `deleteAccount()` calls `DELETE /api/auth/account`. The
+ * backend runs `deleteMyData` first (see `auth({ onDeleteAccount })` in
+ * apps/api/app.ts), so the user's notes and entitlement rows go with the
+ * account. Add every new entity that stores user data to that function.
  */
 export default function Settings() {
   const router = useRouter();
@@ -22,9 +28,8 @@ export default function Settings() {
   const { pro } = usePro();
   const [busy, setBusy] = useState<string | null>(null);
 
-  const privacy = process.env.EXPO_PUBLIC_PRIVACY_URL;
-  const terms = process.env.EXPO_PUBLIC_TERMS_URL;
-  const support = process.env.EXPO_PUBLIC_SUPPORT_EMAIL;
+  // These resolve to the site the backend serves (apps/api), so the rows
+  // always render and always lead somewhere real. See src/links.ts.
   const version = Constants.expoConfig?.version ?? "dev";
 
   async function restorePurchases() {
@@ -40,7 +45,7 @@ export default function Settings() {
   function confirmDelete() {
     Alert.alert(
       "Delete account?",
-      "This removes your account and every note on our servers. Subscriptions are managed by the store and must be cancelled there.",
+      "This deletes your account and every note on our servers. A subscription is managed by the store; cancel it there.",
       [
         { text: "Cancel", style: "cancel" },
         {
@@ -94,9 +99,12 @@ export default function Settings() {
         <Spacer />
 
         <Caption>About</Caption>
-        {privacy ? <Row label="Privacy policy" onPress={() => void Linking.openURL(privacy)} /> : null}
-        {terms ? <Row label="Terms of service" onPress={() => void Linking.openURL(terms)} /> : null}
-        {support ? <Row label="Contact support" onPress={() => void Linking.openURL(`mailto:${support}`)} /> : null}
+        <Row label="Help" onPress={() => void Linking.openURL(SUPPORT_URL)} />
+        <Row label="Privacy policy" onPress={() => void Linking.openURL(PRIVACY_URL)} />
+        <Row label="Terms of service" onPress={() => void Linking.openURL(TERMS_URL)} />
+        {SUPPORT_EMAIL ? (
+          <Row label="Contact support" onPress={() => void Linking.openURL(`mailto:${SUPPORT_EMAIL}`)} />
+        ) : null}
         <Row label="Version" value={version} />
         <Spacer />
 

package/templates/expo/mobile/apps/expo/app/paywall.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useState } from "react";
 import { Alert, Linking, Pressable, Text, View } from "react-native";
 import { useLocalSearchParams, useRouter } from "expo-router";
 import { track } from "@/analytics";
+import { PRIVACY_URL, TERMS_URL } from "@/links";
 import { usePro } from "@/entitlements";
 import { available, offers, purchase, restore, type Offer } from "@/purchases";
 import { radius, space, useTheme } from "@/theme";
@@ -45,8 +46,7 @@ export default function Paywall() {
     if (pro) router.back();
   }, [pro, router]);
 
-  const privacy = process.env.EXPO_PUBLIC_PRIVACY_URL;
-  const terms = process.env.EXPO_PUBLIC_TERMS_URL;
+
 
   async function buy() {
     const offer = list?.find((o) => o.id === selected);
@@ -160,17 +160,13 @@ export default function Paywall() {
       <Button title="Restore purchases" variant="ghost" loading={busy === "restore"} onPress={() => void restorePurchases()} />
       <Text style={{ color: t.muted, fontSize: 11, textAlign: "center", lineHeight: 16, marginTop: space.sm }}>
         Renews automatically until cancelled. Manage in your store account settings.{" "}
-        {terms ? (
-          <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(terms)}>
-            Terms
-          </Text>
-        ) : null}
-        {terms && privacy ? " · " : ""}
-        {privacy ? (
-          <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(privacy)}>
-            Privacy
-          </Text>
-        ) : null}
+        <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(TERMS_URL)}>
+          Terms
+        </Text>
+        {" · "}
+        <Text style={{ textDecorationLine: "underline" }} onPress={() => void Linking.openURL(PRIVACY_URL)}>
+          Privacy
+        </Text>
       </Text>
     </Screen>
   );

package/templates/expo/mobile/apps/expo/app.config.ts

@@ -4,10 +4,11 @@ import type { ConfigContext, ExpoConfig } from "expo/config";
  * App config. The values that change per environment come from env vars
  * so one file serves development builds, TestFlight, and the store:
  *
- *   APP_BUNDLE_ID       reverse-DNS id (iOS bundle id + Android package)
- *   APP_SCHEME          deep-link scheme, e.g. "__APP_NAME_KEBAB__"
- *   EAS_PROJECT_ID      from `eas init` (printed once, then stable)
- *   APP_VARIANT         "development" | "preview" | "production" (set by eas.json)
+ *   APP_BUNDLE_ID                reverse-DNS id (iOS bundle id + Android package)
+ *   APP_SCHEME                   deep-link scheme, e.g. "__APP_NAME_KEBAB__"
+ *   EAS_PROJECT_ID               from `eas init` (printed once, then stable)
+ *   EXPO_PUBLIC_PYLON_BASE_URL   the backend; https:// outside development
+ *   APP_VARIANT                  "development" | "preview" | "production" (set by eas.json)
  *
  * A development build gets a ".dev" suffix so it installs alongside the
  * store app on the same phone.
@@ -17,6 +18,27 @@ const baseBundleId = process.env.APP_BUNDLE_ID ?? "com.example.__APP_NAME_SNAKE_
 const bundleId = variant === "development" ? `${baseBundleId}.dev` : baseBundleId;
 const name = variant === "production" ? "__APP_NAME__" : `__APP_NAME__ (${variant})`;
 
+// A preview or store build with placeholder values would install and
+// then fail at first launch. Refuse to build instead.
+if (variant !== "development") {
+  const problems: string[] = [];
+  if (!process.env.APP_BUNDLE_ID) {
+    problems.push("APP_BUNDLE_ID is unset; the com.example placeholder cannot ship");
+  }
+  if (!process.env.EAS_PROJECT_ID) {
+    problems.push("EAS_PROJECT_ID is unset; run `eas init` and copy the id");
+  }
+  if (!/^https:\/\//.test(process.env.EXPO_PUBLIC_PYLON_BASE_URL ?? "")) {
+    problems.push("EXPO_PUBLIC_PYLON_BASE_URL must be the deployed https:// backend");
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `The ${variant} build is not configured:\n  - ${problems.join("\n  - ")}\n` +
+        `Set these under build.${variant}.env in eas.json, or export them before building.`,
+    );
+  }
+}
+
 export default ({ config }: ConfigContext): ExpoConfig => ({
   ...config,
   name,
@@ -56,7 +78,9 @@ export default ({ config }: ConfigContext): ExpoConfig => ({
     [
       "expo-build-properties",
       {
-        ios: { deploymentTarget: "15.1" },
+        // The floors for Expo SDK 57 / React Native 0.86. expo-build-properties
+        // rejects a lower iOS target; Android below 24 does not build.
+        ios: { deploymentTarget: "16.4" },
         // Cleartext lets a dev/preview build reach http://localhost:4321.
         android: { minSdkVersion: 24, usesCleartextTraffic: variant !== "production" },
       },

package/templates/expo/mobile/apps/expo/babel.config.js

@@ -1,8 +1,8 @@
 module.exports = function (api) {
   api.cache(true);
   return {
+    // babel-preset-expo 57 registers the react-native-worklets plugin
+    // (Reanimated 4) itself; adding it here again applies it twice.
     presets: ["babel-preset-expo"],
-    // Reanimated's plugin must be last.
-    plugins: ["react-native-reanimated/plugin"],
   };
 };

package/templates/expo/mobile/apps/expo/eas.json

@@ -21,22 +21,23 @@
       "distribution": "internal",
       "env": {
         "APP_VARIANT": "preview",
-        "EXPO_PUBLIC_PYLON_BASE_URL": "https://__APP_NAME_KEBAB__.pylonapp.com"
+        "APP_BUNDLE_ID": "",
+        "EAS_PROJECT_ID": "",
+        "EXPO_PUBLIC_PYLON_BASE_URL": ""
       }
     },
     "production": {
       "autoIncrement": true,
       "env": {
         "APP_VARIANT": "production",
-        "EXPO_PUBLIC_PYLON_BASE_URL": "https://__APP_NAME_KEBAB__.pylonapp.com"
+        "APP_BUNDLE_ID": "",
+        "EAS_PROJECT_ID": "",
+        "EXPO_PUBLIC_PYLON_BASE_URL": ""
       }
     }
   },
   "submit": {
     "production": {
-      "ios": {
-        "ascAppId": "REPLACE_WITH_APP_STORE_CONNECT_APP_ID"
-      },
       "android": {
         "track": "internal"
       }

package/templates/expo/mobile/apps/expo/package.json

@@ -14,11 +14,13 @@
     "build:preview": "eas build --profile preview --platform all",
     "build:prod": "eas build --profile production --platform all",
     "submit:ios": "eas submit --platform ios --latest",
-    "submit:android": "eas submit --platform android --latest"
+    "submit:android": "eas submit --platform android --latest",
+    "check:bundle": "expo export --platform ios --platform android --output-dir .expo-export"
   },
   "dependencies": {
     "@pylonsync/react": "^__PYLON_VERSION__",
     "@pylonsync/react-native": "^__PYLON_VERSION__",
+    "@pylonsync/revenuecat": "^__PYLON_VERSION__",
     "@pylonsync/sdk": "^__PYLON_VERSION__",
     "@pylonsync/sync": "^__PYLON_VERSION__",
     "@react-native-async-storage/async-storage": "2.2.0",
@@ -42,11 +44,13 @@
     "react-native-reanimated": "4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-screens": "~4.26.0",
-    "react-native-web": "~0.21.0"
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.10.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.25.0",
-    "@types/react": "~19.2.0",
-    "typescript": "~5.9.0"
+    "@babel/core": "^7.29.0",
+    "@types/react": "~19.2.4",
+    "babel-preset-expo": "~57.0.10",
+    "typescript": "~6.0.3"
   }
 }

package/templates/expo/mobile/apps/expo/src/entitlements.ts

@@ -1,19 +1,14 @@
 import { db } from "@pylonsync/react-native";
-import { hasEntitlement } from "@pylonsync/revenuecat";
+import { hasEntitlement, type RcEntitlementRow } from "@pylonsync/revenuecat/client";
 
 export const PRO = "pro";
 
-interface RcEntitlementRow {
-  id: string;
-  userId: string;
-  entitlement: string;
-  status: string;
-  expiresAt?: string | null;
-}
-
 /**
  * Live Pro status from the synced RcEntitlement rows. Updates the moment
  * the server writes the row after a purchase, on every device.
+ *
+ * `@pylonsync/revenuecat/client` is the browser/React Native entry of the
+ * plugin. The package root is server code and must not be imported here.
  */
 export function usePro(): { pro: boolean; loading: boolean } {
   const { data, loading } = db.useQuery<RcEntitlementRow>("RcEntitlement", {});

package/templates/expo/mobile/apps/expo/src/links.ts

@@ -0,0 +1,29 @@
+/**
+ * Where the app sends people for legal text and help.
+ *
+ * The backend in `apps/api` serves a website as well as the API, so these
+ * pages already exist on whatever host `EXPO_PUBLIC_PYLON_BASE_URL` points
+ * at. That is what makes the App Store and Play Store requirements
+ * satisfiable straight from a scaffold: both stores refuse a submission
+ * without a reachable privacy policy URL.
+ *
+ * Set the EXPO_PUBLIC_* values only if you host the marketing site somewhere
+ * else, on your own domain for example.
+ */
+import { PYLON_BASE_URL } from "./pylon";
+
+const siteOrigin = (
+  process.env.EXPO_PUBLIC_SITE_URL || PYLON_BASE_URL
+).replace(/\/+$/, "");
+
+export const PRIVACY_URL =
+  process.env.EXPO_PUBLIC_PRIVACY_URL || `${siteOrigin}/privacy`;
+
+export const TERMS_URL =
+  process.env.EXPO_PUBLIC_TERMS_URL || `${siteOrigin}/terms`;
+
+export const SUPPORT_URL =
+  process.env.EXPO_PUBLIC_SUPPORT_URL || `${siteOrigin}/support`;
+
+/** Optional. Settings shows a "Contact support" row when it is set. */
+export const SUPPORT_EMAIL = process.env.EXPO_PUBLIC_SUPPORT_EMAIL;

package/templates/expo/mobile/apps/expo/src/pylon.ts

@@ -1,9 +1,14 @@
 import { Platform } from "react-native";
 import { init } from "@pylonsync/react-native";
 
-/** The backend URL. Android emulators reach the host machine at 10.0.2.2. */
+/**
+ * The backend URL. `pylon dev` in apps/api listens on 4321. An Android
+ * emulator reaches the host machine at 10.0.2.2. Outside development
+ * app.config.ts refuses to build without an https:// value.
+ */
+const configured = process.env.EXPO_PUBLIC_PYLON_BASE_URL?.trim();
 export const PYLON_BASE_URL =
-  process.env.EXPO_PUBLIC_PYLON_BASE_URL ??
+  configured ||
   (Platform.OS === "android" ? "http://10.0.2.2:4321" : "http://localhost:4321");
 
 export const APP_NAME = "__APP_NAME_SNAKE__";

package/templates/expo/mobile/apps/expo/src/session.tsx

@@ -1,8 +1,15 @@
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { db, guestSession, signOut as pylonSignOut, useSession } from "@pylonsync/react-native";
+import {
+  db,
+  getReactStorage,
+  guestSession,
+  signOut as pylonSignOut,
+  storageKey,
+  useSession,
+} from "@pylonsync/react-native";
 import { ensurePylon } from "./pylon";
 import { getOnboardingDone, setOnboardingDone as persistOnboardingDone } from "./flags";
-import { configure as configurePurchases } from "./purchases";
+import { configure as configurePurchases, syncEntitlements } from "./purchases";
 
 /**
  * What the router needs to know:
@@ -10,7 +17,7 @@ import { configure as configurePurchases } from "./purchases";
  *   booting     the engine and the on-device flags are still loading
  *   onboarding  first launch: show the welcome slides
  *   ready       a session exists (guest or account) and the tabs can render
- *   signedOut   the user signed out explicitly; offer sign-in or a fresh guest
+ *   signedOut   no session; offer sign-in or a fresh guest
  */
 export type SessionState = "booting" | "onboarding" | "ready" | "signedOut";
 
@@ -26,37 +33,73 @@ interface SessionValue {
 
 const Ctx = createContext<SessionValue | null>(null);
 
+async function notBooted(): Promise<void> {
+  throw new Error("Pylon is still booting");
+}
+
+const BOOTING: SessionValue = {
+  state: "booting",
+  userId: null,
+  isGuest: false,
+  completeOnboarding: notBooted,
+  continueAsGuest: notBooted,
+  signOut: notBooted,
+};
+
+/**
+ * Boots Pylon, then mounts the session reader. The order matters: before
+ * `init()` has run, `db.sync` would create a default engine with the
+ * wrong base URL and no AsyncStorage, and the reader would stay bound to
+ * it. Children render during boot, so the native splash stays up (see
+ * app/_layout.tsx) instead of a blank frame.
+ */
 export function SessionProvider({ children }: { children: React.ReactNode }) {
-  const [booted, setBooted] = useState(false);
-  const [onboardingDone, setOnboardingDoneState] = useState(false);
-  const [signedOut, setSignedOut] = useState(false);
-  const session = useSession(db.sync);
-  const userId = session.userId;
+  const [boot, setBoot] = useState<{ onboardingDone: boolean } | null>(null);
 
   useEffect(() => {
     let alive = true;
     void (async () => {
       await ensurePylon();
-      const done = await getOnboardingDone();
-      if (!alive) return;
-      setOnboardingDoneState(done);
-      setBooted(true);
+      const onboardingDone = await getOnboardingDone();
+      if (alive) setBoot({ onboardingDone });
     })();
     return () => {
       alive = false;
     };
   }, []);
 
+  if (!boot) return <Ctx.Provider value={BOOTING}>{children}</Ctx.Provider>;
+  return <BootedSession initialOnboardingDone={boot.onboardingDone}>{children}</BootedSession>;
+}
+
+/** A token in AsyncStorage: the last session (guest or account) to restore. */
+function hasStoredToken(): boolean {
+  return Boolean(getReactStorage().get(storageKey("token")));
+}
+
+function BootedSession({
+  initialOnboardingDone,
+  children,
+}: {
+  initialOnboardingDone: boolean;
+  children: React.ReactNode;
+}) {
+  const [onboardingDone, setOnboardingDoneState] = useState(initialOnboardingDone);
+  const session = useSession(db.sync);
+  const userId = session.userId;
+
   // Identify the purchase SDK with the Pylon user id so RevenueCat's
-  // app_user_id is our id and webhook events map to our rows.
+  // app_user_id is our id and webhook events map to our rows. After a
+  // guest signs in, RevenueCat aliases the ids; re-reading the
+  // entitlements moves the guest's purchase onto the account.
   useEffect(() => {
-    if (userId) void configurePurchases(userId);
+    if (!userId) return;
+    void configurePurchases(userId).then((ok) => (ok ? syncEntitlements() : undefined));
   }, [userId]);
 
   const continueAsGuest = useCallback(async () => {
     await guestSession();
     await db.sync.notifySessionChanged();
-    setSignedOut(false);
   }, []);
 
   const completeOnboarding = useCallback(async () => {
@@ -69,16 +112,19 @@ export function SessionProvider({ children }: { children: React.ReactNode }) {
 
   const signOut = useCallback(async () => {
     await pylonSignOut();
-    setSignedOut(true);
+    // Wait for /api/auth/me so `state` is signedOut before the caller
+    // navigates, not one render later.
+    await db.sync.notifySessionChanged();
   }, []);
 
-  const state: SessionState = !booted
-    ? "booting"
-    : !onboardingDone
-      ? "onboarding"
-      : userId && !signedOut
-        ? "ready"
-        : "signedOut";
+  // Until /api/auth/me answers, `session.userId` is null because the
+  // answer has not arrived, not because the user is signed out. A stored
+  // token means the previous session is still the one to show: the
+  // replica renders from AsyncStorage and the server confirms or rejects
+  // the token on the first pull. An expired token resolves to no user and
+  // the state moves to signedOut then.
+  const hasSession = session.resolved ? userId != null : hasStoredToken();
+  const state: SessionState = !onboardingDone ? "onboarding" : hasSession ? "ready" : "signedOut";
 
   const value = useMemo<SessionValue>(
     () => ({