fix(guided-study): stepper taps no longer bounce back to initialStep

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s

[CraigBuckmaster]

Problem

On any chapter where the user had previously advanced the guided study past the scene step, opening the study session from ChapterScreen's StudySessionCTA makes every stepper tap appear inert. Tapping Scene / Observe / Explore / Synthesize does nothing visible — the highlighted pill snaps right back to whatever step the route was opened with.

Reproduced on the iOS simulator (rentamac) during post-merge review of #1602.

Root cause

StudySessionScreen.tsx had a naive sync effect:

useEffect(()=>{if(initialStep&&sessionId!=null&&currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

With currentStep in the dependency array and no one-shot guard, the effect re-fires every time currentStep changes:

1. User taps "Observe" → setCurrentStep('observe') → currentStep is 'observe'
2. Effect re-runs on the change → sees currentStep !== initialStep ('review') → calls setSessionStep('review')
3. State snaps back to 'review' within one render cycle

Taps were registering fine; they just got reverted instantly. Explains why one user reported "I can't tap any of the other options above (Scene, observe, explore, etc)" — they could tap, they just couldn't stay.

Fix

Guard the sync with a useRef keyed on sessionId. The sync runs exactly once per session load (when sessionId first becomes non-null) and short-circuits on every subsequent re-run:

constappliedInitialStepForSessionRef=useRef<number|null>(null);useEffect(()=>{if(sessionId==null||!initialStep)return;if(appliedInitialStepForSessionRef.current===sessionId)return;appliedInitialStepForSessionRef.current=sessionId;if(currentStep!==initialStep){voidsetSessionStep(initialStep);}},[currentStep,initialStep,sessionId,setSessionStep]);

The ref is keyed on sessionId (not just a boolean) so that if the user navigates to a different chapter without unmounting — chapter?.id changes, the hook loads a new session, sessionId updates — the new initialStep still applies for the new session. For a stable session, re-renders that carry the same sessionId no-op.

What this does NOT change

• goStep still awaits savePromptDrafts() and saveSynthesis() before calling setCurrentStep. The draft-persistence side effects on step change are preserved.
• No change to useGuidedStudySession hook. The persistence semantics are unchanged.
• No change to ChapterScreen's StudySessionCTA route props. The initialStep param still flows through and is still honored on first load.

Out of scope (follow-ups flagged separately)

The review session also surfaced a cosmetic concern in StudyModeSelector — the active-state background is ${base.gold}16 (~9% opacity gold tint), which in the sepia theme is barely distinguishable from base.bgSurface. Taps there are functionally working (pure React state), but the visual affordance is weak. Captured in #1652 under "also observed" for the Guided Study re-plan; not fixed here.

Test plan

• npx tsc --noEmit — expected to pass (only added useRef to an existing React import).
• npx jest — existing tests should pass; no screen-level test exists for StudySessionScreen (pattern: MyStudyScreen.test.tsx also absent). Hook tests in __tests__/hooks/useGuidedStudySession.test.ts are unaffected since the fix lives in the consuming screen.
• Manual (rentamac iOS simulator):
  1. Open Genesis 1, advance the guided study past "Scene" (tap "Begin observing" or use the stepper), back out to the chapter.
  2. Tap Continue Study from the CTA.
  3. Screen should arrive on the step you left (as before).
  4. Tap any other stepper pill — the UI should switch to that phase and stay.
  5. Tap back through several pills to confirm no bounce.

Rollback

Revert the single commit. Reverts behavior to the existing bounce-back bug — no schema, no persistence, no store changes to unwind.

Discovered during rentamac review on April 24 2026. Companion to #1653 (Canon Comparison tab-stretch fix) and #1652 (Guided Study re-plan capture card).

[github-actions]

Test Results

✅ All tests passed

	Passed	Failed	Total
Tests	✅ 3617	❌ 0	3617
Suites	✅ 491	❌ 0	491

Coverage

Statements	Branches	Functions	Lines
—	—	—	—

⏱️ Duration: 70.6s