Refresh the design of GHS

.design/BACKEND-REFINEMENTS.md

@@ -0,0 +1,166 @@
+# Backend Refinements — Design Overhaul
+
+Hand this to your backend coding agent. Every item is a field/endpoint/storage gap surfaced during design handoff analysis. Frontend ships with fallbacks for unfulfilled items, but full design fidelity requires these.
+
+Origin: `~/Downloads/handoff 4/DESIGN.md` §14 + agent specs (`.design/UX-AUDIT.md`, `UX-ARCHITECTURE.md`, `UI-SPEC.md`).
+
+## Priority legend
+
+- **P0** — Blocks a core primitive from rendering correctly. Frontend uses neutral fallback.
+- **P1** — Enables a richer signal. Frontend renders partial state until backend lands.
+- **P2** — Nice-to-have polish.
+
+---
+
+## R1 — `trendingScore` (P0)
+
+**Field:** `Repository.trendingScore: Float?` (or `Int?` rank position)
+**Where used:** Trending section on Home (DESIGN.md §9.3 / §10.1). Drives the `#1 / #2 / #3` rank chip.
+**Today:** Sample API returned `null`. Frontend currently uses a local affinity-`score` proxy in `HomeRepositoryImpl.kt:571-604`.
+**Need:** Server-side ranking (e.g. release count × stars × freshness × velocity in last 7d). Stable per request; cache TTL ≥ 1h. Position (1, 2, 3…) is preferred over percentage to honor DESIGN.md §11 "no invented percentages."
+
+## R2 — `popularityScore` (P0)
+
+**Field:** `Repository.popularityScore: Int?` (rank position)
+**Where used:** "Most popular" section on Home. Drives the rank numbers (Fraunces italic, opacity 0.55).
+**Today:** Sample returned `null`. Frontend sorts by `stargazersCount` locally.
+**Need:** Server-side all-time rank. Same caching as trending. Independent of time window.
+
+## R3 — Per-app accent color (P1)
+
+**Field:** `Repository.accent: { hex: String, lightTint: String, darkTintAlpha: Float }?`
+**Where used:** Lead card bg tint, FreshnessRing outer, install-panel bloom, Apps row tinted leading icon.
+**Today:** No field. Frontend will resolve in this order (per UX-Architecture §7): backend → topic-derived → language-derived → blue fallback.
+**Backend opportunity:** Run a color-thief / palette extraction on `avatarUrl` once at index time; persist `{ hex, lightTint, darkTintAlpha }`. Saves CPU on every device + stays consistent across devices. **Deferred per D5** — frontend ships topic/language fallback first. Re-evaluate after overhaul lands.
+
+## R4 — Sub-day release recency (P2)
+
+**Field:** `Release.publishedAtUtcSeconds: Long` (in addition to current `publishedAt: Instant`)
+**Where used:** FreshnessRing for releases <24h. Currently rounds to "1 day ago"; design wants "5 hours ago" granularity for the Hot bucket.
+**Today:** `publishedAt: Instant` exists — frontend can derive seconds locally. **No backend change required if backend already returns ISO-8601 with seconds precision.** Confirm.
+
+## R5 — Maintenance state (commit recency) (P1)
+
+**Field:** `Repository.lastCommitAt: Instant?` or `Repository.daysSinceLastCommit: Int?`
+**Where used:** Heartbeat animation period (active 1.4s / recent 2.4s / quiet 4.2s / dormant none — per DESIGN.md §6.1).
+**Today:** Repository has `updatedAt` (last metadata update) but that's not commit recency. GitHub API exposes `pushed_at` — pipe through.
+**Need:** Backend persists + serves `pushed_at` (default branch HEAD timestamp) per repo. Refresh hourly or on release.
+
+## R6 — Mirror health for `SignalBars` (P0)
+
+**Field:** Per-mirror `health: { latencyMs: Int, lossPercent: Float, lastCheckedAt: Instant }`
+**Where used:** Mirror picker — `SignalBars` (4 ascending bars, WiFi-style) shows mirror quality.
+**Today:** GHS pings mirrors client-side (existing `AutoSuggestMirror` logic). Lives on device, not in `MirrorsRepository`.
+**Need (backend):** Optional — backend-aggregated health metrics across users would improve cold-start UX. Not required if client-side latency probe stays.
+
+## R7 — Expected APK signing fingerprint (P0)
+
+**Field:** `Repository.signingFingerprint: { sha256: String, source: "first_install" | "publisher_declared" }?`
+**Where used:** Wax-seal trust card (DESIGN.md §7.8). Cracked-seal red state requires comparing installed APK fingerprint to expected.
+**Today:** No "expected" fingerprint stored anywhere. Cracked-seal state can never fire.
+**Need:**
+- On-device: persist fingerprint of first successful install per `InstalledApp` (Room schema addition). Subsequent installs compare against this.
+- Optional backend: publisher-declared fingerprint (maintainer registers via dashboard) — out of scope for this overhaul unless backend wants it.
+
+## R8 — Translation cache persistence (P2)
+
+**Field:** Backend-side translation cache keyed by `(target_lang, version_tag, repo_id)`.
+**Where used:** Inner Detail screen language toggle. Hot path: user clicks "Translate to es", waits for provider response.
+**Today:** Client-side in-memory cache only (kills on app restart).
+**Need:** Either (a) backend caches translations and serves them via `/v1/translate/cache` so cold-start re-opens are instant, or (b) client persists to Room (already aligned with KSafe stack — frontend can do this).
+**Recommendation:** Client-side persistence to Room is simpler. Skip backend cache unless multi-device sync is desired.
+
+## R9 — `permissionRisk` summary (P1)
+
+**Field:** `Repository.permissionRisk: "low" | "moderate" | "high"?`
+**Where used:** Vital signs grid (Permissions tile) on Detail. `PermDot` color (green/amber/red).
+**Today:** Frontend computes locally from APK Inspect results (Android only). Desktop can't show — needs backend.
+**Need (backend):** When scanning a release's APK assets, classify by protection-level groups (Android docs: normal/signature/dangerous). Cache per `(repoId, releaseTag)`. Required for Desktop parity.
+
+## R10 — `licensePosture` from SPDX (P1)
+
+**Field:** `Repository.licensePosture: "copyleft" | "permissive" | "unknown"`
+**Where used:** `LicensePosture` glyph (Filled © tile vs dashed · tile).
+**Today:** `Repository.license` is a free-text string today. Frontend has hardcoded mapping in tokens.json (`licenses.copyleft`, `licenses.permissive`).
+**Need:** Backend normalizes to SPDX identifier on indexing. Frontend uses the tokens.json map. **No backend change needed if license already SPDX.**
+
+## R11 — `downloads` field (P1)
+
+**Field:** `Repository.totalDownloads: Long` (sum across all release assets)
+**Where used:** `DownloadWeight` primitive (radius is log10(downloads)) + meta line "4.8M dl" on Detail.
+**Today:** Existing Forgejo path aggregates client-side. GitHub doesn't expose easily — current GHS backend likely already proxies.
+**Need:** Confirm `totalDownloads` populated for both GitHub + Forgejo paths.
+
+## R12 — `topics` field (P1)
+
+**Field:** `Repository.topics: List<String>`
+**Where used:** TopicGlyph row (up to 3, mapped via `tokens.json.topicGlyphs.supported` + `topicAliases`).
+**Today:** GitHub API returns topics; confirm backend forwards them. Forgejo `/repos/topics` endpoint exists.
+**Need:** Both branches expose `topics` consistently. If topic count is high, prioritize ones in our supported map.
+
+## R13 — `pushedAt` vs `updatedAt` clarity
+
+**Field naming:** Distinguish "last metadata change" (`updatedAt`) from "last commit" (`pushedAt`).
+**Today:** `Repository.updatedAt` ambiguous in our API.
+**Need:** Rename or split — UX-Audit flagged this as confusing.
+
+## R14 — Backend support for accent override on a per-repo basis (P2)
+
+**Field:** Allow maintainer-published `accent: {hex, lightTint, darkTintAlpha}` overrides.
+**Where:** Some apps have brand colors that don't match topic/language fallback. Maintainer should be able to opt in.
+**Today:** No mechanism.
+**Need:** Out of scope unless backend wants. Frontend's fallback chain (topic → language → blue) is acceptable for v1.
+
+---
+
+## Endpoint additions needed
+
+| Endpoint | Purpose | Priority |
+|----------|---------|----------|
+| `GET /v1/repo/{owner}/{repo}/trending-rank` | Returns `{ rank: Int, lastComputedAt: Instant }` if repo in top-100 trending. Else 404. | P0 |
+| `GET /v1/repo/{owner}/{repo}/popularity-rank` | Same shape, all-time. | P0 |
+| `GET /v1/repo/{owner}/{repo}/permissions-summary` | Returns `{ posture: low|moderate|high, dangerous: List<String>, sensitive: List<String> }` for latest release. | P1 |
+| `GET /v1/translate/cache?lang=&version=&repo=` | Returns cached translation or 204. Skip if going Room-only. | P2 |
+
+---
+
+## Data model summary
+
+Backend `Repository` payload after refinements should have these new/clarified fields:
+
+```jsonc
+{
+  "id": 123,
+  "owner": "...",
+  "name": "...",
+  // ... existing fields ...
+
+  // NEW or clarified
+  "trendingScore": 1,          // rank position in trending (nullable)
+  "popularityScore": 47,       // rank position all-time (nullable)
+  "pushedAt": "2026-05-20T...",// last commit (DISTINCT from updatedAt)
+  "totalDownloads": 4843201,
+  "topics": ["self-hosted", "photos"],
+  "licensePosture": "copyleft",     // server-normalized from SPDX
+  "permissionRisk": "moderate",     // optional pre-computed summary
+  "accent": null                    // deferred — null until D5 reversed
+}
+```
+
+---
+
+## Frontend fallback behavior (what ships without backend changes)
+
+Per UI-SPEC.md §5 Data Honesty Audit Hooks:
+
+- `trendingScore` null → drop rank chip; sort by local affinity
+- `popularityScore` null → sort by stars; drop rank number
+- `accent` null → topic → language → blue fallback
+- `pushedAt` null → use `updatedAt` (with caveat in Heartbeat label)
+- `mirrorHealth` null → client-side ping
+- `signingFingerprint` not stored locally → Wax-seal stays in "Unsigned" open state forever
+- `permissionRisk` null → derive on Android via APK Inspect; show "—" on Desktop
+- `licensePosture` SPDX missing → "unknown" → dashed neutral tile
+- `topics` missing → no TopicGlyph row
+
+Nothing fabricated. Missing primitives just don't render.

.design/DECISIONS.md

@@ -0,0 +1,127 @@
+# Design Overhaul Decisions
+
+Locked decisions before Phase 0. Source: maintainer answers during kickoff session (2026-05-21).
+
+## D1 — Bottom nav 5 → 4
+
+Drop **Tweaks** tab from bottom nav. Reachable via Profile → Settings (already wired).
+Keep Home / Search / Apps / Favourites.
+Override: handoff's 3-tab + Search-FAB rejected as too disruptive to muscle memory.
+
+## D2 — Noto fonts
+
+Bundle **Latin-only** Fraunces, Inter Tight, JetBrains Mono with the app.
+Non-Latin scripts (CJK / Devanagari / Arabic / Hebrew / Thai etc.) fall back to system fonts.
+Modern Android / macOS / Windows ship Noto-like coverage; Linux may show tofu (acceptable risk).
+Total bundled font weight target: ≤ 4 MB across all three families.
+
+## D3 — AppTheme migration map
+
+Legacy `AppTheme` enum → new `Palette`:
+- `OCEAN` → `NORD`
+- `SLATE` → `NORD`
+- `PURPLE` → `PLUM`
+- `FOREST` → `FOREST`
+- `AMBER` → `CREAM`
+
+One-time migration on first launch after upgrade. Surface a non-blocking banner ("Themes refreshed — try the new palettes in Tweaks") via a new one-shot flag in `TweaksRepository`.
+
+## D4 — Wonky-squircle scope
+
+Full DESIGN.md coverage: hero CTAs, lead cards, search input, bottom sheets, confirm dialogs, toasts, device-code box, and any "wonky" call-out in the handoff. Implement as custom `WonkySquircleShape : Shape` using `Path.arcTo` with elliptical bounding rects. No fallback to `RoundedCornerShape`; the asymmetric character is brand-defining.
+
+## D5 — Sponsor cut
+
+Cut `SponsorScreen` entirely. Remove:
+- Route `GithubStoreGraph.SponsorScreen`
+- Profile sponsor row (`feature/profile/.../Options.kt:114`)
+- Nav wiring in `AppNavigation.kt`
+- Any deep links / strings
+
+Aligns with MIGRATION.md "no donations in UI."
+
+## D6 — Desktop two-pane Library
+
+Build during **Phase 4**. Desktop `feature/apps/` adopts list (380dp) + detail (660dp) two-pane per DESIGN.md §8.3. Android remains single-pane → full-screen detail.
+Existing single-pane code path retained behind the same composable signature; platform branch picks layout.
+
+## D7 — AMOLED mode
+
+`ThemeMode` enum = `LIGHT` / `DARK` / `AMOLED` / `SYSTEM`. AMOLED is a Dark sub-mode (resolves to Dark when `SYSTEM = dark`). All 4 palettes ship an AMOLED variant — pure-black `bg` (#000) + dimmed `surface` (lift one notch up). Adds ~30% token surface but contained to `Tokens.kt`.
+
+## D8 — Visual reference
+
+Open `desktop-app.html` / `mobile-app.html` / `design-system.html` **per phase** as side-by-side reference. Not opened upfront en-masse.
+
+---
+
+## Carry-over from agent specs (no decision needed — accepted as written)
+
+- Tokens delivered as hand-written `Tokens.kt`, not Gradle codegen (UX-Architect §1).
+- Single `core/presentation/.../vocabulary/` module hosts all primitives (UX-Architect §8).
+- Per-app accent at UI mapper layer, not domain model (UX-Architect §7).
+- `GhsTheme` composable wraps `MaterialExpressiveTheme` + 6 composition locals (UX-Architect §2).
+- Build order: Phase 0 → 8 per UX-Architecture sequencing.
+- Vocabulary uses `ImageVector.Builder` + `Canvas`; Material Symbols painters where applicable (UX-Architect §9).
+
+## D9 — Coverage policy
+
+Design handoff covers only some screens (Home, Library, Detail incl. Inner About/What's-new, Search, APK Inspect, overlay surfaces, Tweaks fragments). Many screens are uncovered. Policy: **plan each uncovered screen before implementing**, extrapolating from DESIGN.md primitives + patterns + tokens. Ask clarification questions before building.
+
+## D10 — Motion scope (rich)
+
+Beyond DESIGN.md §6.2 baseline (Heartbeat + 120ms tap + palette/mode crossfade):
+- Shared-element transitions (Compose `SharedTransitionLayout`) on avatar → Detail hero
+- Spring physics on press / release (`spring(dampingRatio = MediumBouncy)`)
+- List item enter/exit (slide 200ms)
+- Parallax on Detail hero scroll
+- Skeleton loaders during async fetches
+
+Quick, never blocking user. Spring stiffness defaults: high (300+) so transitions feel snappy.
+
+## D11 — Backend refinements doc
+
+`.design/BACKEND-REFINEMENTS.md` drafted upfront. Hand to backend coding agent in parallel while frontend builds. Frontend ships with fallbacks for any field not yet populated.
+
+## D12 — PR cadence
+
+**One mega-PR** at the end of overhaul. Commits per feature / milestone (atomic). Memory rule (commit msgs ≤10 words) applies. Each commit compiles + runs.
+
+## D13 — Build order
+
+User-directed: **Root + Navigation first**, then **core module fully**, then **feature-by-feature**. Translated to 17 phases — see `MEMORY.md` `project_design_overhaul` and the task list.
+
+## D15 — SponsorScreen full delete
+
+Delete `feature/profile/.../SponsorScreen.kt` composable, its route in `GithubStoreGraph`, nav wire in `AppNavigation`, sponsor row in `feature/profile/.../Options.kt`, and all related strings across 13 locales. No flag, no shim.
+
+## D16 — Apps tab renamed "Library"
+
+Label change only. Route name `AppsScreen` stays (no breaking change for deep links). BottomNav + Drawer label → "Library". String resource updated across 13 locales.
+
+## D17 — Onboarding (3 steps)
+
+New first-launch flow:
+1. **Palette pick** — 4 Cookie swatches (Nord/Cream/Forest/Plum) + System/Light/Dark mode default
+2. **Sign in (optional)** — entry point to web-OAuth or device-flow or skip
+3. **Permissions (Android)** — notifications + install-from-unknown-sources prompts (skip-able)
+
+One-shot. Persisted via `TweaksRepository.onboardingComplete: Boolean`. Skipped on subsequent launches. Lives in `composeApp/` as app-level orchestration (no new feature module — too small).
+
+## D18 — Shared elements: Android only
+
+Use `SharedTransitionLayout` + `sharedElement` modifier (`@OptIn(ExperimentalSharedTransitionApi::class)`) on Android only. Desktop uses standard slide/fade nav transitions via Compose Navigation's `enterTransition` / `exitTransition`. Platform branch via `expect/actual` or runtime platform check.
+
+## D14 — Architecture skills
+
+Source of truth for ViewModel/State/Action/Event/Root/Screen structure, navigation, DI, error handling, testing: `~/.claude/skills/android/*`. Applied to KMP/CMP common code (most patterns platform-agnostic).
+
+---
+
+## Deferred / explicitly out of scope for this overhaul
+
+- Color-thief / server-side accent derivation from avatar (UX-Architect Q6) — use topic + language fallbacks only.
+- Translate-the-app (Crowdin pipeline) (UI-Designer §8).
+- Material You dynamic color override (themes.md §Disallowed).
+- New 5th palette (themes.md §Disallowed).
+- Fake trending percentages / "Featured" curation / invented data (DESIGN.md §11).