fix(extension): Chrome extension helper redirection

[shiv248]

Issue:

Hello!

issues are disabled from creation, so I'll briefly go over the issue here.

Sometimes when a user navigates from deepwiki -> composite and uses the provided extension to Go to Source we get a stale or incorrect response from GitHub due to the nature of the extension being hardcoded to redirect specifically to main, where master or another default branch exists or an override exists which should be respected.

for example if we ask deepwiki - "what is livekit? and what examples do they have for webrtc on esp32?"

And we select ivekit/livekit/README.md it takes us to the correct livekit_composite blob but using the extension redirect if we want to view the original codebase, due to livekit/livekit's default branch being master the README.md comes up as a 404, which is incorrect.

This issue gets highlighted again when livekit_composite/repo.conf specifics direct overridden repos during the livekit repos pull, referenced within livekit_composite/sync_livekit_repos.py, but getting ignored by the redirection extension.

---

Fix:

This PR fixes this issue and adds QOL changes to the extension, which could be expanded upon further. I tried to keep the changes additive rather than removing existing functionality, cleanly.

some features:

• Use repo-default-branches.json to store branch mappings for all repositories.
  • A Python script upstream already generates this file on every repo pull
  • Provides accurate branch info without unnecessary extension runtime github API calls
  • Can be maintained and updated independently of extension code
• Pre-compute branch mappings in repo-default-branches.json as hot cache, but check GitHub only when a 404 occurs
  • Static cache = fast, works offline-like, rarely changes, changes that happen get added automatically via python driver file
  • Dynamic fallback = handles stale cache without extra requests during normal use
  • Only does web request to github cost on 404 (rare case), API key not necessary for end user.
  • Updates local users cache if precompute is wrong and 404 is incorrect, github returned correct default branch.
• Load the JSON once via a background service worker (composite-redirect-bg.js) and share it across all tabs.
  • JSON is fetched only once per browser session
  • All tabs share the same in-memory cache (no duplication)
  • Faster than fetching on every page load
  • Simpler than chrome.storage.local versioning/hashing
  • Cache loads from bundled repo-default-branches.json on service worker startup.
• The background worker owns the branch cache and all URL conversion logic
  • The branch cache needs to be mutable and shared. When a 404 occurs and we fetch the correct branch from GitHub's API, we update the cache. That update needs to be visible to all future redirects, whether they come from the popup or from another 404 recovery.
  • If each context (popup, content script) held its own cache copy, a cache update in one place wouldn't propagate to the others. By centralizing it in the background worker, we get:
    • One cache load on extension startup
    • Cache updates from 404 recovery benefit all subsequent requests
    • No stale copies floating around
  • Background Worker as the Single Source of Truth for Branch Cache
    • Manifest V3 allows ES modules in service workers but not content scripts. This provides a single source of truth and better security.
• Append ?utm_source=livekit_extension to all redirects.
  • Lets the 404 detector distinguish extension-generated 404s from organic ones. This prevents infinite loops and ensures we only attempt cache recovery for redirects we created.
  • Able to distinguish “our redirect failed” vs. “user found a real 404”
  • quick and dirty for now, makes it visible to user and not behind the scenes within extension.
• Repos can be marked with isOverride: true in the JSON cache
  • Some repositories don't follow standard conventions (e.g., esp-webrtc-solution uses branch livekit-demo).
  • Marking these as overrides prevents unnecessary API calls for known edge cases.
  • We trust the JSON and don't second-guess it on 404 for overrides.
• Validate URLs in both the popup and background worker before redirecting.
  • Defense-in-depth. The popup checks that the input is a livekit_composite URL.
  • Before redirecting, it checks that the output is github.com/livekit/ or github.com/livekit-examples/.
  • This prevents the extension from being used to redirect to arbitrary URLs unnecessarily.
• When a redirect results in a 404, check the GitHub API and auto-redirect if the branch has changed. Only triggers for URLs containing ?utm_source=livekit_extension.
  • Logic:
    1. If isOverride -> stop (trust JSON, real 404)
    2. If cached branch == API branch -> stop (real 404)
    3. If cached branch != API branch -> update cache and redirect to correct branch
  • Handles stale cache when upstream branch changes
  • Prevents infinite redirect loops
  • Self-healing: dynamically learns and updates cache
  • 404 detection uses a content script (404-detector.js) scoped to github.com/livekit/* and github.com/livekit-examples/* in the manifest.
  • Dynamic updates from 404 recovery are in-memory only and don't persist across browser/service worker restarts.

Final Architecture

composite-redirect-bg.js (Background Service Worker)

• prefetchCache() – loads JSON once on extension startup
• Handles getBranchCache messages from content scripts
• Handles updateBranchCache messages to update shared cache

composite-redirect.js (Content Script)

• initializeCache() – retrieves cache from background worker
• convertCompositeToSource() – applies correct branch and UTM param
• handle404Redirect() – detects 404s, checks overrides, compares API
• Updates cache via background messages when branch changes are detected

repo-default-branches.json (branch cache)

• Generated by upstream Python script
• Contains branch mappings with optional isOverride flag

Scenarios Covered

Scenario	Behavior
Normal redirect (cache correct)	Instant redirect, no API call
Stale cache (branch changed)	Auto-fix via API, then redirect
Override repo 404	Trust JSON, stop
Real 404 (file doesn’t exist)	Stop after confirming with API
User navigates to 404 naturally	Ignored (no UTM param)
Stale -> fixed -> still 404	Stop (no infinite loop)

fix tested on firefox and chrome/edge.

future recommendations:

• make redirection automatic, eg wikiwand ext.
• fix security issues
• if continuing to develop extension helper, consider bundler as extension becomes more robust
• possibly make a GitHub Actions cron job that will automatically sync every night all LK repos
• consolidate this into one all-inclusive solution managing both frontend, backend, and data corpus + updating, cutting out #ask-ai or deepwiki.

[CLAassistant]

All committers have signed the CLA.