From 8721db35bd47777ad26da2a11756cf8b47ffcd4b Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Sat, 8 Nov 2025 14:14:03 -0600
Subject: [PATCH 1/9] docs: fix header blocking banner on mobile

---
 apps/docs/src/styles/custom.css | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/apps/docs/src/styles/custom.css b/apps/docs/src/styles/custom.css
index 5df0aed..52ea625 100644
--- a/apps/docs/src/styles/custom.css
+++ b/apps/docs/src/styles/custom.css
@@ -385,9 +385,3 @@ starlight-tabs .tab > [role="tab"] {
   li:has(> a:not([aria-current="page"]):is(:hover, :focus-visible)) {
   border-inline-start-color: var(--sl-color-gray-2);
 }
-
-/* Reduce top margin on splash template main content */
-.main-pane {
-  margin-top: 0 !important;
-  padding-top: 0 !important;
-}

From 354bb58f33f9d2903c9d0c8bf8495b370ca827f9 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Wed, 4 Feb 2026 13:12:13 -0600
Subject: [PATCH 2/9] docs: wrap flow methods in event handlers

---
 README.md                                         |  4 ++--
 .../content/docs/api-reference/flow-component.mdx |  3 +--
 .../content/docs/api-reference/use-flow-state.mdx |  6 +++---
 .../src/content/docs/core-concepts/navigation.mdx | 15 ++++++++++++---
 .../content/docs/getting-started/quick-start.mdx  |  6 ++++++
 .../content/docs/getting-started/why-useflow.mdx  |  2 +-
 .../src/content/docs/guides/branching-flows.mdx   |  3 +--
 .../src/content/docs/guides/custom-layouts.mdx    |  9 ++++-----
 .../docs/src/content/docs/guides/linear-flows.mdx |  4 ++--
 apps/docs/src/content/docs/guides/testing.mdx     |  2 +-
 .../src/content/docs/guides/troubleshooting.mdx   |  2 +-
 apps/docs/src/content/docs/index.mdx              |  4 ++--
 apps/docs/src/content/docs/recipes/checkout.mdx   |  7 +++----
 apps/docs/src/content/docs/recipes/onboarding.mdx |  5 ++---
 apps/docs/src/content/docs/recipes/survey.mdx     |  5 ++---
 packages/react/README.md                          |  4 ++--
 16 files changed, 45 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 0c24f7e..6a82f88 100644
--- a/README.md
+++ b/README.md
@@ -135,8 +135,8 @@ function BusinessStep() {
         value={context.company || ""} // 💡 TypeScript knows this is a string
         onChange={(e) => setContext({ company: e.target.value })}
       />
-      <button onClick={back}>Back</button> 
-      <button onClick={next}>Continue</button> 
+      <button onClick={() => back()}>Back</button> 
+      <button onClick={() => next()}>Continue</button> 
     </div>
   );
 }
diff --git a/apps/docs/src/content/docs/api-reference/flow-component.mdx b/apps/docs/src/content/docs/api-reference/flow-component.mdx
index d5aedb2..e03a39e 100644
--- a/apps/docs/src/content/docs/api-reference/flow-component.mdx
+++ b/apps/docs/src/content/docs/api-reference/flow-component.mdx
@@ -330,7 +330,7 @@ const persister = createPersister({ store });
       </main>
       
       <footer>
-        <button onClick={back} disabled={!canGoBack}>
+        <button onClick={() => back()} disabled={!canGoBack}>
           Back
         </button>
         <button onClick={() => next()} disabled={!canGoNext}>
@@ -459,4 +459,3 @@ const handleComplete = useCallback((event) => {
 - [useFlowState Hook](/api-reference/use-flow-state) - Access flow state
 - [FlowProvider](/api-reference/flow-provider) - Global configuration
 - [Callbacks Guide](/guides/callbacks) - Event handling
-
diff --git a/apps/docs/src/content/docs/api-reference/use-flow-state.mdx b/apps/docs/src/content/docs/api-reference/use-flow-state.mdx
index 75e037f..35f3264 100644
--- a/apps/docs/src/content/docs/api-reference/use-flow-state.mdx
+++ b/apps/docs/src/content/docs/api-reference/use-flow-state.mdx
@@ -172,7 +172,7 @@ function ProfileStep() {
   return (
     <div>
       <h2>Welcome, {context.name}!</h2>
-      <button onClick={back}>Back</button>
+      <button onClick={() => back()}>Back</button>
       <button onClick={() => next()}>Continue</button>
     </div>
   );
@@ -257,7 +257,7 @@ function NavigableStep() {
   
   return (
     <div>
-      <button onClick={back} disabled={!canGoBack}>
+      <button onClick={() => back()} disabled={!canGoBack}>
         Back
       </button>
       <button onClick={() => next()} disabled={!canGoNext}>
@@ -404,4 +404,4 @@ next({ skipped: true });  // Confusing - is this a skip?
 - [Flow Component](/api-reference/flow-component) - The parent component that provides flow context
 - [defineFlow](/api-reference/define-flow) - Creating flow definitions
 - [Navigation Guide](/core-concepts/navigation) - Detailed navigation patterns
-- [Context Guide](/core-concepts/context) - Managing flow state
\ No newline at end of file
+- [Context Guide](/core-concepts/context) - Managing flow state
diff --git a/apps/docs/src/content/docs/core-concepts/navigation.mdx b/apps/docs/src/content/docs/core-concepts/navigation.mdx
index abe0794..41d6ed4 100644
--- a/apps/docs/src/content/docs/core-concepts/navigation.mdx
+++ b/apps/docs/src/content/docs/core-concepts/navigation.mdx
@@ -3,8 +3,17 @@ title: Navigation
 description: Control flow movement with type-safe navigation methods
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+
 **Navigation** is how users move through your flow. useFlowState provides several navigation methods that are type-safe, flexible, and work seamlessly with your flow definition.
 
+<Aside type="caution" title="React event handlers">
+  Do not pass flow methods directly as event handlers (for example: `onClick={next}` / `onPress={next}`).
+  React may pass an event object as the first argument, which can accidentally be treated as a context update.
+
+  Always wrap: `onClick={() => next()}` / `onPress={() => next()}` (same for `skip()` and `setContext()`).
+</Aside>
+
 ## Navigation methods
 
 ### `next()` - Move Forward
@@ -770,8 +779,8 @@ function MyStep() {
   
   return (
     <div className="navigation">
-      {canGoBack && <button onClick={back}>Back</button>}
-      <button onClick={next}>Continue</button>
+      {canGoBack && <button onClick={() => back()}>Back</button>}
+      <button onClick={() => next()}>Continue</button>
     </div>
   );
 }
@@ -804,7 +813,7 @@ function MyStep() {
     return <div>This is the end!</div>;
   }
   
-  return <button onClick={next}>Continue</button>;
+  return <button onClick={() => next()}>Continue</button>;
 }
 ```
 
diff --git a/apps/docs/src/content/docs/getting-started/quick-start.mdx b/apps/docs/src/content/docs/getting-started/quick-start.mdx
index 5a9005b..53a6096 100644
--- a/apps/docs/src/content/docs/getting-started/quick-start.mdx
+++ b/apps/docs/src/content/docs/getting-started/quick-start.mdx
@@ -73,6 +73,12 @@ A simple 3-step onboarding flow:
 
    Create components for each step. Each component uses the `useFlowState()` hook to access flow state and navigation.
 
+   <Aside type="caution" title="React event handlers">
+     Do not pass flow methods directly as event handlers (e.g. `onClick={next}` / `onPress={next}`). React will pass an event object as the first argument, which can accidentally be treated as a context update.
+
+     Always wrap: `onClick={() => next()}` / `onPress={() => next()}` (same for `skip()` and `setContext()`).
+   </Aside>
+
    #### Welcome Step
 
    ```tsx title="WelcomeStep.tsx"
diff --git a/apps/docs/src/content/docs/getting-started/why-useflow.mdx b/apps/docs/src/content/docs/getting-started/why-useflow.mdx
index cc11bef..69c4593 100644
--- a/apps/docs/src/content/docs/getting-started/why-useflow.mdx
+++ b/apps/docs/src/content/docs/getting-started/why-useflow.mdx
@@ -452,7 +452,7 @@ function UserTypeStep() {
       </form.Field>
       
       {/* useFlow handles multi-step navigation */}
-      <button type="button" onClick={back}>Back</button>
+      <button type="button" onClick={() => back()}>Back</button>
       <button type="submit">Continue</button>
     </form>
   );
diff --git a/apps/docs/src/content/docs/guides/branching-flows.mdx b/apps/docs/src/content/docs/guides/branching-flows.mdx
index fa46685..048a89e 100644
--- a/apps/docs/src/content/docs/guides/branching-flows.mdx
+++ b/apps/docs/src/content/docs/guides/branching-flows.mdx
@@ -562,7 +562,7 @@ export function SetupPreferenceStep() {
         </label>
       </div>
 
-      <button onClick={back}>Back</button>
+      <button onClick={() => back()}>Back</button>
       <button onClick={handleContinue} disabled={!context.setupMode}>
         Continue
       </button>
@@ -597,4 +597,3 @@ export function SetupPreferenceStep() {
     href="/guides/flow-variants"
   />
 </CardGrid>
-
diff --git a/apps/docs/src/content/docs/guides/custom-layouts.mdx b/apps/docs/src/content/docs/guides/custom-layouts.mdx
index cce1b6c..1a6a43e 100644
--- a/apps/docs/src/content/docs/guides/custom-layouts.mdx
+++ b/apps/docs/src/content/docs/guides/custom-layouts.mdx
@@ -108,7 +108,7 @@ Classic wizard with header, content, and footer:
         {/* Footer Navigation */}
         <footer className="border-t p-4">
           <div className="max-w-4xl mx-auto flex justify-between">
-            <button onClick={back} disabled={currentIndex === 0}>
+            <button onClick={() => back()} disabled={currentIndex === 0}>
               Back
             </button>
             <button onClick={() => next()}>
@@ -433,7 +433,7 @@ export function FlowLayout({
         <footer className="border-t p-4">
           <div className="max-w-4xl mx-auto flex justify-between">
             <button 
-              onClick={back} 
+              onClick={() => back()} 
               disabled={!canGoBack}
             >
               Back
@@ -594,7 +594,7 @@ function WizardLayout({ children }: { children: ReactNode }) {
       <header>Step: {stepId}</header>
       {children}
       <footer>
-        <button onClick={back}>Back</button>
+        <button onClick={() => back()}>Back</button>
         <button onClick={() => next()}>Next</button>
       </footer>
     </div>
@@ -692,7 +692,7 @@ export function OnboardingFlow() {
                       <div className="flex justify-between mt-8 pt-8 border-t">
                         {canGoBack ? (
                           <button 
-                            onClick={back}
+                            onClick={() => back()}
                             className="px-6 py-2 text-gray-600 hover:bg-gray-100 rounded-lg"
                           >
                             ← Back
@@ -743,4 +743,3 @@ export function OnboardingFlow() {
 - [Persistence](/guides/persistence) - Save flow progress
 - [Testing](/guides/testing) - Test custom layouts
 - [TypeScript](/getting-started/type-safety) - Type-safe layouts
-
diff --git a/apps/docs/src/content/docs/guides/linear-flows.mdx b/apps/docs/src/content/docs/guides/linear-flows.mdx
index e53c23d..000b0a1 100644
--- a/apps/docs/src/content/docs/guides/linear-flows.mdx
+++ b/apps/docs/src/content/docs/guides/linear-flows.mdx
@@ -464,8 +464,8 @@ function MyStep() {
 
   return (
     <div className="navigation">
-      {canGoBack && <button onClick={back}>Back</button>}
-      <button onClick={next}>Continue</button>
+      {canGoBack && <button onClick={() => back()}>Back</button>}
+      <button onClick={() => next()}>Continue</button>
     </div>
   );
 }
diff --git a/apps/docs/src/content/docs/guides/testing.mdx b/apps/docs/src/content/docs/guides/testing.mdx
index 36ace71..a0426e0 100644
--- a/apps/docs/src/content/docs/guides/testing.mdx
+++ b/apps/docs/src/content/docs/guides/testing.mdx
@@ -70,7 +70,7 @@ function NavigationTest() {
     <div>
       <div data-testid="current-step">{stepId}</div>
       <button onClick={() => next()}>Next</button>
-      <button onClick={back}>Back</button>
+      <button onClick={() => back()}>Back</button>
     </div>
   );
 }
diff --git a/apps/docs/src/content/docs/guides/troubleshooting.mdx b/apps/docs/src/content/docs/guides/troubleshooting.mdx
index d1bff23..b2593f8 100644
--- a/apps/docs/src/content/docs/guides/troubleshooting.mdx
+++ b/apps/docs/src/content/docs/guides/troubleshooting.mdx
@@ -170,7 +170,7 @@ function MyStep() {
   const { back, canGoBack } = useFlowState();
 
   return (
-    <button onClick={back} disabled={!canGoBack}>
+    <button onClick={() => back()} disabled={!canGoBack}>
       Back
     </button>
   );
diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx
index a20195c..a0e7c72 100644
--- a/apps/docs/src/content/docs/index.mdx
+++ b/apps/docs/src/content/docs/index.mdx
@@ -133,8 +133,8 @@ Build a complete onboarding flow with conditional navigation in 3 simple steps:
            value={context.company || ""} // 💡 TypeScript knows this is a string
            onChange={(e) => setContext({ company: e.target.value })}
          />
-         <button onClick={back}>Back</button> 
-         <button onClick={next}>Continue</button> 
+         <button onClick={() => back()}>Back</button> 
+         <button onClick={() => next()}>Continue</button> 
        </div>
      );
    }
diff --git a/apps/docs/src/content/docs/recipes/checkout.mdx b/apps/docs/src/content/docs/recipes/checkout.mdx
index 50931da..3d82f6b 100644
--- a/apps/docs/src/content/docs/recipes/checkout.mdx
+++ b/apps/docs/src/content/docs/recipes/checkout.mdx
@@ -453,7 +453,7 @@ export function ShippingStep() {
       {/* Navigation */}
       <div className="flex gap-3">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="px-6 py-2 border rounded-lg hover:bg-gray-50"
         >
           Back to Cart
@@ -556,7 +556,7 @@ export function PaymentStep() {
       {/* Navigation */}
       <div className="flex gap-3">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="px-6 py-2 border rounded-lg hover:bg-gray-50"
         >
           Back
@@ -653,7 +653,7 @@ export function ReviewStep() {
       {/* Actions */}
       <div className="flex gap-4">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="flex-1 px-6 py-3 border rounded"
         >
           Back to Payment
@@ -811,4 +811,3 @@ export function CheckoutFlow({ initialCart }: { initialCart: any[] }) {
 - [Survey Flow](/recipes/survey)
 - [Persistence Guide](/guides/persistence)
 - [Testing Guide](/guides/testing)
-
diff --git a/apps/docs/src/content/docs/recipes/onboarding.mdx b/apps/docs/src/content/docs/recipes/onboarding.mdx
index e529d63..7d43fa0 100644
--- a/apps/docs/src/content/docs/recipes/onboarding.mdx
+++ b/apps/docs/src/content/docs/recipes/onboarding.mdx
@@ -194,7 +194,7 @@ export function ProfileStep() {
       {/* Navigation */}
       <div className="flex gap-3">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="flex-1 px-4 py-2 border border-gray-300 rounded-lg hover:bg-gray-50"
         >
           Back
@@ -290,7 +290,7 @@ export function PreferencesStep() {
       {/* Navigation */}
       <div className="flex gap-3">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="px-4 py-2 border border-gray-300 rounded-lg hover:bg-gray-50"
         >
           Back
@@ -575,4 +575,3 @@ const persister = createPersister({
 - [Survey Flow](/recipes/survey)
 - [Persistence Guide](/guides/persistence)
 - [Testing Guide](/guides/testing)
-
diff --git a/apps/docs/src/content/docs/recipes/survey.mdx b/apps/docs/src/content/docs/recipes/survey.mdx
index d726776..86c2fcf 100644
--- a/apps/docs/src/content/docs/recipes/survey.mdx
+++ b/apps/docs/src/content/docs/recipes/survey.mdx
@@ -199,7 +199,7 @@ export function Question1Step() {
 
       <div className="flex gap-3 mt-8 max-w-2xl mx-auto">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="px-6 py-2 border rounded-lg hover:bg-gray-50"
         >
           Back
@@ -247,7 +247,7 @@ export function FeedbackStep() {
 
       <div className="flex gap-3 mt-6">
         <button
-          onClick={back}
+          onClick={() => back()}
           className="px-6 py-2 border rounded-lg hover:bg-gray-50"
         >
           Back
@@ -570,4 +570,3 @@ const surveyFlow = defineFlow({
 - [Branching Flows](/guides/branching-flows)
 - [Callbacks Guide](/guides/callbacks)
 - [Testing Guide](/guides/testing)
-
diff --git a/packages/react/README.md b/packages/react/README.md
index 00a2a49..939867d 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -116,8 +116,8 @@ function BusinessStep() {
         value={context.company || ""} // 💡 TypeScript knows this is a string
         onChange={(e) => setContext({ company: e.target.value })}
       />
-      <button onClick={back}>Back</button> 
-      <button onClick={next}>Continue</button> 
+      <button onClick={() => back()}>Back</button> 
+      <button onClick={() => next()}>Continue</button> 
     </div>
   );
 }

From 8df64a46eeb1dd829ca486c571078be36e167813 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Wed, 4 Feb 2026 13:13:01 -0600
Subject: [PATCH 3/9] docs: fix AsyncStorage store imports

---
 .../src/content/docs/api-reference/storage-stores.mdx     | 8 ++++----
 apps/docs/src/content/docs/guides/persistence.mdx         | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/apps/docs/src/content/docs/api-reference/storage-stores.mdx b/apps/docs/src/content/docs/api-reference/storage-stores.mdx
index 839caf6..6ab8fc3 100644
--- a/apps/docs/src/content/docs/api-reference/storage-stores.mdx
+++ b/apps/docs/src/content/docs/api-reference/storage-stores.mdx
@@ -63,7 +63,7 @@ const store = createMemoryStore();
 
 ```typescript
 import AsyncStorage from "@react-native-async-storage/async-storage";
-import { createAsyncStorageStore } from "@useflow/react-native";
+import { createAsyncStorageStore } from "@useflow/react";
 
 const store = createAsyncStorageStore(AsyncStorage, {
   prefix: "flow"  // Optional: custom key prefix
@@ -100,7 +100,7 @@ import {
 } from "@useflow/react";
 
 // Create store
-const store = createLocalStorageStore();
+const store = createLocalStorageStore(localStorage);
 
 // Create persister with store
 const persister = createPersister({ store });
@@ -147,7 +147,7 @@ describe('MyFlow', () => {
 ```typescript
 const store = process.env.NODE_ENV === 'test'
   ? createMemoryStore()
-  : createLocalStorageStore();
+  : createLocalStorageStore(localStorage);
 
 const persister = createPersister({ store });
 ```
@@ -370,4 +370,4 @@ const compressedStore: StorageStore = {
 
 - [createPersister()](/api-reference/create-persister) - Create persisters
 - [Persistence Guide](/guides/persistence) - Persistence patterns
-- [Custom Stores](/api-reference/custom-stores) - Advanced implementations
\ No newline at end of file
+- [Custom Stores](/api-reference/custom-stores) - Advanced implementations
diff --git a/apps/docs/src/content/docs/guides/persistence.mdx b/apps/docs/src/content/docs/guides/persistence.mdx
index 440a475..335fd17 100644
--- a/apps/docs/src/content/docs/guides/persistence.mdx
+++ b/apps/docs/src/content/docs/guides/persistence.mdx
@@ -74,7 +74,7 @@ import AsyncStorage from "@react-native-async-storage/async-storage";
 import {
   createAsyncStorageStore,
   createPersister,
-} from "@useflow/react-native";
+} from "@useflow/react";
 
 const store = createAsyncStorageStore(AsyncStorage);
 const persister = createPersister({ store });

From c228741a3b18010e6f1a9350829a2fd160479ffb Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Wed, 4 Feb 2026 13:13:43 -0600
Subject: [PATCH 4/9] docs(guides): add routing adapters guide

---
 apps/docs/astro.config.mjs                    |  1 +
 .../src/content/docs/guides/callbacks.mdx     |  2 +
 apps/docs/src/content/docs/guides/routing.mdx | 85 +++++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 apps/docs/src/content/docs/guides/routing.mdx

diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
index 91468e8..7748eea 100644
--- a/apps/docs/astro.config.mjs
+++ b/apps/docs/astro.config.mjs
@@ -124,6 +124,7 @@ export default defineConfig({
             { label: "Branching Flows", link: "/guides/branching-flows" },
             { label: "Flow Variants", link: "/guides/flow-variants" },
             { label: "Persistence", link: "/guides/persistence" },
+            { label: "Routing", link: "/guides/routing" },
             { label: "Callbacks", link: "/guides/callbacks" },
             { label: "Custom Layouts", link: "/guides/custom-layouts" },
             {
diff --git a/apps/docs/src/content/docs/guides/callbacks.mdx b/apps/docs/src/content/docs/guides/callbacks.mdx
index ab25336..411d1cb 100644
--- a/apps/docs/src/content/docs/guides/callbacks.mdx
+++ b/apps/docs/src/content/docs/guides/callbacks.mdx
@@ -254,6 +254,8 @@ Track every transition for analytics:
 
 Keep URL in sync with current step:
 
+For route-per-step flows (including Expo Router), see the [Routing guide](/guides/routing).
+
 ```tsx
 import { useRouter } from 'next/router';
 
diff --git a/apps/docs/src/content/docs/guides/routing.mdx b/apps/docs/src/content/docs/guides/routing.mdx
new file mode 100644
index 0000000..9d0660d
--- /dev/null
+++ b/apps/docs/src/content/docs/guides/routing.mdx
@@ -0,0 +1,85 @@
+---
+title: Routing
+description: Patterns for syncing useFlow with your app router (including Expo Router)
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+useFlow is framework-agnostic. When your UI is split across routes (one route per step), you’ll typically keep the **flow state** in useFlow and use your router to show the right screen for the current step.
+
+## Route-per-step pattern
+
+In this architecture:
+
+- Your router owns **what screen is visible**
+- useFlow owns **what step is current**, **the path/history**, and **the context**
+
+The simplest integration is **one-way sync**: when the flow transitions, you navigate.
+
+## Expo Router (React Native): one route per step
+
+Mount `<Flow />` in a stable layout (so it doesn’t unmount between step routes), and use `onTransition` to navigate.
+
+```tsx title="app/(onboarding)/_layout.tsx"
+import { Flow } from "@useflow/react";
+import { router, Stack } from "expo-router";
+
+import { onboardingFlow } from "@/features/onboarding/flow";
+
+type OnboardingStepId = keyof typeof onboardingFlow.config.steps & string;
+
+function getOnboardingRoute(stepId: OnboardingStepId) {
+  return `/onboarding/${stepId}` as const;
+}
+
+export default function OnboardingLayout() {
+  return (
+    <Flow
+      flow={onboardingFlow}
+      onTransition={({ to, direction }) => {
+        const route = getOnboardingRoute(to);
+
+        if (direction === "backward") {
+          router.back();
+          return;
+        }
+
+        router.push(route);
+      }}
+    >
+      {() => (
+        <Stack
+          screenOptions={{
+            headerShown: false,
+            gestureEnabled: false,
+            animation: "slide_from_right",
+          }}
+        />
+      )}
+    </Flow>
+  );
+}
+```
+
+<Aside type="tip" title="Why mount in a layout?">
+  In the route-per-step pattern, step screens are separate routes. Mounting `<Flow />` in a layout keeps flow state stable as the user navigates between routes.
+</Aside>
+
+## Two-way sync (advanced)
+
+Most apps only need Flow → Router sync. Two-way sync (Router → Flow) is only needed for advanced cases:
+
+- Deep linking directly to a mid-flow route
+- The user navigates via native back/gesture and you want flow `stepId`/`path` to match
+- Restoring a persisted flow state and ensuring the router reflects the restored step
+
+<Aside type="caution" title="Avoid ping-pong loops">
+  If you sync both directions, prevent infinite loops:
+
+  - Flow transition navigates the router
+  - Router navigation triggers a flow “go to step”
+  - That triggers another router navigation, etc.
+
+  Use a guard (e.g. compare current route vs desired route, or a ref flag) so each direction can no-op when it’s reacting to the other.
+</Aside>
+

From 72aec31fcafe439a282708c19d7cafce3f123e23 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Wed, 4 Feb 2026 13:15:57 -0600
Subject: [PATCH 5/9] feat(react): type step ids in Flow callbacks

---
 packages/react/src/flow.tsx                   | 64 ++++++++++---------
 .../react/src/type-tests/flow-step-ids.tsx    | 42 ++++++++++++
 packages/react/src/types.ts                   |  2 +-
 packages/react/src/use-flow-reducer.ts        | 25 +++++---
 4 files changed, 94 insertions(+), 39 deletions(-)
 create mode 100644 packages/react/src/type-tests/flow-step-ids.tsx

diff --git a/packages/react/src/flow.tsx b/packages/react/src/flow.tsx
index ab6781b..d385df2 100644
--- a/packages/react/src/flow.tsx
+++ b/packages/react/src/flow.tsx
@@ -73,11 +73,15 @@ type FlowProps<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>> = {
   flow: TFlow;
   children: (
     state: Omit<
-      UseFlowReturn<ExtractFlowContext<TFlow>, string, string>,
+      UseFlowReturn<
+        ExtractFlowContext<TFlow>,
+        string,
+        ExtractAllStepNames<TFlow> & string
+      >,
       "renderStep"
     > & {
       renderStep: (
-        elements: StepElements<ExtractAllStepNames<TFlow>>,
+        elements: StepElements<ExtractAllStepNames<TFlow> & string>,
       ) => ReactElement;
     },
   ) => ReactNode;
@@ -85,26 +89,26 @@ type FlowProps<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>> = {
   instanceId?: string;
   onComplete?: (event: { context: ExtractFlowContext<TFlow> }) => void;
   onNext?: (event: {
-    from: string;
-    to: string;
+    from: ExtractAllStepNames<TFlow> & string;
+    to: ExtractAllStepNames<TFlow> & string;
     oldContext: ExtractFlowContext<TFlow>;
     newContext: ExtractFlowContext<TFlow>;
   }) => void;
   onSkip?: (event: {
-    from: string;
-    to: string;
+    from: ExtractAllStepNames<TFlow> & string;
+    to: ExtractAllStepNames<TFlow> & string;
     oldContext: ExtractFlowContext<TFlow>;
     newContext: ExtractFlowContext<TFlow>;
   }) => void;
   onBack?: (event: {
-    from: string;
-    to: string;
+    from: ExtractAllStepNames<TFlow> & string;
+    to: ExtractAllStepNames<TFlow> & string;
     oldContext: ExtractFlowContext<TFlow>;
     newContext: ExtractFlowContext<TFlow>;
   }) => void;
   onTransition?: (event: {
-    from: string;
-    to: string;
+    from: ExtractAllStepNames<TFlow> & string;
+    to: ExtractAllStepNames<TFlow> & string;
     direction: "forward" | "backward";
     oldContext: ExtractFlowContext<TFlow>;
     newContext: ExtractFlowContext<TFlow>;
@@ -252,6 +256,8 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     flow.runtimeConfig?.resolvers as any,
   );
 
+  type StepId = ExtractAllStepNames<TFlow> & string;
+
   // Extract all steps (stripped down to only next property)
   const steps = useMemo(() => {
     return Object.fromEntries(
@@ -259,7 +265,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
         id,
         { next: step.next },
       ]),
-    ) as Record<string, StepInfo<string>>;
+    ) as Record<StepId, StepInfo<StepId>>;
   }, [config.steps]);
 
   // Extract possible next steps from current step
@@ -435,14 +441,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     // Handle navigation callbacks
     if (action === "NEXT" && prevState.stepId !== flowState.stepId) {
       onNext?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         direction: "forward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -460,14 +466,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
       });
     } else if (action === "SKIP" && prevState.stepId !== flowState.stepId) {
       onSkip?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         direction: "forward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -485,14 +491,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
       });
     } else if (action === "BACK" && prevState.stepId !== flowState.stepId) {
       onBack?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId,
-        to: flowState.stepId,
+        from: prevState.stepId as StepId,
+        to: flowState.stepId as StepId,
         direction: "backward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -645,8 +651,8 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
 
   // Create renderStep helper function
   const renderStep = useCallback(
-    (elements: StepElements<ExtractAllStepNames<TFlow>>): ReactElement => {
-      return elements[flowState.stepId as ExtractAllStepNames<TFlow>];
+    (elements: StepElements<StepId>): ReactElement => {
+      return elements[flowState.stepId as StepId];
     },
     [flowState.stepId],
   );
@@ -658,15 +664,13 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
 
   // Create the flow state object to pass to children
   const flowRenderState: Omit<
-    UseFlowReturn<ExtractFlowContext<TFlow>, string, string>,
+    UseFlowReturn<ExtractFlowContext<TFlow>, string, StepId>,
     "renderStep"
   > & {
-    renderStep: (
-      elements: StepElements<ExtractAllStepNames<TFlow>>,
-    ) => ReactElement;
+    renderStep: (elements: StepElements<StepId>) => ReactElement;
   } = {
     // From flowState
-    stepId: flowState.stepId,
+    stepId: flowState.stepId as StepId,
     step: flowState.step,
     context: flowState.context,
     path: flowState.path,
diff --git a/packages/react/src/type-tests/flow-step-ids.tsx b/packages/react/src/type-tests/flow-step-ids.tsx
new file mode 100644
index 0000000..19b780a
--- /dev/null
+++ b/packages/react/src/type-tests/flow-step-ids.tsx
@@ -0,0 +1,42 @@
+import { defineFlow, Flow } from "../index";
+
+const testFlow = defineFlow({
+  id: "type-tests",
+  start: "welcome",
+  steps: {
+    welcome: { next: "profile" },
+    profile: {},
+  },
+});
+
+type TestStepId = keyof typeof testFlow.config.steps & string;
+
+export function FlowStepIdTypeTest() {
+  return (
+    <Flow
+      flow={testFlow}
+      onTransition={(event) => {
+        const to: TestStepId = event.to;
+        const from: TestStepId = event.from;
+
+        void to;
+        void from;
+
+        // @ts-expect-error - step ids should be a literal union, not arbitrary strings
+        const _invalid: "does-not-exist" = event.to;
+        void _invalid;
+      }}
+    >
+      {({ stepId }) => {
+        const current: TestStepId = stepId;
+        void current;
+
+        // @ts-expect-error - step ids should be a literal union, not arbitrary strings
+        const _invalid: "does-not-exist" = stepId;
+        void _invalid;
+
+        return null;
+      }}
+    </Flow>
+  );
+}
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
index 13c7091..10904d5 100644
--- a/packages/react/src/types.ts
+++ b/packages/react/src/types.ts
@@ -44,7 +44,7 @@ export type UseFlowReturn<
   TContext extends FlowContext,
   TValidNextSteps extends string = string,
   TStepNames extends string = string,
-> = UseFlowReducerReturn<TContext, TValidNextSteps> & {
+> = UseFlowReducerReturn<TContext, TValidNextSteps, TStepNames> & {
   isRestoring: boolean;
   /**
    * Manually trigger a save when saveMode="manual"
diff --git a/packages/react/src/use-flow-reducer.ts b/packages/react/src/use-flow-reducer.ts
index 40c8606..810e0b5 100644
--- a/packages/react/src/use-flow-reducer.ts
+++ b/packages/react/src/use-flow-reducer.ts
@@ -33,9 +33,10 @@ export type FlowDefinition<
 export type UseFlowReducerReturn<
   TContext extends FlowContext,
   TValidNextSteps extends string = string,
+  TStepNames extends string = string,
 > = {
-  stepId: string;
-  step: CoreFlowDefinition["steps"][string];
+  stepId: TStepNames;
+  step: CoreFlowDefinition["steps"][TStepNames];
   context: TContext;
   status: "active" | "complete";
   /** Path taken through the flow - used for back navigation */
@@ -75,12 +76,16 @@ export type UseFlowReducerReturn<
  * @param resolvers - Optional resolver map for context-driven navigation
  * @returns Flow state and control functions
  */
-export function useFlowReducer<TContext extends FlowContext>(
+export function useFlowReducer<
+  TContext extends FlowContext,
+  TValidNextSteps extends string = string,
+  TStepNames extends string = string,
+>(
   definition: CoreFlowDefinition,
   initialContext: TContext,
   initialState?: FlowState<TContext>,
   resolvers?: RuntimeResolverMap<TContext>,
-): UseFlowReducerReturn<TContext> {
+): UseFlowReducerReturn<TContext, TValidNextSteps, TStepNames> {
   // Store initial context in a ref so it's stable across re-renders
   const initialContextRef = useRef(initialContext);
 
@@ -103,7 +108,7 @@ export function useFlowReducer<TContext extends FlowContext>(
       }
     },
     [],
-  );
+  ) as UseFlowReducerReturn<TContext, TValidNextSteps, TStepNames>["next"];
 
   const skip = useCallback(
     (
@@ -118,7 +123,7 @@ export function useFlowReducer<TContext extends FlowContext>(
       }
     },
     [],
-  );
+  ) as UseFlowReducerReturn<TContext, TValidNextSteps, TStepNames>["skip"];
 
   const back = useCallback(() => {
     dispatch({ type: "BACK" });
@@ -137,8 +142,12 @@ export function useFlowReducer<TContext extends FlowContext>(
   }, []);
 
   return {
-    stepId: state.stepId,
-    step: definition.steps[state.stepId] ?? {},
+    stepId: state.stepId as TStepNames,
+    step: (definition.steps[state.stepId] ?? {}) as UseFlowReducerReturn<
+      TContext,
+      TValidNextSteps,
+      TStepNames
+    >["step"],
     context: state.context,
     status: state.status,
     path: state.path,

From a96f0c0c2d77965490c0877ab57672095f2e458e Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Thu, 16 Apr 2026 01:21:39 -0500
Subject: [PATCH 6/9] fix(react): propagate typed step ids in Flow

---
 packages/react/src/flow.tsx | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/react/src/flow.tsx b/packages/react/src/flow.tsx
index d385df2..e57c0c2 100644
--- a/packages/react/src/flow.tsx
+++ b/packages/react/src/flow.tsx
@@ -246,8 +246,10 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
   // Track if we're currently restoring state from persister
   const [isRestoring, setIsRestoring] = useState(!!persister);
 
+  type StepId = ExtractAllStepNames<TFlow> & string;
+
   // Initialize flow state (restoration happens after mount)
-  const flowState = useFlowReducer<ExtractFlowContext<TFlow>>(
+  const flowState = useFlowReducer<ExtractFlowContext<TFlow>, string, StepId>(
     flowDefinitionWithoutComponents,
     initialContext ?? ({} as ExtractFlowContext<TFlow>),
     undefined, // initialState - restoration happens in useEffect
@@ -256,8 +258,6 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     flow.runtimeConfig?.resolvers as any,
   );
 
-  type StepId = ExtractAllStepNames<TFlow> & string;
-
   // Extract all steps (stripped down to only next property)
   const steps = useMemo(() => {
     return Object.fromEntries(
@@ -441,14 +441,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     // Handle navigation callbacks
     if (action === "NEXT" && prevState.stepId !== flowState.stepId) {
       onNext?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         direction: "forward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -466,14 +466,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
       });
     } else if (action === "SKIP" && prevState.stepId !== flowState.stepId) {
       onSkip?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         direction: "forward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -491,14 +491,14 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
       });
     } else if (action === "BACK" && prevState.stepId !== flowState.stepId) {
       onBack?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         oldContext: prevState.context,
         newContext: flowState.context,
       });
       onTransition?.({
-        from: prevState.stepId as StepId,
-        to: flowState.stepId as StepId,
+        from: prevState.stepId,
+        to: flowState.stepId,
         direction: "backward",
         oldContext: prevState.context,
         newContext: flowState.context,
@@ -652,7 +652,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
   // Create renderStep helper function
   const renderStep = useCallback(
     (elements: StepElements<StepId>): ReactElement => {
-      return elements[flowState.stepId as StepId];
+      return elements[flowState.stepId];
     },
     [flowState.stepId],
   );
@@ -670,7 +670,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     renderStep: (elements: StepElements<StepId>) => ReactElement;
   } = {
     // From flowState
-    stepId: flowState.stepId as StepId,
+    stepId: flowState.stepId,
     step: flowState.step,
     context: flowState.context,
     path: flowState.path,

From ec22c7e0433c3db1873ca9c6458c335e2b9aea24 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Thu, 16 Apr 2026 01:47:08 -0500
Subject: [PATCH 7/9] fix(react): narrow render-prop navigation targets

---
 packages/react/src/flow.tsx                     | 14 ++++++++------
 packages/react/src/type-tests/flow-step-ids.tsx | 14 +++++++++++++-
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/packages/react/src/flow.tsx b/packages/react/src/flow.tsx
index e57c0c2..5227f25 100644
--- a/packages/react/src/flow.tsx
+++ b/packages/react/src/flow.tsx
@@ -30,7 +30,9 @@ import type {
 import { useFlowReducer } from "./use-flow-reducer";
 
 // biome-ignore lint/suspicious/noExplicitAny: React Context requires concrete type at creation, type safety enforced at usage via generics
-const ReactFlowContext = createContext<UseFlowReturn<any> | null>(null);
+const ReactFlowContext = createContext<UseFlowReturn<any, any, any> | null>(
+  null,
+);
 
 /**
  * Get the current flow state from context
@@ -75,7 +77,7 @@ type FlowProps<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>> = {
     state: Omit<
       UseFlowReturn<
         ExtractFlowContext<TFlow>,
-        string,
+        ExtractAllStepNames<TFlow> & string,
         ExtractAllStepNames<TFlow> & string
       >,
       "renderStep"
@@ -269,13 +271,13 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
   }, [config.steps]);
 
   // Extract possible next steps from current step
-  const nextSteps = useMemo(() => {
-    const currentStep = config.steps[flowState.stepId];
+  const nextSteps = useMemo<readonly StepId[] | undefined>(() => {
+    const currentStep = steps[flowState.stepId];
     if (!currentStep?.next) return undefined;
     return typeof currentStep.next === "string"
       ? [currentStep.next]
       : currentStep.next;
-  }, [config.steps, flowState.stepId]);
+  }, [steps, flowState.stepId]);
 
   // Track previous state for callbacks
   const previousStateRef = useRef(flowState);
@@ -664,7 +666,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
 
   // Create the flow state object to pass to children
   const flowRenderState: Omit<
-    UseFlowReturn<ExtractFlowContext<TFlow>, string, StepId>,
+    UseFlowReturn<ExtractFlowContext<TFlow>, StepId, StepId>,
     "renderStep"
   > & {
     renderStep: (elements: StepElements<StepId>) => ReactElement;
diff --git a/packages/react/src/type-tests/flow-step-ids.tsx b/packages/react/src/type-tests/flow-step-ids.tsx
index 19b780a..b6b9f19 100644
--- a/packages/react/src/type-tests/flow-step-ids.tsx
+++ b/packages/react/src/type-tests/flow-step-ids.tsx
@@ -27,14 +27,26 @@ export function FlowStepIdTypeTest() {
         void _invalid;
       }}
     >
-      {({ stepId }) => {
+      {({ next, nextSteps, skip, stepId }) => {
         const current: TestStepId = stepId;
         void current;
 
+        const allowedNextSteps: readonly TestStepId[] | undefined = nextSteps;
+        void allowedNextSteps;
+
+        next("profile");
+        skip("profile");
+
         // @ts-expect-error - step ids should be a literal union, not arbitrary strings
         const _invalid: "does-not-exist" = stepId;
         void _invalid;
 
+        // @ts-expect-error - render-prop navigation targets should be known step ids
+        next("does-not-exist");
+
+        // @ts-expect-error - render-prop skip targets should be known step ids
+        skip("does-not-exist");
+
         return null;
       }}
     </Flow>

From 8c81a29f9e49d10d001f8b008645a47ea20ee285 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Tue, 19 May 2026 21:00:35 -0500
Subject: [PATCH 8/9] fix(react): preserve step-local render prop targets

---
 packages/react/src/flow.tsx                   | 25 ++-----
 packages/react/src/index.ts                   |  2 +
 .../react/src/type-tests/flow-step-ids.tsx    | 67 ++++++++++++++++---
 packages/react/src/types.ts                   | 31 +++++++++
 4 files changed, 95 insertions(+), 30 deletions(-)

diff --git a/packages/react/src/flow.tsx b/packages/react/src/flow.tsx
index 5227f25..ef5a674 100644
--- a/packages/react/src/flow.tsx
+++ b/packages/react/src/flow.tsx
@@ -23,6 +23,7 @@ import type {
   ExtractAllStepNames,
   ExtractFlowContext,
   FlowDefinition,
+  FlowRenderState,
   StepElements,
   StepInfo,
   UseFlowReturn,
@@ -73,20 +74,7 @@ export function useFlowState<
 // biome-ignore lint/suspicious/noExplicitAny: Generic constraint requires 'any' for flexible context type inference
 type FlowProps<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>> = {
   flow: TFlow;
-  children: (
-    state: Omit<
-      UseFlowReturn<
-        ExtractFlowContext<TFlow>,
-        ExtractAllStepNames<TFlow> & string,
-        ExtractAllStepNames<TFlow> & string
-      >,
-      "renderStep"
-    > & {
-      renderStep: (
-        elements: StepElements<ExtractAllStepNames<TFlow> & string>,
-      ) => ReactElement;
-    },
-  ) => ReactNode;
+  children: (state: FlowRenderState<TFlow>) => ReactNode;
   initialContext?: ExtractFlowContext<TFlow>;
   instanceId?: string;
   onComplete?: (event: { context: ExtractFlowContext<TFlow> }) => void;
@@ -665,12 +653,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
   }
 
   // Create the flow state object to pass to children
-  const flowRenderState: Omit<
-    UseFlowReturn<ExtractFlowContext<TFlow>, StepId, StepId>,
-    "renderStep"
-  > & {
-    renderStep: (elements: StepElements<StepId>) => ReactElement;
-  } = {
+  const flowRenderState = {
     // From flowState
     stepId: flowState.stepId,
     step: flowState.step,
@@ -696,7 +679,7 @@ export function Flow<TFlow extends RuntimeFlowDefinition<FlowDefinition, any>>({
     canGoBack: flowState.path.length > 1,
     canGoNext: nextSteps !== undefined,
     renderStep,
-  };
+  } as FlowRenderState<TFlow>;
 
   return (
     <ReactFlowContext.Provider value={flowRenderState}>
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 3703f00..27dcfaa 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -44,7 +44,9 @@ export type {
 export { FlowProvider, useFlowConfig } from "./provider";
 export type {
   ExtractAllStepNames,
+  ExtractValidNextSteps,
   FlowDefinition,
+  FlowRenderState,
   StepElements,
   UseFlowReturn,
 } from "./types";
diff --git a/packages/react/src/type-tests/flow-step-ids.tsx b/packages/react/src/type-tests/flow-step-ids.tsx
index b6b9f19..7eb0c56 100644
--- a/packages/react/src/type-tests/flow-step-ids.tsx
+++ b/packages/react/src/type-tests/flow-step-ids.tsx
@@ -27,25 +27,74 @@ export function FlowStepIdTypeTest() {
         void _invalid;
       }}
     >
-      {({ next, nextSteps, skip, stepId }) => {
-        const current: TestStepId = stepId;
+      {(state) => {
+        const current: TestStepId = state.stepId;
         void current;
 
-        const allowedNextSteps: readonly TestStepId[] | undefined = nextSteps;
+        const allowedNextSteps: readonly TestStepId[] | undefined =
+          state.nextSteps;
         void allowedNextSteps;
 
-        next("profile");
-        skip("profile");
-
         // @ts-expect-error - step ids should be a literal union, not arbitrary strings
-        const _invalid: "does-not-exist" = stepId;
+        const _invalid: "does-not-exist" = state.stepId;
         void _invalid;
 
         // @ts-expect-error - render-prop navigation targets should be known step ids
-        next("does-not-exist");
+        state.next("does-not-exist");
 
         // @ts-expect-error - render-prop skip targets should be known step ids
-        skip("does-not-exist");
+        state.skip("does-not-exist");
+
+        // @ts-expect-error - explicit render-prop targets require narrowing by stepId
+        state.next("profile");
+
+        if (state.stepId === "welcome") {
+          const welcomeNextSteps: readonly "profile"[] | undefined =
+            state.nextSteps;
+          void welcomeNextSteps;
+
+          state.next("profile");
+          state.skip("profile");
+
+          // @ts-expect-error - welcome can only navigate directly to profile
+          state.next("welcome");
+
+          // @ts-expect-error - welcome can only skip directly to profile
+          state.skip("welcome");
+        }
+
+        if (state.stepId === "profile") {
+          const terminalNextSteps: readonly never[] | undefined =
+            state.nextSteps;
+          void terminalNextSteps;
+
+          // @ts-expect-error - profile is terminal and has no explicit next target
+          state.next("welcome");
+
+          // @ts-expect-error - profile is terminal and has no explicit skip target
+          state.skip("welcome");
+        }
+
+        return null;
+      }}
+    </Flow>
+  );
+}
+
+export function FlowRenderPropDestructureTypeTest() {
+  return (
+    <Flow flow={testFlow}>
+      {({ next, skip, stepId }) => {
+        if (stepId === "welcome") {
+          next("profile");
+          skip("profile");
+
+          // @ts-expect-error - destructured render props should preserve step-local next targets
+          next("welcome");
+
+          // @ts-expect-error - destructured render props should preserve step-local skip targets
+          skip("welcome");
+        }
 
         return null;
       }}
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
index 10904d5..2531f8a 100644
--- a/packages/react/src/types.ts
+++ b/packages/react/src/types.ts
@@ -122,6 +122,10 @@ export type ValidNextSteps<
     : never
   : never;
 
+type FlowRenderStep<TFlow> = (
+  elements: StepElements<ExtractAllStepNames<TFlow> & string>,
+) => ReactElement;
+
 /**
  * Extract all possible step names from a flow type
  * Uses distributive conditional types to handle a union of flows automatically
@@ -146,3 +150,30 @@ export type ExtractFlowContext<TFlow> = TFlow extends RuntimeFlowDefinition<
 >
   ? TContext
   : FlowContext;
+
+export type ExtractValidNextSteps<
+  TFlow,
+  TStep extends ExtractAllStepNames<TFlow> & string,
+> = TFlow extends RuntimeFlowDefinition<
+  infer TDefinition,
+  // biome-ignore lint/suspicious/noExplicitAny: Required for TypeScript conditional type inference
+  any
+>
+  ? TStep extends StepNames<TDefinition>
+    ? ValidNextSteps<TDefinition, TStep> & string
+    : never
+  : never;
+
+export type FlowRenderState<TFlow> = {
+  [TStep in ExtractAllStepNames<TFlow> & string]: Omit<
+    UseFlowReturn<
+      ExtractFlowContext<TFlow>,
+      ExtractValidNextSteps<TFlow, TStep>,
+      ExtractAllStepNames<TFlow> & string
+    >,
+    "renderStep" | "stepId"
+  > & {
+    stepId: TStep;
+    renderStep: FlowRenderStep<TFlow>;
+  };
+}[ExtractAllStepNames<TFlow> & string];

From 9703de38baa304ae730088019b439adbdf952320 Mon Sep 17 00:00:00 2001
From: Brian Cheung <bcheung.dev@gmail.com>
Date: Tue, 19 May 2026 21:50:31 -0500
Subject: [PATCH 9/9] chore: add changeset for Flow typing release

---
 .changeset/typed-flow-render-props.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/typed-flow-render-props.md

diff --git a/.changeset/typed-flow-render-props.md b/.changeset/typed-flow-render-props.md
new file mode 100644
index 0000000..87e6e5d
--- /dev/null
+++ b/.changeset/typed-flow-render-props.md
@@ -0,0 +1,5 @@
+---
+"@useflow/react": minor
+---
+
+Improve Flow render-prop typing so step IDs, next steps, and explicit next/skip targets are inferred from the flow definition and narrowed by the current step.