fix(web): preserve node progress on Play resume + drill-back

[naorsabag]

Two related bugs, same root: cumulative state (per-node progress + create/destroy) wasn't re-derived from the step index on key transitions.

What's fixed

1. Click-then-Play kept stale progress

Clicking a node fires its next outgoing step manually (good). But that increment lives in nodeProgressRef, which autoplay also uses. So:

• Pause mid-step. Click node X → X's progress bar advances by 1.
• Press Play → autoplay resumes from where it was. X's bar now permanently ahead of autoplay's expectation; gets pushed further every time autoplay fires X.

2. Drill-down → Back wiped parent's progress

<FlowCanvasInner> is keyed on the node-id list, so drilling into a sub-flow remounts the inner component on return — fresh nodeProgressRef = new Map(). Even though resumeFromStep was correctly seeded into stepIndexRef, the per-node bars all snapped to zero.

Implementation

• Extract the inline cumulative-replay logic from goToStep into a shared applyEffectsThroughStep(idx) helper.
• New mount-time useEffect: if stepIndexRef.current >= 0 on first render (i.e., startFromStep was set), replay 0..stepIndexRef and push into state. Fixes Compose roads from a single line #2.
• Play-resume branch in the [playing] effect now also replays before re-entering the phase. Fixes fix: tighten road endpoints against node art #1.
• goToStep refactored to use the same helper — no behavior change.

Verification

• npm run typecheck — clean
• npm test — 40/40
• npm run format:check — clean

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Fixed animation playback to properly replay state when resuming mid-phase.
  • Improved animation consistency when starting from custom positions.
  • Manual scrubbing now applies the same cumulative effects as autoplay mode.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 47eb6f23-9eb7-4f76-ab51-9c190f520355

📥 Commits

Reviewing files that changed from the base of the PR and between dc7abd7 and bc2c90d.

📒 Files selected for processing (1)

• packages/web/src/hooks/useFlowAnimation.ts

---

Walkthrough

The PR refactors useFlowAnimation to centralize cumulative step effect replay through a new applyEffectsThroughStep helper function. This helper is now invoked during play-resume mid-phase, mount initialization with a non-zero startFromStep, and manual step navigation, ensuring consistent node progress and visibility state reconstruction across all entry points.

Changes

Cumulative Step Effects Replay

Layer / File(s)	Summary
Cumulative Effects Helper packages/web/src/hooks/useFlowAnimation.ts	Introduces applyEffectsThroughStep(idx) to reconstruct nodeProgress, activeNodes, and destroyedNodes for steps 0..idx. Includes mount-only effect that replays when startFromStep > 0 so initial state matches autoplay expectations.
Play-Resume Integration packages/web/src/hooks/useFlowAnimation.ts	On playing resume with an active phase, cumulative effects through current stepIndexRef are replayed before re-entering React state, ensuring node/edge visibility is consistent with resumed playback.
goToStep Refactoring packages/web/src/hooks/useFlowAnimation.ts	goToStep(idx) now calls shared applyEffectsThroughStep(idx) instead of duplicating cumulative create/destroy and per-node progress logic. Dependency list updated to include applyEffectsThroughStep.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• naorsabag/openhop#93: Both PRs modify the same hook with cumulative step effect replay and goToStep refactoring.
• naorsabag/openhop#90: Both PRs modify useFlowAnimation to change phase-aware timing and cumulative step effect application.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR objectives address fixing node progress preservation on Play resume and drill-back, but the linked issues (#1, #2) concern road rendering composition and node handle positioning, which are unrelated coding requirements.	Verify that the linked issues are correct. If issues #1 and #2 are unrelated, remove them and link to issues that define the node progress fix requirements instead.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(web): preserve node progress on Play resume + drill-back' clearly and specifically describes the main fix: preventing loss of node progress when resuming playback and returning from nested flows.
Out of Scope Changes check	✅ Passed	Changes are focused on useFlowAnimation.ts and specifically address node progress replay logic, mount-time state restoration, and Play-resume reconciliation—all directly related to the PR's stated objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/preserve-progress-on-resume-and-drillback

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}