@pylonsync/create-pylon 0.8.3 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"
@@ -10,7 +10,7 @@
     "create-pylon": "./bin/create-pylon.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test \"test/*.test.mjs\""
   },
   "files": [
     "bin",

package/templates/_root/gitignore

@@ -22,6 +22,7 @@ Package.resolved
 
 # Expo / RN
 .expo/
+.expo-export/
 .expo-shared/
 ios/Pods/
 ios/build/

package/templates/backend/mobile/apps/api/README.md

@@ -6,6 +6,7 @@ data API, realtime sync, auth, and the RevenueCat webhook.
 ```
 app.ts                 User + Note + RcEntitlement (from @pylonsync/revenuecat)
 functions/createNote   server-enforced free-tier cap, then insert
+functions/deleteMyData the user's rows, run by DELETE /api/auth/account
 functions/revenuecatWebhook, syncEntitlements, _pylonRcUpsertEntitlement
 lib/purchases.ts       the RevenueCat plugin instance + FREE_NOTE_LIMIT
 ```

package/templates/backend/mobile/apps/api/app.ts

@@ -79,7 +79,11 @@ const manifest = buildManifest({
   // the app's ids on the server: PYLON_APPLE_NATIVE_CLIENT_IDS (the iOS
   // bundle id) and PYLON_GOOGLE_NATIVE_CLIENT_IDS (the iOS + Android OAuth
   // client ids). See .env.example.
-  auth: auth(),
+  //
+  // `onDeleteAccount`: DELETE /api/auth/account runs this function before
+  // it removes the User row. Pylon deletes its own auth rows; the app's
+  // rows (Note, RcEntitlement) are deleted in functions/deleteMyData.ts.
+  auth: auth({ onDeleteAccount: "deleteMyData" }),
 });
 
 // The CLI runs `bun run app.ts` and reads this as the manifest.

package/templates/backend/mobile/apps/api/functions/createNote.ts

@@ -9,15 +9,19 @@ import { FREE_NOTE_LIMIT, PRO_ENTITLEMENT } from "../lib/purchases";
  *
  * Returns `LIMIT_REACHED` when a free account is at the cap; the app opens
  * the paywall on that code.
+ *
+ * `auth: "guest"`: the app starts every user as a guest, and the default
+ * (`"user"`) rejects guest sessions with 401 before the handler runs.
  */
 export default mutation({
+  auth: "guest",
   args: {
     title: v.string(),
     body: v.optional(v.string()),
   },
   async handler(ctx, args: { title: string; body?: string }) {
     const userId = ctx.auth.userId;
-    if (!userId) throw ctx.error("UNAUTHENTICATED", "sign in first");
+    if (!userId) throw ctx.error("UNAUTHENTICATED", "start a guest session or sign in first");
     const title = args.title.trim();
     if (!title) throw ctx.error("INVALID_ARGS", "title is required");
 

package/templates/backend/mobile/apps/api/functions/deleteMyData.ts

@@ -0,0 +1,38 @@
+import { mutation, v } from "@pylonsync/functions";
+import { ENTITLEMENT_ENTITY } from "../lib/purchases";
+
+/**
+ * Deletes the caller's rows before Pylon deletes the account. Wired
+ * through `auth({ onDeleteAccount: "deleteMyData" })` in app.ts; the
+ * runtime calls it as the user with `{ userId }` and aborts the deletion
+ * if it throws. `internal: true` keeps it off the HTTP surface.
+ *
+ * Add every entity that stores user data here. Pylon removes the User
+ * row, sessions, API keys, linked accounts, and trusted devices; nothing
+ * else.
+ */
+export default mutation({
+  internal: true,
+  auth: "guest",
+  args: { userId: v.string() },
+  async handler(ctx, args: { userId: string }) {
+    if (ctx.auth.userId !== args.userId) {
+      throw ctx.error("FORBIDDEN", "a user can only delete their own data");
+    }
+
+    const notes = await ctx.db.query("Note", { ownerId: args.userId });
+    for (const note of notes) {
+      await ctx.db.delete("Note", String(note.id));
+    }
+
+    // The entitlement policy denies every client delete. This is server
+    // code running as part of account deletion, so the unsafe surface
+    // (policy bypass) is the right tool.
+    const entitlements = await ctx.db.query(ENTITLEMENT_ENTITY, { userId: args.userId });
+    for (const row of entitlements) {
+      await ctx.db.unsafe.delete(ENTITLEMENT_ENTITY, String(row.id));
+    }
+
+    return { notes: notes.length, entitlements: entitlements.length };
+  },
+});

package/templates/backend/mobile/apps/api/lib/purchases.ts

@@ -16,7 +16,15 @@ export const FREE_NOTE_LIMIT = 10;
 // Point the dashboard webhook at https://<your-app>/api/fn/revenuecatWebhook.
 export const purchases = revenuecat({
   entitlements: [PRO_ENTITLEMENT],
+  // Guests can buy before they sign in (the plugin default). The server
+  // reads RevenueCat by the caller's own id, so a guest cannot claim an
+  // entitlement it did not pay for. Set `syncAuth: "user"` to require an
+  // account first.
+  syncAuth: "guest",
 });
 
+/** The synced entitlement entity; `deleteMyData` purges it on account deletion. */
+export const ENTITLEMENT_ENTITY = purchases.manifest.entities[0].name;
+
 export const { revenuecatWebhook, syncEntitlements } = purchases.handlers;
 export const { _pylonRcUpsertEntitlement } = purchases.internals;

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

@@ -26,8 +26,32 @@ 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/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

@@ -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.
@@ -70,8 +73,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: `EXPO_PUBLIC_PRIVACY_URL`, `EXPO_PUBLIC_TERMS_URL`, and
+  `EXPO_PUBLIC_SUPPORT_EMAIL` point at real pages and a monitored inbox.
+- 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

@@ -15,6 +15,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();
@@ -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" },
         {

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/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>(
     () => ({