feat: add freshness and randomness weights to popular ranking

[Jeanclaudeaoun]

Summary

• Adds two new weight keys (freshness and randomness) to the popular feed ranking system
• freshness controls time-decay: the backend should apply a decay factor like 1/(1 + ageHours/halfLife)^gravity so newer posts rank higher
• randomness controls daily shuffle: the backend should apply deterministic daily jitter (e.g. ±20% seeded by hash(postId + todayUTC)) so the same posts don't always appear in the same order

Details

The frontend already supports 8 weight keys (comments, tipsAmountAE, tipsCount, uniqueTippers, trendingBoost, contentQuality, reads, interactionsPerHour) sent as query params to GET /api/posts/popular. This PR adds two more:

Weight	Backend behavior	UI label
freshness	Time decay based on (Date.now - datePosted) — low = weak decay (old posts stay), med = moderate, high = aggressive decay favoring new posts	Freshness
randomness	Deterministic daily jitter using post ID + current date as seed — low = ±10%, med = ±20%, high = ±40% score variation	Daily Shuffle

Both default to med (not sent to backend) like all other weights. Comments are already included as an existing weight key.

Files changed

• src/features/social/components/SortControls.tsx — added freshness and randomness to WeightKey type and label map
• src/api/backend.ts — added new keys to the weights type in listPopularPosts()
• src/locales/en.json — added translation strings
• Tests updated to cover the new weight keys (all 30 tests pass)

Backend requirements

The backend (/api/posts/popular) needs to handle these two new query params and incorporate them into the scoring formula. Suggested approach:

finalScore = baseEngagementScore × timeDecayFactor × dailyRandomFactor

Test plan

• backend.listPopularPosts.test.ts — verifies new weight keys are appended to URL
• SortControls.test.tsx — verifies 10 weight labels render with low/med/high toggles
• Manual: verify Freshness and Daily Shuffle controls appear in the customize panel on both mobile and desktop

🤖 Generated with Claude Code

https://claude.ai/code/session_016Q4cZKvz96N3NZmHk2gPhH

---

Generated by Claude Code

---

Note

Low Risk
Frontend-only query-param and UI changes; correct ranking depends on backend support for the new weights and seed.

Overview
Extends the popular feed ranking controls and API with two new tunable weights—Freshness and Shuffle (randomness)—alongside the existing eight signals, wired through SortControls, listPopularPosts, and English copy.

The client now sends an optional seed query param on GET /api/posts/popular. The hot feed keeps a session shuffleSeed ref, includes it in the React Query key, and passes it on every popular-posts fetch so pagination stays consistent with backend shuffle behavior.

Tests cover the new weight query params and seed append/omit behavior; SortControls tests expect 10 weight rows (labels Freshness / Shuffle).

^{Reviewed by Cursor Bugbot for commit aceb201. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

📸 Screenshots report — updated Tue, 14 Jul 2026 00:44:39 GMT

[netlify]

✅ Deploy Preview for fancy-gelato-7cdad5 ready!

Name	Link
🔨 Latest commit	aceb201
🔍 Latest deploy log	https://app.netlify.com/projects/fancy-gelato-7cdad5/deploys/6a5585d20cbd8a000879c454
😎 Deploy Preview	https://deploy-preview-623--fancy-gelato-7cdad5.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

🔎️ Preview Link for Commit: 892b62a

https://pr-623-superhero.stg.service.aepps.com