admanagekit-mcp-server 1.1.1 → 1.2.1

package/content/README.md

@@ -5,7 +5,11 @@
 
 AdManageKit is a comprehensive Android library designed to simplify the integration and management of Google AdMob ads, Google Play Billing, and User Messaging Platform (UMP) consent.
 
-**Latest Version `4.4.0`** is a minor release focused on the billing module. Subscription offers can now be **purchased individually** — `subscribe(activity, offer)` buys exactly the plan the user tapped, where previously the library always resolved the token itself and could charge for whichever offer Play listed last. It also adds offer lookup by id/base plan/tag, cross-cadence price normalization (`BillingPeriod`, `getSavingsPercent`, `getFormattedPricePerMonth`), trial-eligibility checks, Play Billing 9 one-time product offers (discounts, rentals, pre-orders, limited quantity), client-side **account hold** detection, Play payment-recovery messaging, and product-details diagnostics. Purely additive, with one behavior change: an on-hold subscription now reports `ON_HOLD` and is no longer `isSubscriptionActive()`. See [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md).
+**Latest Version `4.4.2`** is a bug-fix release. No API changed, but several fixes are user-visible and two affect revenue: rewarded ads could **crash the app** (every show-path callback, including `onRewardEarned`, was delivered on a background thread), a **completed purchase could fail to disable ads** until the next launch, **blank gaps** were left where banner/native slots should have collapsed for premium users and after failed loads (in both XML and Compose), and app open ads could appear over screens excluded via `disableAppOpenAdsTemporarily()`. Also fixes a `BannerAdView` leak that kept requesting ads after detach. Two deliberate behavior changes: an account-hold subscription no longer disables ads, and premium users no longer reserve ad space in Compose. See [Release Notes v4.4.2](docs/release-notes/RELEASE_NOTES_v4.4.2.md).
+
+**Version `4.4.1`** is a patch release that updates the Google Mobile Ads Next-Gen SDK to **1.3.0** (from 1.2.1) and repairs three documentation-delivery channels that had silently gone stale: the API docs build had failed on every release since the Dokka 2.x upgrade, leaving [the published KDoc](https://i2hammad.github.io/AdManageKit/) without any 4.x types; MCP server npm publishing had been broken since January 2026; and the MCP tool schemas hardcoded which versions and classes existed, so they rejected `4.4.0` as an unknown version. No AdManageKit API changed. See [Release Notes v4.4.1](docs/release-notes/RELEASE_NOTES_v4.4.1.md).
+
+**Version `4.4.0`** is a minor release focused on the billing module. Subscription offers can now be **purchased individually** — `subscribe(activity, offer)` buys exactly the plan the user tapped, where previously the library always resolved the token itself and could charge for whichever offer Play listed last. It also adds offer lookup by id/base plan/tag, cross-cadence price normalization (`BillingPeriod`, `getSavingsPercent`, `getFormattedPricePerMonth`), trial-eligibility checks, Play Billing 9 one-time product offers (discounts, rentals, pre-orders, limited quantity), client-side **account hold** detection, Play payment-recovery messaging, and product-details diagnostics. Purely additive, with one behavior change: an on-hold subscription now reports `ON_HOLD` and is no longer `isSubscriptionActive()`. See [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md).
 
 **Version `4.3.5`** is a patch release that makes `appOpenAdFreshnessThreshold` (default 4 hours) actually enforced on every app open show path. Previously only `ON_DEMAND` consulted it — `HYBRID`, `ONLY_CACHE`, and the multi-provider waterfall checked only whether an ad object existed and could show a day-old cached ad. Stale ads are now discarded and replaced instead of shown. It also settles the `appOpenAdTimeout` default at **10 seconds** (the property said 4s while `resetToDefaults()` said 10s — 4s was too short for the fetch-with-dialog paths). No API changes. See [Release Notes v4.3.5](docs/release-notes/RELEASE_NOTES_v4.3.5.md).
 
@@ -25,7 +29,7 @@ Since **4.2.0** the library runs on the Google Mobile Ads **Next-Gen SDK** (`ads
 
 ## Next-Gen GMA SDK
 
-As of v4.2.0, AdManageKit runs on Google's **Next-Gen Google Mobile Ads SDK** (`com.google.android.libraries.ads.mobile.sdk`, stable `1.2.1`) instead of the legacy `com.google.android.gms:play-services-ads`. This isn't a branch or an opt-in — it's the only version of AdManageKit going forward.
+As of v4.2.0, AdManageKit runs on Google's **Next-Gen Google Mobile Ads SDK** (`com.google.android.libraries.ads.mobile.sdk`, stable `1.3.0` as of 4.4.1) instead of the legacy `com.google.android.gms:play-services-ads`. This isn't a branch or an opt-in — it's the only version of AdManageKit going forward.
 
 ### Why the move
 
@@ -122,7 +126,7 @@ See [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md) and the [
 `BannerAdView` and `BannerAdCompose` now support every standard AdMob banner size via the new `BannerAdSize` enum — `ADAPTIVE` (default, unchanged behavior), `BANNER` (320x50), `LARGE_BANNER` (320x100), `MEDIUM_RECTANGLE` (300x250), `FULL_BANNER` (468x60), `LEADERBOARD` (728x90). Select programmatically (`loadBanner(activity, adUnitId, BannerAdSize.MEDIUM_RECTANGLE)`), in XML (`app:bannerAdSize="medium_rectangle"`), or in Compose (`adSize = BannerAdSize.MEDIUM_RECTANGLE`). The size carries through retries, auto-refresh, and the multi-provider waterfall. See the [Banner Ad Guide](docs/BANNER_AD_IMPROVEMENTS.md).
 
 ### Custom Native Ad Templates
-If none of the 37 built-in `NativeTemplateView` presets fit your design, supply your own layout: `setCustomTemplate(layoutResId, shimmerResId, sizeHint)` programmatically, `app:customAdLayout`/`app:customAdShimmerLayout` in XML, or `customLayoutResId` on `NativeTemplateCompose`. The layout's root must be a Next-Gen SDK `NativeAdView` reusing the standard asset ids. See the [NativeTemplateView guide](docs/NATIVE_TEMPLATE_VIEW.md#custom-templates).
+If none of the 38 built-in `NativeTemplateView` presets fit your design, supply your own layout: `setCustomTemplate(layoutResId, shimmerResId, sizeHint)` programmatically, `app:customAdLayout`/`app:customAdShimmerLayout` in XML, or `customLayoutResId` on `NativeTemplateCompose`. The layout's root must be a Next-Gen SDK `NativeAdView` reusing the standard asset ids. See the [NativeTemplateView guide](docs/NATIVE_TEMPLATE_VIEW.md#custom-templates).
 
 ### Redesigned Banner Shimmer + Night Mode
 The banner loading placeholder now adapts to the requested size (a 300x250 request shows a proper media-block placeholder, not a lone 50dp row), reserves the exact ad size on every path including waterfalls (no layout jump), centers to match the loaded ad, and follows the system dark theme instead of rendering a hardcoded white card.
@@ -189,15 +193,15 @@ dependencyResolutionManagement {
 **Step 2:** Add dependencies to your app's `build.gradle`:
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.0'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.0'
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
 
 // For Jetpack Compose support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
 
 // For Yandex Ads multi-provider support
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2'
 ```
 
 **Step 3:** Ensure your app's `compileSdk` is **37 or higher** (required transitively as of 4.2.0).
@@ -207,7 +211,7 @@ implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.0'
 ## Features
 
 ### NativeTemplateView (v2.6.0+)
-- **27 Template Styles**: card_modern, material3, app_store, social_feed, gradient_card, pill_banner, medium_horizontal, flexible, icon_left, top_icon_media, spotlight, and more
+- **38 Template Styles**: card_modern, material3, app_store, social_feed, gradient_card, pill_banner, medium_horizontal, flexible, icon_left, top_icon_media, spotlight, plus the video_* and flat_* families
 - **XML & Programmatic**: Set templates via `app:adTemplate` or `setTemplate()`
 - **Material 3 Theming**: Automatic dark/light mode support
 - **AdChoices Control**: Configure placement position (v2.9.0+)
@@ -771,6 +775,8 @@ Register it **before** `initBilling`. Products land in `unfetched` when the id i
 - [Multi-Provider Waterfall](docs/MULTI_PROVIDER_WATERFALL.md)
 - [Yandex Integration](docs/YANDEX_INTEGRATION.md)
 - [Billing Integration Guide](docs/APP_PURCHASE_GUIDE.md)
+- [Release Notes v4.4.2](docs/release-notes/RELEASE_NOTES_v4.4.2.md)
+- [Release Notes v4.4.1](docs/release-notes/RELEASE_NOTES_v4.4.1.md)
 - [Release Notes v4.4.0](docs/release-notes/RELEASE_NOTES_v4.4.0.md)
 - [Release Notes v4.3.5](docs/release-notes/RELEASE_NOTES_v4.3.5.md)
 - [Release Notes v4.3.4](docs/release-notes/RELEASE_NOTES_v4.3.4.md)

package/content/docs/AD_LOADING_STRATEGIES.md

@@ -1,16 +1,19 @@
 # Ad Loading Strategies Guide
 
-**New in v2.6.0** - AdManageKit supports three different ad loading strategies to fit different use cases in your app.
+**New in v2.6.0** - AdManageKit supports four different ad loading strategies to fit different use cases in your app.
 
 ## Strategy Availability
 
 | Strategy | Interstitial | App Open | Native |
 |----------|-------------|----------|--------|
 | ON_DEMAND | ✅ | ✅ | ✅ |
-| ONLY_CACHE | ✅ | ✅ | ❌ |
+| ONLY_CACHE | ✅ | ✅ | ✅ |
 | HYBRID | ✅ | ✅ | ✅ |
+| FRESH_WITH_CACHE_FALLBACK | ✅ | ✅ | ✅ |
 
-> **Note:** `ONLY_CACHE` is only available for **Interstitial** and **App Open** ads. Native ads display inline with shimmer loading, so they always need to load content.
+> **Note:** all four strategies work for every ad type. `ONLY_CACHE` behaves differently
+> on native ads: instead of blocking with a dialog, it shows a cached ad if one is ready
+> and otherwise hides the container (see [Native Ads Behavior](#native-ads-behavior)).
 
 ## Strategy Types
 
@@ -82,6 +85,26 @@ User triggers ad → Check cache →
         If timeout: Skip ad → Continue
 ```
 
+### 4. FRESH_WITH_CACHE_FALLBACK
+**Fetch fresh first, fall back to cache if the load fails**
+
+- ✅ Freshest creative whenever the network cooperates
+- ✅ A warm cache covers the failure case
+- ✅ Successful loads are cached for later requests
+- ⚠️ Slower than cache-first when the fetch is slow
+
+**Best for:**
+- RecyclerView / feed placements where each item should try for a fresh ad
+- Placements where creative freshness matters more than instant fill
+
+**How it works:**
+```
+Load ad → Fetch fresh →
+    If loaded: Show ad (and cache it for next time)
+    If failed: Fall back to cached ad if one exists
+        If no cache: Skip / hide container
+```
+
 ---
 
 ## Native Ads Behavior
@@ -118,6 +141,14 @@ Load native ad → Check cache →
         ❌ On failure → Hide container
 ```
 
+**FRESH_WITH_CACHE_FALLBACK:**
+```
+Load native ad → Show shimmer → Fetch fresh ad →
+    ✅ Show ad when loaded → Hide shimmer (ad is cached for next time)
+    ❌ On failure → Show cached ad if one exists
+        ❌ No cache → Hide container
+```
+
 ### Usage Example
 
 ```kotlin

package/content/docs/COMPOSE_INTEGRATION.md

@@ -7,14 +7,14 @@ AdManageKit provides native Jetpack Compose components for all ad types with ful
 ## Installation
 
 ```groovy
-implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.6.0'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
 ```
 
 ## Available Components
 
 | Component | Description |
 |-----------|-------------|
-| `NativeTemplateCompose` | Unified native ad with 28 templates (NEW in 2.6.0) |
+| `NativeTemplateCompose` | Unified native ad with 38 templates, or a fully custom layout (NEW in 2.6.0) |
 | `BannerAdCompose` | Banner ad with lifecycle management |
 | `NativeBannerSmallCompose` | Small native banner (80dp) |
 | `NativeBannerMediumCompose` | Medium native banner (120dp) |
@@ -29,7 +29,7 @@ implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v2.6.0'
 
 ## NativeTemplateCompose (NEW in 2.6.0)
 
-A Compose wrapper for `NativeTemplateView` supporting all 28 template styles.
+A Compose wrapper for `NativeTemplateView` supporting all 38 template styles.
 
 ### Basic Usage
 
@@ -86,6 +86,18 @@ NativeAdTemplate.GRID_ITEM        // Compact grid item
 NativeAdTemplate.TOP_ICON_MEDIA   // Top icon, media center
 NativeAdTemplate.ICON_LEFT        // Left icon column layout
 
+// Flat-design family (10 styles, v3.6.0+)
+NativeAdTemplate.FLAT_INLINE_ROW
+NativeAdTemplate.FLAT_CARD_RATING
+NativeAdTemplate.FLAT_MEDIA_TOP
+NativeAdTemplate.FLAT_TEXT_MINIMAL
+NativeAdTemplate.FLAT_COMPACT_PILL
+NativeAdTemplate.FLAT_CAROUSEL
+NativeAdTemplate.FLAT_BANNER
+NativeAdTemplate.FLAT_FEATURE_LIST
+NativeAdTemplate.FLAT_SPONSORED_STORY
+NativeAdTemplate.FLAT_FOOTER_SLIM
+
 // Video Templates
 NativeAdTemplate.VIDEO_SMALL      // 120x120dp
 NativeAdTemplate.VIDEO_MEDIUM     // 180dp height
@@ -111,13 +123,75 @@ NativeVideoLargeCompose(adUnitId = adUnitId)
 NativeVideoSquareCompose(adUnitId = adUnitId)
 ```
 
+### Custom Templates & Shimmer (v4.3.0+)
+
+If none of the 38 built-in templates fit your design, pass your own layout instead of a `template`:
+
+```kotlin
+NativeTemplateCompose(
+    adUnitId = "ca-app-pub-xxx/yyy",
+    customLayoutResId = R.layout.my_native_ad,
+    customShimmerResId = R.layout.my_native_ad_shimmer,  // strongly recommended, see below
+    customSizeHint = NativeAdSize.MEDIUM
+)
+```
+
+`customLayoutResId` takes precedence over `template` when both are set.
+
+**Layout requirements.** The root must be (or inflate as) a Next-Gen SDK `NativeAdView`, and the asset views must reuse the standard ids so the library can bind them:
+
+`ad_headline`, `ad_body`, `ad_call_to_action`, `ad_app_icon`, `ad_advertiser`, `ad_media`, `ad_stars`, `ad_choices_view`
+
+Any id you omit is simply not populated — but the headline and call-to-action should always be present, and the call-to-action must remain fully visible and tappable or the native ad validator flags a policy violation.
+
+#### The shimmer parameter is optional, but omitting it rarely does what you want
+
+`customShimmerResId` is not required. If you leave it out, the shimmer falls back to **the shimmer belonging to `template`** — which defaults to `CARD_MODERN`:
+
+```kotlin
+// NativeTemplateView.kt
+get() = customShimmerResId ?: currentTemplate.shimmerResId
+```
+
+So a custom layout with no custom shimmer still shows a placeholder — just one shaped like a completely different ad. The usual symptom is a placeholder that visibly jumps to a different size when the real ad arrives.
+
+Two ways to get this right:
+
+```kotlin
+// 1. Supply a shimmer matching your layout (recommended)
+NativeTemplateCompose(
+    adUnitId = adUnitId,
+    customLayoutResId = R.layout.my_native_ad,
+    customShimmerResId = R.layout.my_native_ad_shimmer
+)
+
+// 2. No custom shimmer: set `template` to whichever built-in most resembles your
+//    layout, so the fallback is at least the right shape. Every template carries
+//    its own shimmer (NativeAdTemplate.shimmerResId), and that is what gets used.
+NativeTemplateCompose(
+    adUnitId = adUnitId,
+    template = NativeAdTemplate.MEDIUM_HORIZONTAL,  // example: its shimmer is the fallback
+    customLayoutResId = R.layout.my_native_ad
+)
+```
+
+Passing `0` for `customShimmerResId` is treated the same as omitting it.
+
+**`customSizeHint`** classifies the ad for the cache and gives the Yandex waterfall a fallback size, since a custom layout has no built-in size bucket. Values are `NativeAdSize.SMALL` (icon + title + CTA), `MEDIUM` (adds body), `LARGE` (adds media). Pick whichever matches your layout's content; it does not affect how your layout is measured.
+
+The same feature in XML and code is documented in the [NativeTemplateView guide](NATIVE_TEMPLATE_VIEW.md#custom-templates).
+
 ---
 
 ## Loading Strategies (NEW in 2.6.0)
 
-Native ad Compose components support `loadingStrategy` parameter with `ON_DEMAND` and `HYBRID`:
+Native ad Compose components accept a `loadingStrategy` parameter. All four strategies
+are supported for native ads — `ON_DEMAND`, `ONLY_CACHE`, `HYBRID` (default) and
+`FRESH_WITH_CACHE_FALLBACK`.
 
-> **Note:** `ONLY_CACHE` is only available for Interstitial and App Open ads, not for native ads.
+> **`ONLY_CACHE` on native ads** shows a cached ad if one is ready and otherwise hides
+> the container, rather than blocking the UI with a dialog the way interstitial and app
+> open ads do. See the [Ad Loading Strategies guide](AD_LOADING_STRATEGIES.md) for the full matrix.
 
 ```kotlin
 // ON_DEMAND - Always fetch fresh ad

package/content/docs/NATIVE_AD_PRELOADING.md

@@ -202,7 +202,10 @@ class MainActivity : AppCompatActivity() {
         // Configure ONLY_CACHE strategy
         AdManageKitConfig.apply {
             interstitialLoadingStrategy = AdLoadingStrategy.ONLY_CACHE
-            nativeLoadingStrategy = AdLoadingStrategy.HYBRID // Auto-converted from ONLY_CACHE
+            // Native ads support ONLY_CACHE too - there is no auto-conversion. Set it
+            // explicitly if you want cache-or-nothing; HYBRID here is a deliberate choice
+            // to still fetch when the cache misses.
+            nativeLoadingStrategy = AdLoadingStrategy.HYBRID
             enableSmartPreloading = true
         }
 
@@ -387,7 +390,7 @@ AdManageKitConfig.apply {
 ## Testing
 
 See `LoadingStrategyTestActivity.kt` for comprehensive testing of:
-- All three loading strategies
+- All four loading strategies
 - Preload functionality
 - Cache management
 - Real-time cache status monitoring

package/content/docs/NATIVE_TEMPLATE_VIEW.md

@@ -1,14 +1,14 @@
 # NativeTemplateView Guide
 
-**New in v2.6.0** - A unified native ad component supporting 28 different template styles with Material 3 theming and video support.
+**New in v2.6.0** - A unified native ad component supporting 38 different template styles with Material 3 theming and video support.
 
 ## Overview
 
-`NativeTemplateView` is a single, flexible component that replaces the need for multiple native ad views. It supports 28 different visual templates that can be set via XML attributes or programmatically.
+`NativeTemplateView` is a single, flexible component that replaces the need for multiple native ad views. It supports 38 different visual templates that can be set via XML attributes or programmatically.
 
 ## Features
 
-- **28 Template Styles**: From minimal to icon-left, compact to fullscreen video
+- **38 Template Styles**: From minimal to icon-left, compact to fullscreen video
 - **Material 3 Theming**: Automatic dark/light mode support
 - **Video Support**: All templates support video ads (120dp+ MediaView)
 - **Shimmer Loading**: Beautiful loading animation
@@ -273,6 +273,10 @@ NativeTemplateCompose(
 )
 ```
 
+`customLayoutResId` takes precedence over `template`, mirroring `app:customAdLayout` in XML.
+
+`customShimmerResId` is optional, but if omitted the shimmer falls back to the one belonging to `template` (default `CARD_MODERN`) — so a custom layout shows a placeholder shaped like a different ad. Either supply a matching shimmer or set `template` to the closest built-in. See [Custom Templates & Shimmer](COMPOSE_INTEGRATION.md#custom-templates--shimmer-v430) in the Compose guide for the full explanation.
+
 ## Jetpack Compose Usage
 
 NativeTemplateView is also available as a Compose component via the `ad-manage-kit-compose` module.

package/content/docs/release-notes/RELEASE_NOTES_v4.4.1.md

@@ -0,0 +1,110 @@
+# Release Notes — v4.4.1
+
+**Release Date:** 2026-07-29
+
+## Overview
+
+v4.4.1 is a patch release with one dependency update and a set of documentation-delivery repairs. **No AdManageKit API changed** — no signature was added, removed, or altered.
+
+The dependency update moves the **Google Mobile Ads Next-Gen SDK from 1.2.1 to 1.3.0**. Since the SDK is an `api` dependency, this is what your app resolves transitively.
+
+The rest of the release fixes everything *around* the library — the API documentation site and the MCP documentation server that AI coding assistants read. Three delivery channels had silently gone stale, each in a way that made the library look older than it is:
+
+- **The API docs site** had not regenerated since the Dokka 2.x upgrade. Every release since then, including 4.4.0, failed its documentation workflow, so [the published KDoc](https://i2hammad.github.io/AdManageKit/) never gained any 4.x types.
+- **The MCP server on npm** was stuck at 1.0.0 (published 2026-01-26). Assistants consuming it were being told about a pre-Next-Gen-SDK, pre-Billing-9 library.
+- **The MCP server's own tool schemas** hardcoded which versions and classes existed, so even a fresh publish would have rejected `4.4.0` as an unknown version and reported February 2026 as the latest release.
+
+All modules are bumped to **4.4.1**. The MCP server is published separately as **1.2.0**.
+
+---
+
+## Changed
+
+### Google Mobile Ads Next-Gen SDK 1.2.1 → 1.3.0
+
+`gradle/libs.versions.toml` moves `adsMobileSdk` to **1.3.0**. AdManageKit exposes the SDK as an `api` dependency, so apps on 4.4.1 resolve 1.3.0 transitively unless they pin it themselves.
+
+No AdManageKit code needed to change for this — the library was already on Next-Gen SDK patterns throughout (explicit `MobileAds.initialize()`, main-thread marshalling of background callbacks, Next-Gen `AdKit*` type aliases). `assembleDebug` and the full unit test suite (**168 tests, 0 failures**, forced re-run) pass against 1.3.0.
+
+Consult [Google's Next-Gen SDK release notes](https://developers.google.com/admob/android/migration) for what 1.3.0 changes on the SDK side. If your app references the SDK's own types directly (rather than only AdManageKit's `AdKitError` / `AdKitLoadError` / `AdKitValue` aliases), review those call sites — but nothing in AdManageKit's surface requires action.
+
+---
+
+## Fixed
+
+### API documentation generation (Dokka)
+
+The Deploy API Documentation workflow failed on every release since the Dokka 2.x upgrade. On an Android module, Dokka registers a source set per variant (`debug`, `release`, plus test/androidTest/testFixtures) *and* a generic `main`. Since `main`, `debug` and `release` all cover `src/main`, this tripped Dokka's duplicate-source-root check:
+
+```
+Pre-generation validity check failed: Source sets 'androidJvm' and 'release'
+have the common source roots: .../src/main/kotlin, .../src/main/java
+```
+
+All five modules were affected; CI only reported two because the build stopped early. Dokka is now configured to document the **release variant only** — matching what each module actually publishes via `components["release"]` — and to suppress the rest. That also keeps test and androidTest sources out of the public API docs, which they were never meant to be eligible for.
+
+The configuration lives in the root build rather than being repeated across five modules, so any new module is covered automatically.
+
+`dokkaGeneratePublicationHtml` now emits **1244 pages** across all five modules, including the 4.4.0 billing types (`BillingPeriod`, `OneTimeOfferInfo`, `ProductDetailsListener`, `InAppMessageListener`) and the new `AppPurchase` members. No test-source pages are emitted.
+
+### MCP server npm publishing
+
+The `publish-npm` job ran checkout, setup-node, download-artifact and `npm publish` with **no dependency install**. Because `package.json` declares `"prepublishOnly": "npm run build"`, `npm publish` re-ran `tsc` in a job with no `node_modules` and died with `TS2307 Cannot find module` on every import. The build job's uploaded artifact could not help — `prepublishOnly` rebuilds from source regardless.
+
+- `npm ci` added to `publish-npm` so `prepublishOnly` can build. The redundant `download-artifact` step is dropped; the build job stays as a verification gate.
+- **`zod` declared as a direct dependency.** It is imported by `tools/code-generation.ts` and `tools/documentation.ts` but appeared in neither `dependencies` nor `devDependencies`, resolving only because npm hoisted it out of `@modelcontextprotocol/sdk`. An SDK release nesting zod differently would have broken the build with no source change. The range mirrors the SDK's own (`^3.25 || ^4.0`) so npm can dedupe.
+
+### MCP tool schemas drifting from bundled docs
+
+Publishing current documentation was not enough — the code gating access to it was stale:
+
+- `get_release_notes` accepted only 17 versions while **38** release-notes files were bundled. Every version from 3.4.0 onward, including 4.4.0, was rejected at schema validation, and `"latest"` was hardcoded to 3.3.8.
+- `get_migration_guide` omitted **4.2.0**, the Next-Gen SDK migration — the one most consumers need.
+- `get_api_reference` listed 16 classes against 34 documented sections, hiding `OfferInfo`, `BillingPeriod`, `PurchaseResult` and others.
+- `TOPIC_MAP` had no entry for the `Subscription-Offers` wiki page.
+
+These lists are now **derived at startup from the bundled content**, so shipping a doc is sufficient to make it reachable: `discoverReleaseVersions()` scans `docs/release-notes/` (sorted newest-first by numeric version, with `"latest"` resolving to the newest file actually present), `discoverMigrationVersions()` scans the README for `### Migrating to X`, and `discoverApiClassNames()` reuses the `API_REFERENCE.md` section parser. `list_documentation` renders from those and appends any `TOPIC_MAP` key the hand-written grouping missed, so a registered topic can never be undiscoverable. The hardcoded `RELEASE_VERSIONS`, `MIGRATION_VERSIONS` and `API_CLASS_NAMES` constants are gone, leaving nothing to drift.
+
+`z.enum()` requires a non-empty tuple, so discovery degrades to a plain string when it finds nothing, rather than throwing at registration and taking the server down.
+
+### MCP code-generation templates emitting obsolete APIs
+
+The generator templates are hardcoded TypeScript, so unlike the bundled docs they gained nothing from republishing. They emitted code against APIs two major versions old — including one case that does not work at all.
+
+- **`generate_config` emitted no `MobileAds.initialize()` call.** Since v4.2.0 AdManageKit runs on the Next-Gen SDK, which removed the legacy SDK's silent lazy-init, so the generated `Application` class produced an app that never loads ads. Both the Kotlin and Java templates now initialize explicitly, off the main thread (`initialize()` blocks and can ANR), read the application id from the manifest, and construct `AppOpenManager` only after initialization returns — otherwise its lifecycle observer can fire a load the SDK rejects as "not initialized". This mirrors the sample app's `MyApplication.kt`.
+- **Billing `setup`** now emits `setDebugMode(BuildConfig.DEBUG)` (a library AAR always has `BuildConfig.DEBUG = false`, so the host app must inject its build state), obfuscated account ids, and the `ProductDetailsListener` for diagnosing an empty paywall.
+- **Billing `subscribe`** showed only `subscribe(activity, id)`, which resolves the offer itself and on a multi-offer product can charge for a plan the user did not pick. It now shows the offer-explicit form and explains why.
+- **New `offers` scenario** — multi-offer paywalls: enumerating offers, buying a specific one, savings badges, per-month normalization, trial eligibility, one-time product offers.
+- **New `account_hold` scenario** — client-side hold detection, Play's payment recovery flow, pending plan changes.
+- `subscription_management` and `subscribe` now handle `SubscriptionState.ON_HOLD`, which 4.4.0 made reachable.
+- The **Java template** was a stub covering only `setup` and `purchase`; it now mirrors the Kotlin coverage.
+- **`FRESH_WITH_CACHE_FALLBACK` was missing from every loading-strategy enum**, and native ads were restricted to two of the four values. All four fields now use a shared `AD_LOADING_STRATEGIES` constant mirroring `AdLoadingStrategy.kt`.
+
+---
+
+## Verification
+
+- `assembleDebug` succeeds and `testDebugUnitTest --rerun-tasks` passes **168 tests with 0 failures** against Next-Gen SDK 1.3.0 (forced re-run, not an up-to-date cache hit).
+- `dokkaGeneratePublicationHtml` succeeds across all five modules (1244 pages, no test-source pages).
+- `npm publish --dry-run` exercises the previously failing `prepublishOnly` path: builds clean, produces a 103-file tarball carrying 58 docs and 19 wiki pages.
+- A live MCP stdio session against real docs resolves 38 release versions (4.4.0 newest, `"latest"` → v4.4.0), 5 migration guides including 4.2.0, 33 API classes including `OfferInfo` and `BillingPeriod`, and 24 topics including `subscription-offers`.
+- Against a docs-less root, the server still starts, schemas degrade with no enum, and handlers return their normal "not found" messages.
+- Every symbol emitted by the refreshed templates was checked against library source: 25 `AppPurchase` methods, 15 `OfferInfo`/`OneTimeOfferInfo` properties, `SubscriptionState.ON_HOLD`, `BillingPeriod.formatOf`, and the `InAppMessageListener` / `ProductDetailsListener` method names all resolve. All nine billing scenarios generate in both languages.
+
+---
+
+## Upgrading
+
+Drop-in from 4.4.0 — no AdManageKit API changed, so no source edits are required.
+
+The one thing to be aware of is the transitive **Next-Gen SDK bump to 1.3.0**. If your app pins `com.google.android.libraries.ads.mobile.sdk` itself, either raise your pin to 1.3.0 or expect Gradle's conflict resolution to pick the higher version anyway. If your app calls the SDK's own types directly — rather than only AdManageKit's `AdKitError` / `AdKitLoadError` / `AdKitValue` aliases — give those call sites a compile pass.
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.1'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.1'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.1'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.1'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.1'
+```
+
+For the MCP server, `npx -y admanagekit-mcp-server` now resolves to 1.2.0 or newer.

package/content/docs/release-notes/RELEASE_NOTES_v4.4.2.md

@@ -0,0 +1,121 @@
+# Release Notes — v4.4.2
+
+**Release Date:** 2026-07-29
+
+## Overview
+
+v4.4.2 is a bug-fix release. No API was added, removed or changed — but several of these are user-visible, and two affect revenue directly:
+
+- **Rewarded ads could crash the app.** Every rewarded show-path callback, including `onRewardEarned`, was delivered on a background thread.
+- **A completed purchase could fail to disable ads**, leaving a paying customer looking at ads until the next app launch.
+- **Blank gaps** where a banner or native ad should have collapsed — for premium users and after a failed load, in both XML and Compose.
+- **App open ads could appear over excluded screens**, including flows protected by `disableAppOpenAdsTemporarily()`.
+
+Upgrading is a drop-in from 4.4.x. Two behavior changes are called out under [Behavior changes](#behavior-changes).
+
+---
+
+## Fixed
+
+### Rewarded ads: callbacks delivered off the main thread
+
+`RewardedAdManager` attached the Next-Gen SDK's event callbacks directly, with no marshalling anywhere on the direct (non-waterfall) path. `onAdDismissed`, `onAdShowed`, `onAdFailedToShow`, `onAdClicked` and — most importantly — the `onRewardEarned` reward listener all ran on a background thread.
+
+`onRewardEarned` and `onAdDismissed` are **abstract** on `RewardedAdCallback`: every consumer implements them, and they are exactly where apps grant the reward and update the UI. The result was a `CalledFromWrongThreadException` or a silently corrupted UI update on every rewarded flow that touched a view.
+
+All load, show and reward callbacks now post to the main thread. The waterfall path was already safe via its providers, but is now marshalled explicitly too, so the guarantee holds for third-party providers registered through `AdProviderConfig` rather than depending on their behavior.
+
+> The v4.3.1 threading fix covered interstitial `onNextAction`, the banner/native waterfall chains and `NativeTemplateView` — rewarded was missed.
+
+### A completed purchase could fail to disable ads
+
+`AppPurchase.handlePurchase(Purchase)` wrapped every entitlement mutation in `if (productDetailsMap.get(productId) != null)`. That map is populated **only** by a successful `queryProductDetailsAsync`, and Play declines product ids routinely — which is why `getUnfetchedProducts()` exists.
+
+When details were missing, the purchase was acknowledged, `onProductPurchased` fired, and the entitlement was silently dropped: `isPurchased()` kept returning `false` and **ads kept serving to a paying customer**. Nothing masked it, either — `verifyPurchased()` runs only on billing-service connect, so the state stayed wrong until the next app launch.
+
+Product type is now resolved from the configured `subProductIdList` / `inAppProductIdList` first — matching what `verifyPurchased()` already did — then from `productDetailsMap`, and finally from the purchase's own `isAutoRenewing()` flag. Granting on a reasonable inference beats billing someone and leaving the ads on.
+
+### Blank gaps where an ad should have collapsed
+
+Two independent causes, both producing the same symptom.
+
+**In XML/View usage:** `NativeBannerSmall`, `NativeBannerMedium` and `NativeLarge` hid only their shimmer for premium users and left the root visible, leaving an empty view with its padding and background. `NativeBannerMedium` never collapsed on load failure at all, and `NativeBannerSmall` only did so on the strategy path, not the direct AdMob one. All three now collapse the root, and reset visibility at load start so a later successful load isn't left invisible.
+
+**In Compose:** every wrapper claimed its height with a Compose modifier while the "hide me" logic lived in the View's `visibility`. Setting `visibility = GONE` cannot shrink the Compose node, so the ad vanished and the gap remained. Each `update` block then forced the view back to `VISIBLE`, undoing the hide the library had just performed — and for banners that ran through `showAd()`, which **restarts the shimmer** on an empty slot.
+
+Height is now driven by slot state rather than view visibility (`LOADING` and `SHOWN` reserve the ad's height so a fill doesn't shift the layout; `HIDDEN` occupies nothing), and no `update` block forces visibility unconditionally. `ProgrammaticNativeAdCompose`'s error branch rendered empty content inside a still-reserved 80–300dp box; that box now collapses.
+
+**All five Compose ad composables now gate on `rememberPurchaseStatus()`**, so a premium user issues no ad request and reserves no space. That helper already existed and was reactive — nothing internal used it.
+
+### Compose silently loaded nothing on a wrapped context
+
+Every Compose ad entry point gated on `context is ComponentActivity` — 12 sites, with no `ContextWrapper` unwrapping and, at ten of them, no `else` branch.
+
+`LocalContext.current` is the Activity in the common `setContent { }` case, but it is a `ContextThemeWrapper` inside `Dialog` / `ModalBottomSheet` composables, under per-screen theme wrappers, and in some `AndroidView`-nested compositions. There, the composable loaded nothing, fired no failure callback, and rendered an empty box forever with no diagnostics.
+
+New `Context.findComponentActivity()` unwraps the wrapper chain (mirroring `NativeBannerSmall.findHostActivity()`), and every site now reports a failure instead of failing silently.
+
+### App open ads could appear over excluded screens
+
+When an ad finished loading while the app was backgrounded, `onStart` routed it through a pending-ad path that checked purchase state, interstitial conflicts and activity validity — but **never `isActivityExcluded(...)` and never `skipNextAd`**.
+
+An app that called `disableAppOpenAdsTemporarily()` before a payment flow, or excluded its splash/PIN activity, could still get a full-screen ad there if the user backgrounded the app mid-fetch and returned. Both gates are now honored; the loaded ad stays cached for the next legitimate opportunity.
+
+### Retries could strand the caller waiting on them
+
+`AdRetryManager` keys retries by ad unit id, so scheduling for an id that already has one **replaces** it. `NativeAdIntegrationManager` deliberately withholds the failure callback when it schedules a retry, expecting that retry to deliver the result.
+
+Because the screen-specific key resolves to the *base* ad unit id, two native views sharing one ad unit (a `SMALL` and a `MEDIUM` on the same screen) collide — and the evicted retry's owner was never told anything. Its view held its shimmer forever.
+
+`scheduleRetry` now accepts an `onDropped` callback, invoked when a retry is replaced, cancelled, or refused because retries are disabled/exhausted. It is delivered via `Handler.post` so a handler that reacts by scheduling another retry cannot re-enter `scheduleRetry` mid-mutation. A non-atomic get-then-remove in `cancelRetry` was fixed alongside it.
+
+### Duplicate callbacks and duplicate ad shows
+
+`AdManager`'s force-show and splash flows guarded their outcomes with plain captured `var`s, written from both the SDK's background thread and the main-thread timeout. Neither side could see the other's write reliably, so a timeout landing alongside a load could deliver `onNextAction()` twice — breaking the once-per-flow contract callers gate navigation on — or attempt two shows.
+
+Each flow now uses a single `AtomicBoolean` latch shared across load-success, load-failure and timeout, so exactly one outcome wins.
+
+`AdManager.onAdShowedFullScreenContent` also invoked `callback.onAdShowed()` on the SDK thread while the dismiss and failure paths three lines away marshalled correctly; it now matches them.
+
+### Leaks
+
+- **`BannerAdView` never stopped auto-refresh on detach.** A banner inside a `RecyclerView`, `ViewPager` or a fragment whose view is destroyed kept requesting ads on schedule — indefinitely, since each refresh schedules the next — and the pending `Runnable` retained the Activity. Host `ON_DESTROY` only covers the case where the whole Activity goes away. Refresh now stops on detach and resumes on re-attach, and the lifecycle observer is unregistered on cleanup.
+- **`RewardedAdManager`'s retry closures captured the Activity** passed to `showAd()`, parked on the main `Handler` for up to `maxRetryDelay` off a process-lifetime singleton. They now use the application context, as `AdManager` already did at three sites.
+
+### Also hardened
+
+- `AdManager` no longer opens its loading dialog over a finishing or destroyed activity. A `BadTokenException` there left `isFetchingWithDialog` stuck `true`, permanently short-circuiting every later force-show to `onNextAction()`.
+- `showWaterfallWithWelcomeDialog` attaches to an in-flight load instead of starting a duplicate one, matching its non-waterfall twin.
+- Restored / already-acknowledged purchases now reach the purchase history listener; that branch previously skipped it.
+
+---
+
+## Behavior changes
+
+Both are deliberate, and both follow the library's existing account-hold stance.
+
+1. **An account-hold subscription no longer disables ads.** `getSubscriptionState()` already returned `ON_HOLD` and `isSubscriptionActive()` already returned `false` for these users, but `isPurchased()` still counted them — so they got no premium features *and* no ads. If your app deliberately keeps serving on-hold users ad-free, check `isSuspended()` explicitly. Pair `hasSubscriptionOnHold()` with `showInAppMessages(...)` to prompt a payment fix.
+
+2. **Premium users no longer reserve ad space in Compose.** Composables return before creating the view, so the slot occupies zero height rather than an empty block. If your layout relied on that reserved space, add it explicitly.
+
+---
+
+## Verification
+
+`assembleDebug` succeeds and `testDebugUnitTest --rerun-tasks` passes **173 tests, 0 failures** (168 existing plus 5 new `AdRetryManager` cases covering the `onDropped` contract, including a negative case proving a retry that runs does not also report dropped).
+
+The layout fixes are **not** covered by automated tests — the Compose module has no test source set and the View-layer visibility changes need a real hierarchy. They were verified by reading the visibility paths end to end; confirming them on-device is recommended.
+
+---
+
+## Upgrading
+
+Drop-in from 4.4.x. No source changes required; review the two behavior changes above.
+
+```groovy
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-compose:v4.4.2'
+implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-yandex:v4.4.2'
+```

package/content/wiki/Ad-Loading-Strategies.md

@@ -1,8 +1,8 @@
-# Ad Loading Strategies - AdManageKit v2.8.0
+# Ad Loading Strategies - AdManageKit v4.4.2
 
 ## Overview
 
-AdManageKit v2.6.0+ introduces three loading strategies that control how ads are fetched and displayed. Choose the right strategy based on your app's needs for user experience vs. ad coverage.
+AdManageKit v2.6.0+ introduces four loading strategies that control how ads are fetched and displayed. Choose the right strategy based on your app's needs for user experience vs. ad coverage.
 
 ## Strategy Types
 
@@ -63,15 +63,33 @@ AdManageKitConfig.interstitialLoadingStrategy = AdLoadingStrategy.HYBRID
 - Default recommendation
 - Balanced UX and coverage
 
+### 4. FRESH_WITH_CACHE_FALLBACK
+
+**Fetch fresh first, fall back to cache on failure**
+
+```kotlin
+AdManageKitConfig.nativeLoadingStrategy = AdLoadingStrategy.FRESH_WITH_CACHE_FALLBACK
+```
+
+| Pros | Cons |
+|------|------|
+| Freshest creative when the network cooperates | Slower than cache-first when the fetch is slow |
+| Cache covers the failure case | Requires a warm cache to help |
+| Successful loads are cached for later | - |
+
+**Best for:**
+- RecyclerView / feed scenarios where each item should try for a fresh ad
+- Placements where creative freshness matters more than instant fill
+
 ## Strategy Availability
 
-| Ad Type | ON_DEMAND | ONLY_CACHE | HYBRID |
-|---------|-----------|------------|--------|
-| Interstitial | ✅ | ✅ | ✅ |
-| App Open | ✅ | ✅ | ✅ |
-| Native | ✅ | ❌ | ✅ |
+| Ad Type | ON_DEMAND | ONLY_CACHE | HYBRID | FRESH_WITH_CACHE_FALLBACK |
+|---------|-----------|------------|--------|---------------------------|
+| Interstitial | ✅ | ✅ | ✅ | ✅ |
+| App Open | ✅ | ✅ | ✅ | ✅ |
+| Native | ✅ | ✅ | ✅ | ✅ |
 
-> **Note:** Native ads use shimmer instead of dialog, so ONLY_CACHE hides container if not cached.
+> **Note:** Native ads use shimmer instead of a dialog, so `ONLY_CACHE` hides the container when nothing is cached rather than blocking the UI.
 
 ## Configuration
 

package/content/wiki/App-Open-Ads.md

@@ -1,10 +1,10 @@
-# App Open Ads - AdManageKit v4.3.5
+# App Open Ads - AdManageKit v4.4.2
 
 ## Overview
 
 AdManageKit provides lifecycle-aware app open ad management through `AppOpenManager`. App open ads display when users launch or return to your app, with support for loading strategies, ad freshness enforcement, welcome dialogs, activity/screen exclusion, and the multi-provider waterfall.
 
-**Library Version**: v4.3.5
+**Library Version**: v4.4.2
 
 ## Features
 
@@ -23,9 +23,9 @@ AdManageKit provides lifecycle-aware app open ad management through `AppOpenMana
 
 ```groovy
 dependencies {
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.3.5'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.3.5'
-    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.3.5'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-billing:v4.4.2'
+    implementation 'com.github.i2hammad.AdManageKit:ad-manage-kit-core:v4.4.2'
 }
 ```