Architectural Overhaul for a Faster, More Stable Experience

This release introduces a transformative set of foundational improvements, focusing on application stability, performance, and a more robust user experience. We have completely overhauled the app's startup and authentication lifecycle to eliminate race conditions and have implemented a powerful in-memory caching layer that makes content discovery dramatically faster. Alongside these architectural enhancements, we are excited to launch the new "Discover" feature, a dedicated space for users to explore news sources.

🚀 Foundational Stability & Performance

This release focuses on deep, under-the-hood enhancements that create a significantly more reliable and responsive application. The entire startup sequence has been re-architected, and a new caching layer ensures content is delivered to the user with minimal delay.

• ⚡️ The application's core startup and authentication lifecycle has been completely rebuilt to be more robust, sequential, and free of race conditions, leading to a more predictable and stable user experience. #182
• 💾 A comprehensive, session-based in-memory caching layer for the news feed has been introduced, providing near-instantaneous content switching between saved filters feeds and reducing network requests. #189
• 📢 The ad management system has been refined to improve lifecycle handling, ensuring that ad resources are managed more efficiently and reliably across the application. #190, #192

🧭 A New Way to Discover Content

To enhance content exploration, a new top-level "Discover" feature has been introduced, providing users with powerful tools to find and follow new sources.

• 🗺️ Users can now explore the new 'Discover' section to browse news sources by category, filter them by country of origin, and follow or unfollow them directly within a dedicated interface. #187

✨ Polished Visuals & User Experience

Alongside major architectural changes, this release includes significant UI and UX refinements that create a more modern and intuitive interface.

• 🖼️ Generic source icons have been replaced with dynamic network logos, providing a richer and more visually engaging experience across all content discovery and feed surfaces. #192
• ➡️ Subtle fade effects have been added to the edges of horizontally scrolling lists, improving the discoverability of content and adding a layer of visual polish. #192

Advanced Content Discovery & Core UI Modernization

This release marks a significant evolution in user experience, introducing a powerful and deeply integrated system for saving and managing content filters. Alongside this flagship feature, the application's core navigation has been modernized with a revamped search and account interface, and a new "Discover" section lays the groundwork for future content exploration.

🔍 Advanced Content Filtering & Discovery

The feed filtering system has been completely overhauled to give users granular control over their content. This includes the ability to save complex filter combinations, reorder them for a personalized workflow, and quickly access content from followed sources and topics.

• 💾 Users can now create, save, and manage custom feed filters, which are instantly accessible from a new horizontal quick-access bar on the main feed. #161
• ❤️ A new 'Followed' filter provides one-tap access to personalized content, complemented by a redesigned source selection interface for a more intuitive experience. #167
• ↔️ A dedicated management page now allows users to reorder their saved filters using a simple drag-and-drop interface, placing their most-used shortcuts at their fingertips. #169
• 🐛 The filtering system is now more reliable, with bug fixes for active filter identification and a new auto-scrolling feature that keeps the selected filter in view. #172

✨ Modernized Navigation & User Interface

Core navigational components have been redesigned to create a more streamlined and integrated user experience, making search more accessible and account management more intuitive.

• 🔎 Search functionality is now seamlessly integrated into the main feed's app bar, while the account section has been redesigned as a modern, full-screen modal for improved clarity. #177
• 🧭 A new 'Discover' section has been added to the bottom navigation, replacing the former 'Search' and 'Account' tabs to create a central hub for content exploration. #177

🛠️ Demo Experience & Stability

Improvements were made to the application's demo mode and data handling logic to ensure a more robust and representative experience for first-time users and those transitioning between account types.

• 🧪 New anonymous users in the demo environment now begin with a richer set of pre-populated data, including saved filters, to provide a more functional and complete initial experience. #164
• 🔩 Data migration logic has been refined to correctly handle the transition from a guest to a standard user in demo mode, preventing data conflicts and ensuring a seamless upgrade path. #173

Content Limitation Enforcement & Auth Flow Refactor

This release introduces a major new feature for enforcing content limits and provides a significant architectural refactoring of the authentication and account linking flows. It also includes several key bug fixes and dependency updates to improve stability and the web loading experience.

🚀 Content Limitation Enforcement

A new system has been implemented to gracefully handle and enforce limits on user actions, such as following content or bookmarking articles. This was necessary to provide a clear and consistent user experience when users reach plan-based limits.

• 📥 Introduced a ContentLimitationService to centralize the logic for checking user content limits based on their role and remote configuration. [#145]
• 🎨 Added a ContentLimitationBottomSheet to provide a user-friendly UI that informs users when they hit a limit and offers tailored actions like signing in or upgrading. [#145]
• ✅ Integrated content limit checks into key user actions, including following topics, sources, and countries, as well as bookmarking headlines. [#145, #159]
• 🐛 Fixed a UI bug where the ContentLimitationBottomSheet content could overflow on smaller screens by wrapping it in a SingleChildScrollView. [#149]

🔐 Authentication & Account Linking Refactor

The authentication and account linking flows have been separated and re-architected to improve clarity, maintainability, and the overall user experience.

• 🔗 Separated the core sign-in/sign-up flow from the account linking process by introducing a dedicated AccountLinkingPage for anonymous users. [#142]
• ⚙️ The GoRouter configuration was comprehensively refactored to support the new, distinct authentication paths and to better manage state. [#142]
• 🐛 Fixed a critical bug in the authentication flow where goNamed was incorrectly used, preventing users from navigating back. This was corrected by using pushNamed. [#144]
• 👍 After successful verification, navigation was changed from pushNamed to goNamed to ensure users are properly redirected and cannot navigate back to previous auth steps. [#148]

🛠️ App Health & Web Experience

Several updates were made to improve project stability, maintainability, and the loading experience on the web platform.

• ⬆️ Updated several key dependencies, including bloc, go_router, and very_good_analysis, to their latest versions. [#135]
• 🕸️ Fixed a critical bug where the web splash screen would remain visible indefinitely, blocking the app. This was resolved by updating the Flutter bootstrap script and refining the splash removal timing. [#136]
• ✨ Refactored the web splash screen management to use the flutter_native_splash package, simplifying the codebase by removing custom logic. [#137]
• 📝 Implemented a centralized logging system using the logging package and a new GoRouterObserver, replacing ad-hoc print statements for better debuggability. [#143]

✨ Version Enforcement

• Introduced a new feature to enforce mandatory app updates based on remote configuration, directing users to a dedicated UpdateRequiredPage. [#134]
• Integrated package_info_plus and pub_semver for accurate version retrieval and comparison. [#134]

Role-Based Ad Logic, Content Filtering & UI Refinements

This release focuses on refining the application's data presentation logic, improving the user interface and theming capabilities, and enhancing project documentation and stability.

📢 Ad Logic & Content Filtering

The logic for displaying ads and fetching content has been updated to be more precise, ensuring users only see relevant information based on their role and the content's status.

• Implemented role-based ad visibility, where the decision to show an ad is now driven by remote configuration based on the user's role (e.g., premium, standard). [#127]
• Applied a consistent ContentStatus.active filter across all data-fetching operations for sources, topics, and headlines to ensure inactive content is not retrieved or displayed. [#128]

🎨 UI & Theming Refinements

Several updates were made to the UI to improve visual consistency, theming flexibility, and responsiveness.

• The application's theme scheme (FlexScheme) is now dynamically controlled by the application state, allowing for more flexible, state-driven theme management. [#129]
• The entity details page UI has been updated with responsive padding to support RTL layouts and standardized sizing for visual consistency. [#129]
• Added new localization keys for "Suggested Topics" and "Suggested Sources" to enable dynamic and localized titles for content collection widgets. [#129]

🛠️ Project Health & Documentation

General maintenance was performed to improve build reproducibility and developer experience.

• The main README.md file has been completely restructured with collapsible sections and significantly expanded feature descriptions for monetization, remote control, and architecture. [#123]
• All git-based dependencies in pubspec.yaml have been pinned to specific commit hashes to ensure reproducible builds across all environments. [#127]

Centralized App State, Robust Ad Lifecycle & Startup Refinements

This release introduces a significant architectural refactoring of the application's core state management, a complete overhaul of the ad lifecycle to prevent common crashes and memory leaks, and a more robust and predictable startup sequence.

🚦 Centralized App State & Initialization

The application's state management and initialization logic have been fundamentally re-architected to improve data flow, simplify the codebase, and handle startup errors more gracefully.

• Single Source of Truth: The AppBloc is now the single source of truth for all application-wide state, including user authentication, app settings, and content preferences. This centralizes data and eliminates the need for the separate AccountBloc. [#121]
• Robust Startup Sequence: Remote configuration is now fetched earlier in the bootstrap process, and a new AppLifeCycleStatus enum provides more granular states. This prevents race conditions related to evaluating maintenance mode or required updates. [#120]
• Critical Error Handling: A dedicated CriticalErrorPage has been added to provide a clear UI and retry mechanism for unrecoverable startup failures, such as failing to fetch initial remote config. [#121]
• Persistent User Settings: All user display settings (theme, font, etc.) are now immediately persisted, ensuring preferences are saved and reloaded consistently across sessions. [#120]
• Centralized Filter Logic: A new HeadlinesFilterBloc has been introduced to manage all headline filtering logic (topics, sources, countries), simplifying filter management. [#121]
• Demo Mode Stability: Improved error handling in the AppBloc to gracefully handle NotFoundException for user data in demo mode, preventing the app from entering a critical error state. [#122]

💰 Ad Lifecycle & Management Overhaul

The entire ad system has been refactored to address critical lifecycle issues, prevent memory leaks, and provide more granular control over ad display.

• Centralized Ad Disposal: A disposeAd method has been introduced in the AdProvider and AdService. The InlineAdCacheService is now the central authority for managing the ad lifecycle, preventing memory leaks by ensuring ad resources are properly released. [#118]
• Fixed 'AdWidget' Errors: Resolved the common 'AdWidget' is already in the Widget tree error by adding a ValueKey to the admob.AdWidget and improving the didUpdateWidget logic in AdmobInlineAdWidget to handle new ad instances correctly. [#119]
• Stable Ad Loader Widgets: All setState calls within FeedAdLoaderWidget are now guarded by if (mounted) checks to prevent errors when a widget is disposed of during an async operation. [#119]
• Refactored Interstitial Ads: Replaced the AdNavigatorObserver with a new InterstitialAdManager to centralize logic. UI components now explicitly call onPotentialAdTrigger, providing more precise control and allowing for ad pre-loading. [#115]
• Synchronized Ad Navigation: Navigation now explicitly awaits the completion of an interstitial ad before proceeding to the next screen, ensuring a more predictable user flow. [#116]

🛠️ Other Notable Changes

• Realistic Demo Ads: Demo and local interstitial ads now feature a 5-second countdown timer before the close button is enabled, more accurately simulating a real ad experience. [#116]
• Improved Ad Placement Logic: The FeedDecoratorService now correctly includes CallToActionItem and ContentCollectionItem when calculating content density, leading to more intelligent inline ad placement. [#119]
• Code Reusability: Extracted common headline tap logic and metadata display into new reusable utility classes and widgets (HeadlineTapHandler, HeadlineMetadataRow), reducing code duplication. [#116]

📢 Ad System Overhaul & Robust Initialization

This release introduces a major architectural overhaul of the application's advertising system, focusing on flexibility, multi-format support, and improved lifecycle management. It also includes a significant refactoring of the app's startup sequence to ensure service dependencies are initialized in a more robust and predictable order.

📢 Advertising System Overhaul

The entire ad infrastructure has been refactored to support a more flexible, multi-provider, and multi-format system, aligning with a new remote configuration structure from the backend.

• Unified Ad Service: The AdService now supports multiple ad platforms (e.g., AdMob, Local) and ad formats (inline, banner, interstitial) through a unified interface and abstract ad models. [#109]
• Granular Ad Caching: A new InlineAdCacheService was introduced to specifically cache native and banner ads, improving scrolling performance. Interstitial ads are now managed on-demand via a new AdNavigatorObserver and are excluded from caching. [#109]
• In-Article Ad Integration: The article details page now supports dynamic injection of in-article banner ads at configurable positions based on remote settings. [#109, #112]
• Robust Interstitial Logic: The logic for displaying interstitial ads has been refined to increment the page transition counter more selectively and to use unawaited to prevent blocking UI navigation during the ad display process. [#112, #114]
• Enhanced Ad Logging: Added consistent log prefixes and more detailed error reporting across all ad-related services to improve debuggability. [#114]

🛠️ Demo Environment & Platform Compatibility

To streamline development and testing, the ad system has been improved to gracefully handle different environments and platforms.

• New Demo Ad Provider: A dedicated DemoAdProvider was introduced to simulate ad loading and display visual placeholders for all ad types when the app runs in demo mode, bypassing real ad network calls. [#111, #112]
• Conditional Initialization: The app's bootstrap process now dynamically initializes ad providers based on the environment, using the DemoAdProvider in demo mode and real providers (AdMob, Local) otherwise. [#112]
• Web Platform Safety: Implemented conditional imports for ad providers to ensure AdMob integration defaults to a demo provider on the web, preventing MissingPluginException crashes. [#113]

🚀 Robust Service Initialization

The application's startup sequence has been refactored to establish a more stable and predictable dependency chain, preventing potential race conditions and runtime issues.

• Logical Initialization Order: Core services like key-value storage and the HTTP client are now guaranteed to be initialized before services that depend on them. [#110]
• Circular Dependency Fix: Resolved a circular dependency between the HttpClient and AuthRepository by having the client read auth tokens directly from storage. [#110]
• Code Cleanup: Removed numerous redundant comments and unnecessary non-null assertions across the codebase to improve readability and rely on compiler null safety. [#110]

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

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.

🚀 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.

✨ 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.