feat: improve PWA version visibility and updates - #42
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (4)
Included review availability: Your plan includes up to 3 reviews per rolling hour; 1 remains after this review. 📝 WalkthroughWalkthroughThe PR adds build-aware PWA lifecycle state, safe service-worker activation, update checks, shared version displays, mobile profile integration, localized profile entries, and focused test coverage. ChangesPWA version updates
Estimated code review effort: 4 (Complex) | ~45 minutes Merge Risk: 🟡 Moderate · up to The PR improves PWA version visibility and safe updates, but merge readiness is still affected by a CI check that may not fail on formatter changes and a timing race that can leave update status incorrect; these issues should be fixed or explicitly accepted before merging. Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Owner
Author
|
@sourcery-ai review |
Reviewer's GuideIntroduces a PWA lifecycle context/provider that tracks running vs deployed builds, coordinates safe service worker updates, and exposes version status to shared UI, while cleaning up profile menu links and adding a typed i18n namespace and documentation for the new PWA versioning behavior. Sequence diagram for PWA version check and safe update activationsequenceDiagram
actor User
participant Window
participant ServiceWorkerRegistration
participant ApiServer as ApiServer_/api/version
participant NavigatorSW as navigator.serviceWorker
participant Worker as sw.js
User->>Window: Open PWA
Window->>ServiceWorkerRegistration: Mount provider
ServiceWorkerRegistration->>NavigatorSW: getRegistration("/")
NavigatorSW-->>ServiceWorkerRegistration: existingRegistration
ServiceWorkerRegistration->>NavigatorSW: register(serviceWorkerUrl)
NavigatorSW-->>ServiceWorkerRegistration: registration
ServiceWorkerRegistration->>ApiServer: fetch("/api/version", {cache:"no-store"})
ApiServer-->>ServiceWorkerRegistration: { version: deployedBuild }
ServiceWorkerRegistration->>NavigatorSW: register("/sw.js?v="+deployedBuild)
NavigatorSW-->>ServiceWorkerRegistration: registration (installing/waiting)
ServiceWorkerRegistration-->>ServiceWorkerRegistration: setUpdateStatus("available" / "ready")
rect rgb(230,230,250)
ServiceWorkerRegistration->>NavigatorSW: getRegistration("/")
NavigatorSW-->>ServiceWorkerRegistration: registration(waiting for appBuild)
ServiceWorkerRegistration-->>NavigatorSW: waiting.postMessage({ type:"ACTIVATE_UPDATE" })
ServiceWorkerRegistration-->>ServiceWorkerRegistration: handoffArmedRef = true
end
ServiceWorkerRegistration->>Worker: postMessage({ type:"ACTIVATE_UPDATE" })
Worker->>Worker: handleActivateUpdate(event)
Worker->>Worker: clients.matchAll({ type:"window", includeUncontrolled:true })
alt single matching client
Worker->>Worker: skipWaiting()
else multiple window clients
Worker-->>ServiceWorkerRegistration: postMessage({ type:"UPDATE_ACTIVATION_BLOCKED" })
end
Worker-->>Window: controllerchange
Window->>ServiceWorkerRegistration: handleControllerChange
ServiceWorkerRegistration-->>Window: window.history.go(0) (once when handoffArmed)
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="apps/web/lib/i18n/client.ts" line_range="33-42" />
<code_context>
});
-export const useTranslation = useTranslationOrg;
+export function useTranslation(): ReturnType<
+ typeof useTranslationOrg<"translation">
+>;
+export function useTranslation(ns: "translation"): ReturnType<
+ typeof useTranslationOrg<"translation">
+>;
+export function useTranslation(ns: "profile_menu"): ReturnType<
+ typeof useTranslationOrg<"profile_menu">
+>;
+export function useTranslation(ns: "translation" | "profile_menu" = "translation") {
+ return useTranslationOrg(ns);
+}
</code_context>
<issue_to_address>
**issue (bug_risk):** The `useTranslation` overload return types use an invalid `typeof useTranslationOrg<...>` construction and are likely to break TypeScript.
The current overloads are invalid because `typeof` can’t be used with a type argument (`typeof useTranslationOrg<"translation">` won’t compile or will infer incorrectly).
You can keep overloads but rely on `ReturnType<typeof useTranslationOrg>` and let the `ns` argument drive the generic:
```ts
export function useTranslation(): ReturnType<typeof useTranslationOrg>;
export function useTranslation(ns: "translation"): ReturnType<typeof useTranslationOrg>;
export function useTranslation(ns: "profile_menu"): ReturnType<typeof useTranslationOrg>;
export function useTranslation(ns: "translation" | "profile_menu" = "translation") {
return useTranslationOrg(ns);
}
```
For per-namespace precision, consider using the `Namespace`/`KeyPrefix` generics from `react-i18next` instead of encoding them via `typeof`.
</issue_to_address>
### Comment 2
<location path="docs/superpowers/plans/2026-08-16-pwa-version-updates.md" line_range="28" />
<code_context>
+
+### Client lifecycle provider
+
+`apps/web/components/pwa/ServiceWorkerRegistration.tsx` remains the service-worker integration point and now also provides shared PWA lifecycle state.
+
+It exports:
</code_context>
<issue_to_address>
**nitpick (typo):** Consider dropping the hyphen in “service-worker” for consistency.
In this doc you use “service worker” elsewhere, so please update this instance to “service worker integration point” for consistency with the rest of the text and common usage.
```suggestion
`apps/web/components/pwa/ServiceWorkerRegistration.tsx` remains the service worker integration point and now also provides shared PWA lifecycle state.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Installed PWAs can keep running an older frontend build without clearly showing which build is actually executing. The fork also versions its service-worker URL as
/sw.js?v=<build>, so an old frontend cannot discover a newly deployed worker URL by callingregistration.update()on its old URL alone.The shared profile menu also still contained upstream Karakeep app/docs/social links instead of Marka-owned surfaces.
Solution
/api/versionwithno-storeon initial load and whenever the document returns to the foreground/sw.js?v=<commit>silently when a newer build existscontrollerchangehandoffComing soonrowsprofile_menunamespace while keeping server translations scoped to the configured default namespaceValidation
Current head
3773b295183f1a9b6dd778bca109ce1fefaa43bcis synced with currentmainand validated by:@karakeep/webVitest suiteFinal synced-head CI run: https://github.com/absolutepraya/karakeep/actions/runs/31957306794
CodeRabbit reviewed the final implementation changes with no actionable comments. The later sync commit only incorporated six disjoint reviewer-policy/docs files from
main; relative to currentmain, this PR still changes only the intended 18 PWA/version files. All existing inline review threads are resolved.Device acceptance
Real installed-PWA acceptance remains to be recorded on:
The automated suite covers the lifecycle contracts, but this PR is not described as fully device-verified until those real-device checks are completed.
Docs
docs/superpowers/specs/2026-08-16-pwa-version-updates-design.mddocs/superpowers/plans/2026-08-16-pwa-version-updates.mddocs/superpowers/specs/2026-07-12-offline-library-pwa-design.mdOut of scope