fix(themes): prevent reset on license errors, improve switch performance

[s0up4200]

Summary

• Adds 7-day grace period for license validation to prevent premium theme resets on transient API failures (fixes Fix/premium theme resets to default after idle time #837)
• Caches license entitlement in localStorage for offline/error resilience
• Reduces license API polling from 30s to 1h with retry support
• Blocks premium theme switching during errors unless within grace period
• Shows warning banner when license verification is unavailable
• Drastically improves theme switch performance by removing heavy CSS transitions
• Makes font loading non-blocking
• Coalesces PWA theme updates via requestAnimationFrame

Test plan

• Verify premium theme persists when license API is temporarily unavailable
• Verify premium theme switching is blocked during API errors (unless within grace)
• Verify theme switching feels instant (no lag)
• Verify warning banner appears when license check fails
• Verify license deletion clears cached entitlement

Summary by CodeRabbit

• New Features

  • PWA mobile app capability enabled for improved mobile experience.
  • License-aware premium theme gating with offline grace-period persistence and clearer verification handling.
  • Theme preview caching and variation previews in the theme picker.

• Improvements

  • More descriptive error messaging, warning banner when verification is unavailable, and gated premium actions.
  • Debounced theme update scheduling to reduce redundant updates.
  • Shorter, optional theme transitions (150ms) and non-blocking font loading for snappier changes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a local license-entitlement store with a 7-day grace period and entitlement-aware gating for premium themes; propagates license error state through hooks; updates theme validation to preserve themes during transient failures; debounces PWA theme updates, shortens theme transitions, and adds a mobile-web-app meta tag.

Changes

Cohort / File(s)	Summary
License Entitlement Module web/src/lib/license-entitlement.ts	New module providing localStorage-backed entitlement persistence, GRACE_PERIOD_MS, LicenseEntitlement type, getLicenseEntitlement, setLicenseEntitlement, clearLicenseEntitlement, isWithinGracePeriod, and canSwitchToPremiumTheme with grace-period fallback logic.
License Hook Updates web/src/hooks/useLicense.ts	Syncs license entitlement to storage on successful fetch, clears on delete success, and surfaces isError in returns; useHasPremiumAccess now returns { hasPremiumAccess, isLoading, isError }.
Theme Validation & Related Components web/src/components/themes/ThemeValidator.tsx, web/src/components/themes/ThemeSelector.tsx	ThemeValidator refactored to use entitlement/grace logic, interval raised to 1 hour, returns null; ThemeSelector uses canSwitchToPremiumTheme, shows a distinct banner/toast when license verification fails.
Theme Selection Handlers web/src/components/layout/MobileFooterNav.tsx, web/src/components/ui/ThemeToggle.tsx	Replace direct hasPremiumAccess checks with canSwitchToPremiumTheme({ hasPremiumAccess, isLoading, isError }); gate premium theme/variation switches on that result; surface distinct messages for verification errors vs missing entitlement; update hook dependencies.
Theme & PWA Utilities web/src/utils/theme.ts, web/src/utils/pwaNativeTheme.ts	theme.ts: add ENABLE_THEME_TRANSITIONS (default false), reduce transition duration to 150ms, make font loading non-blocking, gate transitions. pwaNativeTheme.ts: add debounced scheduleUpdate to coalesce theme updates and prefer stored critical vars for background color.
Metadata web/index.html	Added <meta name="mobile-web-app-capable" content="yes" /> in the head.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant UI as Theme UI (Selector/Toggle/Nav)
    participant Hook as useHasPremiumAccess
    participant API as License API
    participant Lib as license-entitlement
    participant Storage as localStorage

    User->>UI: Select premium theme
    UI->>Hook: request license state
    Hook->>API: fetch license
    alt API Success
        API-->>Hook: { hasPremiumAccess: true/false }
        Hook->>Lib: setLicenseEntitlement(hasPremiumAccess) (on success)
        Hook-->>UI: { hasPremiumAccess, isLoading:false, isError:false }
        UI->>Lib: canSwitchToPremiumTheme({hasPremiumAccess,false,false}) → allow/deny
        UI-->>User: apply theme or show premium prompt
    else API Error
        API-->>Hook: error
        Hook-->>UI: { hasPremiumAccess: undefined, isLoading:false, isError:true }
        UI->>Lib: getLicenseEntitlement()
        Lib->>Storage: read stored entitlement
        alt Within grace period
            Lib-->>UI: entitlement allows premium
            UI-->>User: apply theme (grace)
        else Grace expired / no entitlement
            Lib-->>UI: cannot switch
            UI-->>User: show "Unable to verify license" / deny
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(themes): add basic variation support #569 — modifies theme variation and selection UI (ThemeToggle, ThemeSelector, MobileFooterNav); closely related to gating/variation changes in this PR.

Suggested labels

web, themes

Poem

🐰

I nibbled keys and stored the news,
Seven days' grace for theme-time views,
When servers nap, my cache holds true,
Debounced and brisk—your colors stay new,
A rabbit's hop keeps themes for you!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main changes: preventing theme reset on license errors and improving performance through reduced transitions and optimized polling.
Linked Issues check	✅ Passed	The PR implements all coding requirements from #837: grace period (7 days) for license validation, localStorage caching, increased polling from 30s to 1h, premium theme switching restrictions on errors, warning banner, removed heavy CSS transitions, non-blocking font loading, and coalesced PWA updates.
Out of Scope Changes check	✅ Passed	All changes align with the linked issue #837. Minor addition of PWA meta tag in index.html is tangential but relates to PWA theme improvements mentioned in the PR objectives, falling within acceptable scope.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/premium-theme-validation

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2270ad4 and e4a468d.

📒 Files selected for processing (2)

• web/src/components/themes/ThemeSelector.tsx
• web/src/components/ui/ThemeToggle.tsx

🧰 Additional context used

🧬 Code graph analysis (1)

web/src/components/ui/ThemeToggle.tsx (1)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (63-85)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Run tests

🔇 Additional comments (7)

web/src/components/themes/ThemeSelector.tsx (3)

144-155: LGTM! Grace-period license checking integrated correctly.

The integration of canSwitchToPremiumTheme properly handles the three states (loading, error, success) and checks the 7-day grace period from cached entitlement during API failures. The isThemeLicensed simplification correctly gates premium themes based on the combined license state.

---

160-171: LGTM! Error messaging properly differentiates verification failures.

The early-return pattern correctly prioritizes license verification errors (isError) over generic missing-license messages, providing users with actionable context when the API is unavailable versus when they lack a valid license.

---

225-232: LGTM! Warning banner condition is correct.

The condition isError && !canSwitchPremium correctly identifies the scenario where license verification has failed AND the user is outside the grace period (or has no cached entitlement). This ensures the warning only appears when premium switching is actually blocked due to verification issues.

web/src/components/ui/ThemeToggle.tsx (4)

39-44: Previous stale modeKey concern is now resolved.

The modeKey is now derived from the reactive isDark state (Line 89), which is tracked in the useThemeChange hook (Lines 39, 44, 58) and updated whenever the THEME_CHANGE_EVENT fires. This ensures modeKey remains synchronized with the current theme mode, addressing the previous review's concern about stale values when dark mode changes while the dropdown is open.

Also applies to: 58-62, 89-89

---

82-117: LGTM! Preview color caching is well-implemented.

The previewColorsCache is created once with useMemo and provides stable identity for the getPreviewColors callback. The cache key ${modeKey}:${theme.id} correctly handles mode switches, and the callback's dependencies [modeKey, previewColorsCache] ensure it's recreated only when the mode changes. The color resolution logic properly handles var(--variation-color) by falling back to the first variation.

---

134-150: LGTM! License-aware theme selection with appropriate error messaging.

Both handleThemeSelect and handleVariationSelect correctly gate premium themes using canSwitchPremium and provide distinct error messages based on whether isError is true (license verification failure) or false (missing license). Closing the dropdown before applying the theme change (Line 145) improves perceived performance by providing immediate feedback.

Also applies to: 154-172

---

232-241: LGTM! Variation preview reveals on hover/focus.

The onMouseEnter and onFocus handlers correctly set activeThemeId only when a theme has variations, enabling on-demand display of variation color pills. This improves UX by revealing variations contextually without cluttering the dropdown.

---

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.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

web/src/components/ui/ThemeToggle.tsx (1)

188-202: Consider aligning isLocked with canSwitchPremium for visual consistency.

The isLocked check uses !hasPremiumAccess directly, but the handlers use canSwitchPremium. This could cause visual inconsistency:

• During grace period with API error: theme appears locked (opacity-60) but selection would succeed
• During loading with valid cached entitlement: same inconsistency

While not a functional bug (handlers correctly gate access), aligning the visual state improves UX.

Suggested fix

           .map((theme) => {
             const isPremium = isThemePremium(theme.id);
-            const isLocked = isPremium && !hasPremiumAccess;
+            const isLocked = isPremium && !canSwitchPremium;
             const colors = getThemeColors(theme);

web/src/components/themes/ThemeValidator.tsx (2)

34-34: Consider standardizing console output.

The code uses both console.warn (line 34) and console.log (lines 44, 52, 88, 106) inconsistently. For production code, consider:

• Standardizing on console.warn for error-related conditions
• Using a logging library for better control over log levels
• Or removing debug logs entirely for production builds

Also applies to: 44-44, 52-52, 88-88, 106-106

---

56-56: Minor optimization: reduce localStorage reads.

The code reads localStorage.getItem("color-theme") multiple times across different code paths. While not a significant performance concern, you could read it once at the start of each effect and reuse the value for cleaner code.

Example refactor for the first effect

   useEffect(() => {
     // Don't do anything while loading - let the stored theme persist
     if (isLoading) return
+
+    const storedThemeId = localStorage.getItem("color-theme")

     // If there's an error fetching license data
     if (isError) {
       // ... rest of error handling uses storedThemeId variable
     }

     // ... success case also uses storedThemeId variable
   }, [data, isLoading, isError])

Also applies to: 86-86, 103-103

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0684d75 and c96e236.

📒 Files selected for processing (9)

• web/index.html
• web/src/components/layout/MobileFooterNav.tsx
• web/src/components/themes/ThemeSelector.tsx
• web/src/components/themes/ThemeValidator.tsx
• web/src/components/ui/ThemeToggle.tsx
• web/src/hooks/useLicense.ts
• web/src/lib/license-entitlement.ts
• web/src/utils/pwaNativeTheme.ts
• web/src/utils/theme.ts

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: s0up4200
Repo: autobrr/qui PR: 617
File: internal/services/license/license_service.go:23-24
Timestamp: 2025-11-20T17:10:01.827Z
Learning: In the autobrr/qui repository, the `UpdateLicenseStatus` method in `internal/database/license_repo.go` updates both the `status` field and the `last_validated` timestamp to `time.Now()` whenever it's called, ensuring the offline grace period window advances correctly on successful license validations.

🧬 Code graph analysis (6)

web/src/components/layout/MobileFooterNav.tsx (4)

web/src/hooks/useLicense.ts (1)

• useHasPremiumAccess (107-115)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (93-118)

web/src/utils/theme.ts (2)

• setTheme (252-300)
• themes (449-449)

web/src/config/themes.ts (3)

• themes (22-22)
• themes (38-38)
• isThemePremium (33-36)

web/src/hooks/useLicense.ts (2)

web/src/lib/api.ts (1)

• api (1716-1716)

web/src/lib/license-entitlement.ts (2)

• setLicenseEntitlement (52-62)
• clearLicenseEntitlement (67-73)

web/src/utils/theme.ts (1)

web/src/utils/fontLoader.ts (1)

• loadThemeFonts (56-80)

web/src/components/themes/ThemeValidator.tsx (3)

web/src/lib/license-entitlement.ts (2)

• getLicenseEntitlement (28-47)
• isWithinGracePeriod (78-83)

web/src/utils/theme.ts (3)

• themes (449-449)
• setValidatedThemes (207-210)
• setTheme (252-300)

web/src/config/themes.ts (5)

• themes (22-22)
• themes (38-38)
• isThemePremium (33-36)
• getThemeById (25-27)
• getDefaultTheme (29-31)

web/src/components/ui/ThemeToggle.tsx (3)

web/src/hooks/useLicense.ts (1)

• useHasPremiumAccess (107-115)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (93-118)

web/src/config/themes.ts (1)

• isThemePremium (33-36)

web/src/components/themes/ThemeSelector.tsx (3)

web/src/hooks/useLicense.ts (1)

• useHasPremiumAccess (107-115)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (93-118)

web/src/config/themes.ts (1)

• isThemePremium (33-36)

🔇 Additional comments (24)

web/index.html (1)

9-9: LGTM!

This meta tag properly enables full-screen PWA mode on Android/Chrome, complementing the existing apple-mobile-web-app-capable for iOS.

web/src/utils/theme.ts (2)

17-26: LGTM!

Reducing the transition to only the root background color is a solid performance optimization. Child elements receiving CSS variable changes instantly avoids expensive repaints on many DOM elements.

---

77-82: LGTM!

Non-blocking font loading improves perceived theme-switch performance. Users may briefly see fallback fonts (FOUT), but this is an acceptable trade-off for faster theme application.

web/src/utils/pwaNativeTheme.ts (1)

128-161: LGTM!

Good use of requestAnimationFrame to coalesce rapid theme mutations into a single update per frame. This prevents redundant meta tag updates when theme application triggers multiple attribute changes in quick succession.

web/src/hooks/useLicense.ts (3)

13-27: LGTM!

The changes correctly:

1. Persist entitlement on successful response for grace-period support
2. Reduce polling from 30s to 1 hour (reducing CPU usage)
3. Add retry support for transient failures
4. Enable refetch on reconnect for better resilience

---

76-82: LGTM!

Clearing the cached entitlement on license deletion is essential to prevent the grace period from incorrectly allowing premium access after intentional license removal.

---

107-115: LGTM!

Exposing isError enables UI components to distinguish between "no license" and "verification failed", allowing for appropriate user messaging.

web/src/components/layout/MobileFooterNav.tsx (3)

99-100: LGTM!

Good use of the centralized canSwitchToPremiumTheme utility for consistent entitlement-aware premium access checks across UI components.

---

138-154: LGTM!

The conditional error messaging provides clear user feedback: "Unable to verify license" for API failures vs. "premium theme" prompt for missing licenses. Dependency array correctly includes canSwitchPremium and isError.

---

156-174: LGTM!

Variation selection correctly mirrors the theme selection logic, ensuring consistent entitlement checks and error messaging.

web/src/lib/license-entitlement.ts (5)

15-23: LGTM!

Good design choices:

• Versioned storage key (v1) enables future schema migrations
• Grace period matches backend's offlineGracePeriod (7 days) as noted in the learnings

---

28-47: LGTM!

Shape validation ensures corrupted or tampered localStorage data doesn't cause runtime errors. Silent error handling is appropriate here.

---

52-73: LGTM!

Both functions handle localStorage errors gracefully, which is important for private browsing modes where localStorage may be unavailable.

---

78-83: LGTM!

Simple and correct grace period check using Unix timestamp comparison.

---

93-140: LGTM!

The two-tier approach is well-designed:

• canSwitchToPremiumTheme: More restrictive, gates new premium theme selections
• shouldKeepCurrentPremiumTheme: More lenient, prevents jarring theme resets during transient failures

Both correctly leverage the grace period for resilience during API outages.

web/src/components/themes/ThemeSelector.tsx (4)

142-156: LGTM!

The canSwitchPremium computation and isThemeLicensed helper centralize the entitlement-aware access check, consistent with other components.

---

161-193: LGTM!

Error messaging is consistent across all theme-related components, providing clear feedback for both license verification failures and missing licenses.

---

230-238: LGTM!

The warning banner appropriately displays only when license verification fails and the user is outside the grace period. The yellow styling correctly indicates a temporary issue rather than a permanent error.

---

195-216: LGTM!

Loading state provides appropriate visual feedback while license data is being fetched.

web/src/components/ui/ThemeToggle.tsx (2)

60-70: LGTM!

Consistent setup with other components for entitlement-aware premium theme switching.

---

81-124: LGTM!

Theme and variation selection handlers correctly use canSwitchPremium with context-aware error messaging. Dependency arrays are properly updated.

web/src/components/themes/ThemeValidator.tsx (3)

33-68: Excellent grace period implementation.

The grace period logic correctly handles transient license validation failures:

• Preserves premium theme access within the 7-day grace window
• Restricts to free themes outside the grace period without forcing an immediate reset
• Keeps the current premium theme accessible even outside grace to avoid jarring UX changes
• Defers actual theme resets until a confirmed no-access response

This implementation properly addresses issue #837 by preventing theme resets on transient API errors while maintaining security.

---

70-90: Correct handling of confirmed license state.

The downgrade logic appropriately distinguishes between transient errors and confirmed loss of entitlement. The explicit check data?.hasPremiumAccess === false (rather than a truthy check) correctly ensures theme resets only occur when premium access is definitively denied, not during error states.

---

94-129: Periodic validation logic is sound.

The validation interval correctly implements the 1-hour polling frequency (reduced from 30 seconds per PR objectives). The logic appropriately:

• Only validates when confirmed data is available (skips during error states)
• Checks for premium theme usage with confirmed no-access
• Handles cross-tab storage changes
• Properly cleans up intervals and event listeners

The dependency array [data, isLoading, isError] is correct as the closures need to capture the latest state.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (2)

web/src/components/themes/ThemeValidator.tsx (2)

23-23: Explicit return type added per PR objectives.

The function signature now includes the explicit : null return type as requested in the PR objectives and previous review comments.

---

78-111: Periodic validation properly guards against error states.

The validation logic correctly:

• Skips validation during loading and error states (lines 79-83)
• Uses the named constant THEME_VALIDATION_INTERVAL_MS (line 94), addressing a previous review comment
• Includes isError in the dependency array (line 111) to properly react to error state changes

This ensures periodic validation only runs when license state is confirmed, reducing CPU usage during transient failures as intended.

🧹 Nitpick comments (1)

web/src/components/themes/ThemeSelector.tsx (1)

160-191: Consider extracting duplicate toast logic.

The error handling in handleThemeSelect and handleVariationSelect is identical. A small helper would reduce duplication:

Proposed refactor

+  const showLicenseError = () => {
+    if (isError) {
+      toast.error("Unable to verify license", {
+        description: "License check failed. Premium theme switching is temporarily unavailable.",
+      })
+    } else {
+      toast.error("This theme requires a premium license", {
+        description: "Please purchase a license to access premium themes",
+      })
+    }
+  }
+
   const handleThemeSelect = (themeId: string) => {
     if (isThemeLicensed(themeId)) {
       setTheme(themeId)
     } else {
-      if (isError) {
-        toast.error("Unable to verify license", {
-          description: "License check failed. Premium theme switching is temporarily unavailable.",
-        })
-      } else {
-        toast.error("This theme requires a premium license", {
-          description: "Please purchase a license to access premium themes",
-        })
-      }
+      showLicenseError()
     }
   }

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c96e236 and 2270ad4.

📒 Files selected for processing (7)

• web/src/components/themes/ThemeSelector.tsx
• web/src/components/themes/ThemeValidator.tsx
• web/src/components/ui/ThemeToggle.tsx
• web/src/hooks/useLicense.ts
• web/src/lib/license-entitlement.ts
• web/src/utils/pwaNativeTheme.ts
• web/src/utils/theme.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• web/src/utils/pwaNativeTheme.ts

🧰 Additional context used

🧬 Code graph analysis (4)

web/src/components/ui/ThemeToggle.tsx (2)

web/src/hooks/useLicense.ts (1)

• useHasPremiumAccess (110-118)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (63-85)

web/src/hooks/useLicense.ts (1)

web/src/lib/license-entitlement.ts (2)

• setLicenseEntitlement (35-45)
• clearLicenseEntitlement (47-53)

web/src/utils/theme.ts (1)

web/src/utils/fontLoader.ts (1)

• loadThemeFonts (56-80)

web/src/components/themes/ThemeSelector.tsx (3)

web/src/hooks/useLicense.ts (1)

• useHasPremiumAccess (110-118)

web/src/lib/license-entitlement.ts (1)

• canSwitchToPremiumTheme (63-85)

web/src/config/themes.ts (1)

• isThemePremium (33-36)

🔇 Additional comments (19)

web/src/hooks/useLicense.ts (3)

14-31: LGTM! Entitlement persistence and polling changes align with PR objectives.

The changes correctly:

• Store entitlement via useEffect when query data is available
• Reduce polling from 30s to 1 hour (staleTime and refetchInterval)
• Add retry support with retry: 2
• Enable reconnection-triggered refetch

---

80-85: LGTM! Correctly clears cached entitlement on license deletion.

The entitlement is cleared before invalidating queries, ensuring the UI reflects the correct state immediately.

---

110-118: LGTM! Exposing isError enables proper error handling in UI components.

This allows components like ThemeSelector and ThemeToggle to differentiate between "no license" and "verification failed" states.

web/src/utils/theme.ts (3)

17-19: Performance improvements look good.

Transitions are effectively disabled with ENABLE_THEME_TRANSITIONS = false, and the duration is reduced to 150ms for when transitions are re-enabled. This aligns with the PR goal of making theme switching feel instant.

---

81-83: Non-blocking font loading improves theme switch performance.

Fonts load in the background while the theme applies immediately. Users may briefly see fallback fonts, but the overall UX is faster.

---

21-27: Lightweight transition CSS is a good simplification.

Only transitioning the root background color while child elements inherit instantly via CSS variables is an effective performance optimization.

web/src/components/themes/ThemeSelector.tsx (2)

144-154: LGTM! Entitlement-aware gating is correctly implemented.

The canSwitchToPremiumTheme function centralizes the grace-period logic, and isThemeLicensed properly gates premium theme access.

---

228-235: LGTM! Warning banner provides good user feedback.

The banner correctly appears only when license verification fails AND the grace period has expired, clearly communicating why premium themes are temporarily unavailable.

web/src/components/ui/ThemeToggle.tsx (4)

71-78: LGTM! Theme sorting is correctly memoized.

Since themes is a static import, the empty dependency array is appropriate.

---

80-115: Color caching implementation is sound.

The cache correctly keys by both mode and theme ID. The cache will work correctly once the modeKey staleness issue is addressed.

---

130-170: LGTM! Error handling aligns with ThemeSelector.

The premium gating and error-aware toast messages are consistent across components. The dropdown close timing differs between theme and variation selection, which seems intentional given variation involves two sequential operations.

---

219-244: LGTM! Hover/focus handlers improve discoverability of theme variations.

The onFocus handler ensures keyboard users can also discover variations, which is good for accessibility.

web/src/lib/license-entitlement.ts (4)

1-14: LGTM! Well-structured entitlement persistence module.

• Versioned storage key (v1) enables future migrations
• 7-day grace period matches backend offlineGracePeriod
• Clear interface definition

---

16-33: LGTM! Defensive parsing with proper validation.

The runtime validation of parsed JSON structure prevents type assertion issues from propagating.

---

55-61: LGTM! Grace period check with future timestamp guard.

The check for lastSuccessfulValidationAt > now is good defensive coding that prevents issues from clock manipulation or data corruption.

---

63-85: LGTM! Three-path logic correctly handles all API states.

The function properly:

1. Uses cached entitlement during loading (within grace period)
2. Returns live API result on success
3. Falls back to cached entitlement on error (within grace period)

This aligns with the PR objective to prevent premium theme resets on transient API failures while still respecting confirmed loss of entitlement.

web/src/components/themes/ThemeValidator.tsx (3)

6-12: LGTM! Imports and constant declaration address PR objectives.

The new imports (getThemeById, getLicenseEntitlement, isWithinGracePeriod) support the grace period implementation, and the named constant THEME_VALIDATION_INTERVAL_MS addresses a previous review comment about extracting magic numbers.

---

71-74: Excellent: only resets on confirmed loss of entitlement.

The explicit data?.hasPremiumAccess === false check (line 72) correctly distinguishes between:

• Transient errors (data is undefined) → no reset
• Confirmed loss of access (data.hasPremiumAccess is explicitly false) → reset to default

This precisely addresses the PR objective of preserving themes during API failures while maintaining security on confirmed entitlement loss.

---

33-56: Grace period error handling correctly implements PR objectives with proper null safety.

The error handling path properly addresses issue #837 by:

• Preserving the current theme when within the 7-day grace period (lines 40-44)
• Blocking premium theme switching when outside grace, while keeping the currently applied premium theme (lines 46-55)
• Avoiding forced resets on transient API failures

The isWithinGracePeriod function safely handles null input from getLicenseEntitlement() with an explicit guard clause (if (!entitlement) return false), and its type signature correctly accepts LicenseEntitlement | null.