fix: clear stale onboarding modal session state

[Ajit-Mehrotra]

Summary

This PR audits onboarding persistence across the Vue/Pinia layer, browser storage, and the API-backed onboarding tracker, then removes the stale browser-session flag that could suppress onboarding on a later fresh install.

Problem

During testing on a fresh installation, the onboarding modal did not appear because the browser still had this key in sessionStorage:

• onboardingModalHidden: "true"

That key was acting as a persistent UI override even though it was not authoritative onboarding state. In practice, a prior dev/test flow in the same browser session could hide onboarding for a new install.

Root Cause

The onboarding modal visibility store persisted isHidden to sessionStorage under onboardingModalHidden. That value was separate from the real onboarding completion state and could outlive the install context it came from.

The actual source of truth for onboarding completion is server-side in onboarding-tracker.json via the API onboarding tracker service. The browser-hidden flag should never have been able to suppress a new fresh-install flow on its own.

Audit Findings

Pinia / browser state

• onboardingDraft is intentionally persisted in localStorage so users can resume in-progress onboarding work.
• onboardingTemporaryBypass is intentionally persisted in sessionStorage so the temporary bypass survives reloads within the same browser session and current boot.
• onboardingModalHidden was the unsafe piece. It persisted a modal UI override beyond the flow where it was set.

API-backed state

• The backend onboarding tracker persists completed and completedAtVersion to disk and remains the authoritative onboarding state.
• Existing completion / reset behavior on the API side looked correct and was not the source of the bug.

Existing cleanup behavior

• Draft cleanup was already happening on onboarding completion, skip, and normal modal exit paths.
• The missing piece was cleanup of the stale hidden-session key and removing its persistence going forward.

Changes

• Stop persisting the onboarding modal isHidden override in sessionStorage.
• Keep isHidden as in-memory Pinia UI state only.
• Add cleanup for the legacy onboardingModalHidden sessionStorage key on store mount.
• Include legacy hidden-key cleanup in the shared onboarding storage cleanup helper.
• Add regression tests covering the removal of the hidden key and the new non-persistent visibility behavior.

Why this approach

This keeps the useful pieces of onboarding persistence while removing the risky one:

• Keep draft persistence so users do not lose onboarding progress.
• Keep temporary bypass persistence so the bypass works within the current browser session / boot.
• Keep API persistence as the source of truth for onboarding completion.
• Remove persisted modal-hidden UI state so a stale browser session cannot suppress a later fresh install.

Testing

Ran:

• pnpm test -- web/test/store/onboardingModalVisibility.test.ts web/test/components/Onboarding/onboardingStorageCleanup.test.ts web/test/components/Onboarding/OnboardingModal.test.ts web/test/components/Onboarding/OnboardingSummaryStep.test.ts

Result:

• Vitest passed successfully in the worktree: 61 test files passed, 605 tests passed, 6 skipped.

Notes

This PR intentionally keeps cleanup for the old onboardingModalHidden key so any browser sessions that already have the stale value get healed automatically after upgrade.

Summary by CodeRabbit

• New Features

  • Added automatic cleanup of legacy onboarding storage data on app startup.

• Bug Fixes

  • Improved onboarding modal state persistence and initialization.

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 50.78%. Comparing base (8742cac) to head (7f45b2e).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
...nents/Onboarding/store/onboardingStorageCleanup.ts	72.72%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1904      +/-   ##
==========================================
- Coverage   50.78%   50.78%   -0.01%     
==========================================
  Files        1022     1022              
  Lines       70518    70524       +6     
  Branches     7647     7649       +2     
==========================================
+ Hits        35811    35814       +3     
- Misses      34584    34587       +3     
  Partials      123      123              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ffa76997-8d7a-415c-9f59-c6a6d70b894a

📥 Commits

Reviewing files that changed from the base of the PR and between 298da54 and 7f45b2e.

📒 Files selected for processing (4)

• web/__test__/components/Onboarding/onboardingStorageCleanup.test.ts
• web/__test__/store/onboardingModalVisibility.test.ts
• web/src/components/Onboarding/store/onboardingModalVisibility.ts
• web/src/components/Onboarding/store/onboardingStorageCleanup.ts

---

Walkthrough

Refactors onboarding modal visibility state from persistent session storage to in-memory ref. Adds a new cleanup function to remove legacy hidden state from sessionStorage on component mount, with corresponding test updates to verify the new storage approach.

Changes

Cohort / File(s)	Summary
Storage Cleanup Implementation web/src/components/Onboarding/store/onboardingStorageCleanup.ts, web/__test__/components/Onboarding/onboardingStorageCleanup.test.ts	Added new exported function clearLegacyOnboardingModalHiddenSessionState() to safely remove legacy hidden state from sessionStorage; updated cleanup function to invoke it; added corresponding test cases validating the cleanup behavior.
Visibility State Refactoring web/src/components/Onboarding/store/onboardingModalVisibility.ts	Migrated isHidden from useSessionStorage to in-memory ref; introduced clearLegacyOnboardingModalHiddenSessionState() call in onMounted lifecycle; integrated clearOnboardingDraftStorage into setTemporaryBypass logic.
Test Updates web/__test__/store/onboardingModalVisibility.test.ts	Removed local mock for hidden state; replaced all direct mockIsHidden accesses with store.isHidden; adjusted mock call indices for useSessionStorage; added test for legacy storage cleanup on mount; updated assertions across onboarding flow tests to verify store-driven state.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Away with storage, into memory we go,
Legacy keys laid to rest nice and slow,
The modal hides cleaner, a lighter refrain,
No sessionStorage bloat to burden the brain! ✨

🚥 Pre-merge checks | ✅ 3

✅ 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: clear stale onboarding modal session state' accurately summarizes the main change—removing and clearing a legacy sessionStorage key for onboarding modal visibility. It is concise, specific, and directly reflects the primary objective of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/onboarding-storage-audit

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

This plugin has been deployed to Cloudflare R2 and is available for testing.
Download it at this URL:

https://preview.dl.unraid.net/unraid-api/tag/PR1904/dynamix.unraid.net.plg