feat(site): overhaul release discovery, downloads, and accessibility experience

[harsha-vardhan-burra]

feat(site): overhaul release discovery, downloads, and accessibility experience

Overview

This PR delivers a comprehensive refinement of the Passcodes website's release discovery and download experience.

The work transforms the release flow from a collection of independent release surfaces into a cohesive end-to-end journey:

Homepage
→ Current Production Release
→ Project Updates
→ Release Details
→ Downloads
→ Documentation

The implementation was completed incrementally across four focused commits, followed by a holistic UX, accessibility, and regression QA pass.

The existing release synchronization architecture and PassAlgo integration remain intact and authoritative throughout this work.

---

What This PR Changes

1. Project Updates & Release Experience

Introduces a structured Project Updates experience centered around the current production release.

Current Production Release

• Added a dedicated current-release hero to /changelog/.
• Clearly surfaces the active production release (v3.2.1).
• Presents release highlights and relevant build information.
• Provides direct access to:
  • APK download
  • Installation / Setup Guide
  • Release details
  • GitHub release

This makes the current production build immediately identifiable instead of requiring users to scan a chronological release list.

Recent Updates & Architectural Milestones

• Added a curated Recent Updates section.
• Added a dedicated Major Architectural Milestones section.
• Distinguished routine releases from significant architectural transitions such as:
  • v3.0 cross-platform migration
  • v2.0 database architecture milestone
  • v1.0 initial stable baseline

Release Discovery & Search

Added structured release selectors and filtering for:

• Features
• Improvements
• Fixes
• Security
• Architecture

And release states:

• Stable
• Beta
• Alpha
• Milestones
• Deprecated
• Yanked

Search supports release versions, keywords, summaries, highlights, technical release metadata, and release states.

---

2. Release Discovery & Cross-Page Navigation

Connected the major release-related surfaces so users are no longer left at dead ends.

Homepage → Release Details

• The homepage release announcement now points to the canonical release detail route.
• The displayed release version is resolved consistently from the verified production release data.

Downloads → Project Updates

• Added a Release notes & milestones path from Downloads to Project Updates.
• Individual download cards can link directly to their corresponding release entry.

Release Details → Downloads / Documentation

Release detail pages now include:

• Breadcrumb navigation
• Previous / Next release navigation
• Download action
• Installation / Setup Guide
• Project Updates navigation
• GitHub release link
• A dedicated Next Steps section

This creates a continuous path from understanding a release to actually installing it.

---

3. Download Experience & Build Selection

Refined the Downloads experience around the real user question:

"What should I download for my phone?"

Architecture-Aware Downloads

• Added hardware-aware package recommendations.
• Modern Android devices are guided toward the appropriate ARM64 build.
• Universal is available as a fallback.
• Alternative ABI packages remain accessible for users who need them.
• Archive entries support expandable architecture variants.

The goal is to expose the necessary technical information without forcing every user to understand Android ABI terminology before downloading.

Release Channel Clarity

Downloads now explicitly distinguish:

• Stable
• Beta
• Alpha
• Deprecated
• Yanked

Each state has contextual guidance explaining what it means.

Deprecated Releases

Legacy releases are clearly identified as deprecated and separated from the normal production download path.

Yanked Releases

Withdrawn releases now:

• Display explicit withdrawal notices.
• Use appropriate warning semantics.
• No longer present normal prominent download actions.

This prevents withdrawn packages from being mistaken for valid production downloads.

Setup Guidance

Added a clear path from Downloads to the official Installation & Setup Guide without duplicating documentation content.

Empty States

Improved filtered/search empty states with:

• Clear explanation
• Reset filters action
• Better recovery flow

---

4. Holistic UX, Accessibility & Regression QA

After implementing the above features, the complete release journey was audited across desktop and mobile.

The QA pass identified and corrected several concrete consistency and accessibility issues.

Release Consistency

• Synchronized the homepage announcement version across its badge, announcement text, and technical stats.
• Standardized release-state badge casing across the site.
• Standardized Architecture Milestone terminology.
• Applied consistent download-count formatting using the existing PassAlgo formatter.

Responsive Fixes

• Corrected mobile alignment of Previous / Next release navigation.
• Added mobile overflow regression coverage for:
  • Homepage
  • Project Updates
  • Downloads
  • Release Details

Accessibility Improvements

• Added aria-pressed state to release-channel filter controls.
• Added semantic breadcrumb structure using:
  • nav
  • ol
  • aria-current="page"
  • hidden visual separators
• Added descriptive accessible names to repeated/generic release and download links.
• Improved screen-reader distinction between repeated actions such as release details and architecture downloads.

Test Coverage

Expanded Playwright coverage for:

• Current production release
• Project Updates
• Release detail navigation
• Release-state filtering
• Deprecated releases
• Yanked releases
• Architecture/build selection
• Variant expansion
• Search and empty-state reset
• Setup Guide navigation
• Mobile overflow
• Release filtering behavior

---

Architecture & Data Integrity

The existing release architecture remains unchanged and continues to be the single source of truth:

GitHub Releases API + Passcodes-Docs
                ↓
      scripts/sync-releases.mjs
                ↓
    normalized-releases.json
                ↓
 Homepage / Changelog / Downloads / Release Details

No parallel release-data system was introduced.

The existing @passcodes/passalgo integration remains authoritative for:

• Number formatting
• Date rendering
• File-size calculations

The existing Next.js static export configuration is also preserved:

output: "export"
trailingSlash: true

The build continues to generate the complete static route set.

---

Files / Areas Primarily Affected

Release & Changelog

• Hero.tsx
• CurrentReleaseHero.tsx
• RecentUpdatesGrid.tsx
• MilestonesSection.tsx
• page.tsx
• src/app/changelog/[slug]/page.tsx
• changelog.ts

Downloads

• DownloadsContent.tsx
• DownloadCard.tsx
• ReleaseList.tsx
• ArchDownload.tsx

Testing

• changelog.spec.ts
• downloads.spec.ts
• mobile.spec.ts
• changelog-search.spec.ts
• release-filters.spec.ts

---

Validation

All quality checks pass.

Check	Result
TypeScript	✅ 0 errors
ESLint	✅ 0 warnings / errors
Production Build	✅ 23/23 static pages generated
Playwright	✅ 67 passed, 5 skipped
Git Diff Check	✅ Clean
Mobile Overflow Coverage	✅ Homepage, Changelog, Downloads, Release Details
Architecture Variant Coverage	✅ Passing
Release-State Coverage	✅ Stable / Beta / Alpha / Deprecated / Yanked

The production build also successfully executed the release synchronization step and regenerated the normalized release data.

[JeelDobariya38]

LGTM!!! Merge It.