25-08-2025

Content Discovery Overhaul & Architectural Refinements

This release marks a significant leap in how users discover and personalize their news feeds. We've introduced a suite of powerful filtering tools that offer granular control over content, while foundational architectural changes enhance navigation, stability, and the overall robustness of the application.

🔍 Advanced Content Filtering & Discovery

We focused on giving users more precise tools to find the news that matters to them. This involved not just adding new filters, but rethinking how filtering works to create a more cohesive and efficient experience.

• 🗺️ Geographical Filtering Introduced: Users can now pinpoint news with surgical precision by filtering headlines based on where an event occurred (Event Country) or the headquarters of a news source (Source Headquarter). This was built on a newly refactored, reusable country selection component. #92
• ✨ Unified Source Filtering: The user experience for filtering by source has been streamlined by integrating country selection directly into the main source filter page, eliminating unnecessary navigation steps. #93
• ✅ Corrected Filter Logic: A bug in the headline feed's filtering mechanism was addressed by refining the HeadlineFilter model and ensuring source headquarters are correctly filtered by their ISO codes. #94
• 📌 "Apply My Followed" Shortcut: A new "Apply My Followed" feature has been implemented across country, source, and topic filters, allowing users to instantly apply their saved preferences with a single tap. #95

🗺️ Deeper Personalization & Navigation

This release deepens user personalization by treating countries as first-class entities that can be followed and explored. We also refactored core navigation to be more robust and idiomatic.

• ❤️ Followable Countries: Users can now follow and unfollow specific countries, adding another layer of personalization to their content preferences, managed through dedicated new BLoCs and UI pages. #97
• 🔗 Unified Entity Details: Countries are now integrated into our generic entity details feature, allowing them to be viewed and managed with the same rich detail pages as topics and sources. #98
• 🧭 Robust Navigation Arguments: Navigation to detail pages was refactored to pass simple, serializable identifiers (entityId, contentType) instead of entire objects. This aligns with GoRouter best practices and improves maintainability. #99
• 📍 Centralized Navigation Logic: The EntityDetailsBloc is now created at the routing level, centralizing its management. This change also enabled direct navigation from a headline to its corresponding country detail page. #100

🛠️ Under-the-Hood: A More Robust Foundation

Significant effort went into improving the application's core stability, especially within the demo environment, and ensuring our asynchronous operations are handled safely.

• 🔄 Synchronized User Preferences: The AccountBloc now subscribes to repository updates, ensuring that user content preferences are always synchronized and instantly reflect any changes. #104
• 🛡️ Resilient Ad Loading: The AdLoaderWidget has been fortified with improved lifecycle management to prevent setState calls on disposed widgets and to cancel ad requests when the widget is removed or updated, preventing memory leaks. #105
• 🧪 Stabilized Demo Environment: The demo mode experience is now more reliable. We've fixed the email login flow, introduced a service to pre-emptively initialize user data to prevent read errors, and implemented a specialized in-memory client for advanced country filtering. #101, #102, #103

19-08-2025

Ad System Implementation, App Status Management & Auth Refinements

Summary

This is a significant functional release for the mobile client, introducing a new ad system for monetization, a centralized service for app status management, and key refinements to the authentication flow. The changes focus on architectural stability, lifecycle management, and data consistency.

💰 Ad System Implementation & Lifecycle Management

An ad system was implemented to support monetization. The architecture was designed to be provider-agnostic and to solve lifecycle management issues that cause crashes with native ad SDKs.

• Provider-Agnostic Architecture: The system uses a generic NativeAd model and abstract AdProvider to decouple the app from a specific ad network. The initial implementation uses Google AdMob but can be extended.
• Lifecycle Crash Fixes: Native ad objects are now managed within StatefulWidget lifecycles (AdmobNativeAdWidget) and a central AdCacheService. This solves a bug where disposing ads that were scrolled off-screen would cause the app to crash.
• Performance via Caching: The AdCacheService stores loaded ads to prevent redundant network requests during scrolling, improving UI fluidity. The cache is strategically invalidated on content refreshes to ensure ad relevance.
• Theme & Format Aware Ads: The ad service now accepts AdThemeStyle and HeadlineImageStyle parameters. This allows ads to be requested with theme-aware styling (light/dark mode) and the correct template size (small/medium) to match the surrounding UI content.
• Platform Safety: A NoOpAdProvider is used on unsupported platforms like web, which renders a visual placeholder. This prevents MissingPluginException crashes at startup.

🚦 Centralized App Status Management

The app's startup sequence and handling of global states have been re-architected to improve stability and allow for backend-driven UI control.

• Remote Configuration States: The app can now be remotely configured to display a full-screen, blocking MaintenancePage or UpdateRequiredPage.
• Centralized State Logic: The AppBloc now acts as a single source of truth for the app's status, evaluating the remote configuration on startup and during background fetches. This ensures the app's UI reacts immediately to critical status changes.
• Stable Startup Sequence: A dedicated StatusPage now handles the initial config fetch state. This prevents context-related crashes and localization failures that occurred when this logic was previously in the router. The router's responsibility is now simplified to only handle authentication redirects.

🔐 Authentication Flow Refinements

The authentication module has been updated to improve security and resolve UX and memory issues.

• Request Cooldown: A 60-second cooldown is now enforced on sign-in code requests to prevent abuse. The UI provides a countdown timer.
• Memory Leak Fix: The _cooldownTimer in the AuthenticationBloc is now properly cancelled when the BLoC is closed, fixing a memory leak.
• UI/UX Fixes:
  • The code entry field now uses the pinput widget for a better user experience.
  • A navigation bug was fixed where using context.goNamed was improperly clearing the navigation stack; it now uses context.pushNamed.

🛠️ Other Notable Changes

• Data Sorting Consistency: Implemented explicit sorting across all data repositories. Headlines are now consistently sorted by updatedAt descending, while entities like topics and sources are sorted alphabetically.
• Web Splash Screen: The web splash screen logic was refactored into a dedicated service and its CSS was updated with a new loading spinner.
• GitHub Issue Templates: A new suite of issue templates has been added to the repository to standardize bug reports and feature requests.

23-07-2025

🚀 Project-Wide Renaming & Architectural Standardization

This release marks a significant foundational refactoring of the entire project. We have undertaken a comprehensive renaming initiative to standardize our package structure and align with more conventional naming practices.

The ht_ prefix has been removed from the main project and all internal library packages. This results in a cleaner, more descriptive, and more maintainable codebase for the future, while also standardizing our error handling and updating key dependencies.

✨ Key Changes & Enhancements

Project & Package Renaming

• Project Renamed: The project itself has been renamed from ht_main to flutter_news_app_mobile_client_full_source_code, with corresponding updates to Android application IDs and other configurations.
• Internal Packages Refactored: All internal shared packages (e.g., ht_auth_repository, ht_ui_kit) have been renamed to remove the ht_ prefix (e.g., auth_repository, ui_kit), requiring extensive updates to imports across the entire codebase.

Technical Refinements

• Standardized Error Handling: The custom HtHttpException has been replaced with the more standard HttpException type across all BLoCs and state management files. This improves consistency and aligns our error handling with common Dart practices.
• Dependency Upgrades: Several third-party packages, including go_router and very_good_analysis, have been upgraded to their latest versions.

21-07-2025

✨ Search & Usability Enhancements

This release focuses on improving the user experience of the search page and headline displays. We've introduced a more intuitive 'time ago' date format and enhanced search results to be more interactive. Under the hood, we've also made several refinements to improve application stability and maintainability.

✨ User Experience Enhancements

• User-Friendly Date Formatting: All timestamps across headline tiles are now displayed in a more intuitive 'time ago' format (e.g., "5 minutes ago," "yesterday"). This makes it much easier to gauge how recent an article is at a glance.
• Enhanced Search Results: The search page is now more powerful. When you search for topics, they will appear as dedicated, interactive items in the results list, allowing you to tap them to navigate directly to that topic feed.

🔧 Stability & Technical Refinements

• Robust Configuration Handling: We've improved how remote configuration is fetched, using constants instead of hardcoded strings to make the process more reliable and less prone to errors.
• Dependency Updates & Alignment: The application has been updated to use the latest version of our internal ht-http-client library, ensuring full compatibility and stability with our backend services.
• Code Quality: Minor code cleanup was performed, including the removal of unused imports and variables, contributing to better overall code hygiene.

20-07-2025

🚀 Major Architectural Refactor & UI Standardization

This release introduces a significant architectural refactor aimed at improving the application's maintainability, scalability, and overall robustness. We have overhauled our core data models to align with recent backend changes and standardized state management across all features.

A key part of this effort was extracting all shared UI code into a new, internal ht_ui_kit package, promoting code reuse and creating a more polished, consistent user experience.

✨ Key Architectural & Core Model Updates

• Core Model Refactor: The Category model has been comprehensively replaced by Topic throughout the entire application. Similarly, AppConfig has been renamed to RemoteConfig, and UserRole to AppUserRole for better clarity and consistency with the API.
• Standardized Authentication State: The AuthenticationBloc has been refactored to use a single state class (AuthenticationState) managed by an AuthenticationStatus enum. This simplifies state transitions and improves the predictability of the authentication flow.

🎨 Shared UI Kit & Standardized Error Handling

• Shared UI Code Extraction: Common UI components and utilities (e.g., FailureStateWidget, LoadingStateWidget, app_spacing) have been extracted from this repository into our new internal ht_ui_kit package. This centralizes shared code, promotes reuse, and ensures a consistent look and feel.
• Improved Error Display: To support the new UI kit, error handling has been standardized. All BLoCs now report errors using rich HtHttpException objects instead of simple strings. The shared FailureStateWidget from the UI kit now uses these exceptions to display consistent, informative, and localized error messages to the user.

🔧 Feature & Technical Refinements

• Enhanced Feed & Search: The feed and search features have been refactored to align with the new Topic model and standardized state management patterns. Data fetching is now more flexible, using a new filter and pagination approach.
• Structured Logging: The logging package has been integrated across key BLoCs, providing better debugging capabilities and visibility into the application's behavior.

25-06-2025

🐛 Critical Fix for Demo Mode

This release addresses a critical bug affecting the user experience in our demo mode. Previously, users testing the app as a guest would lose their settings and content preferences upon signing up or logging in.

We have now implemented a dedicated data migration service that ensures all user data is seamlessly transferred from the guest profile to the authenticated account. This provides a much smoother and more reliable experience for new users trying out the application.

✨ Fixes & Improvements

• Demo Mode Data Sync: Fixed a critical bug where UserAppSettings and UserContentPreferences were lost when an anonymous user authenticated. All settings are now correctly migrated.
• Race Condition Mitigation: Resolved a potential race condition during the data migration by implementing a retry mechanism and handling ConflictException more gracefully. This ensures data integrity even during concurrent operations.

🔧 Refinements & Code Quality

• New Data Migration Service: Implemented a new client-side DemoDataMigrationService to handle the data transfer logic specifically for the demo environment, improving the robustness of the feature.
• Codebase Cleanup: Performed extensive code hygiene improvements across the app, including removing redundant comments, streamlining BLoC emits, and organizing imports for better readability and maintenance.
• Linter Adjustments: Updated the analysis_options.yaml file to ignore specific, non-critical linter warnings, streamlining the development workflow.

20-06-2025

This is the first official public release of ht_main, the Flutter mobile application for the Headlines Toolkit!

This initial version establishes the core foundation of the application, providing a feature-complete, source-available news app and starter kit.

✨ Highlights in this Release

• 📰 Production-Ready News Feed: A beautiful and performant infinite-scrolling feed.
• 🔐 Full Authentication Suite: Includes passwordless email, anonymous sign-in, and seamless account linking.
• 🧑‍🎨 Deep User Personalization: Features for saving headlines, following topics, and customizing content preferences.
• 🎨 Advanced Theming Engine: Full control over light/dark modes, accent colors, and typography.
• 📱 Adaptive UI: A responsive layout that works great on both phones and tablets out of the box.
• 🏗️ Clean Architecture: A solid foundation built with BLoC and GoRouter for easy extension.
• 🌍 Localization Ready: Ships with English and Arabic support included.

---

This is a foundational release, and we're excited for you to explore it! For full setup instructions and technical details, please see the project README.md.