@chipmobilesdk/rn-ads 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-ads` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The event catalog, error codes, state names, and result unions are **public API**. Renaming or removing any of them is a major change.
+
+## [0.1.0] — 2026-09-02
+
+Initial release. No migration required.
+
+### Added
+
+- **Provider-neutral public contract** for configuration, initialization, availability, load, show, events, errors, and cleanup. Consuming apps never import the Google Mobile Ads SDK; they name placement keys they chose.
+- **Three ad formats on Android**: anchored adaptive banner (`AdsBanner`), interstitial, and rewarded.
+- **Production-traffic guarantee.** In `development` and `test`, any ad unit that is not one of Google's official test units is replaced with one, reported as a `config_warning` naming every affected placement and surfaced through `getSubstitutedPlacements()`. `production` never substitutes. A debug build declaring `production` fails closed with `production_in_dev_build`.
+- **Enforced consent ordering.** No provider call of any kind occurs before the app's privacy gate permits requests. Child-directed, under-age-of-consent, content-rating, and personalization options are applied before the provider initializes; changing one afterwards reports `requires_reinitialization` rather than half-applying.
+- **Idempotent initialization.** Concurrent callers share one operation; the native SDK initializes at most once.
+- **Single full-screen lock.** At most one interstitial or rewarded ad is ever displayed. A refused show returns `busy` immediately and is never queued.
+- **Trustworthy rewards.** `reward_earned` is emitted only on provider confirmation, exactly once, and never inferred from dismissal. Both callback orderings produce the same outcome.
+- **Normalized event and error model** with a per-cycle `correlationId`, stable error codes, a `retryable` flag, and redacted causes. No provider object, advertising identifier, or consent payload crosses the boundary.
+- **Graceful degradation.** Ads disabled, an unsupported platform, a missing bridge, or a failing provider are ordinary conditions — no public operation throws.
+- **Bounded timeouts and staleness.** Load 30s, show 10s, loaded-ad validity 60 minutes, each configurable within a documented band. Out-of-band values are a configuration error rather than silently clamped.
+- **`./testing` entrypoint** exporting `createFakeAdsEngine`, so consumers can test their own integration with no device, network, or ad inventory.
+
+### Deliberately not included
+
+- **Automatic retry.** Retry pacing belongs to the app; every retry is a billable request. The contract is shaped so bounded, disableable retry can be added later without a breaking change.
+- **A consent management platform.** The package consumes a gate outcome and enforces ordering around it. Consent UX, copy, and policy are the app's.
+- **Frequency capping or placement rules.** The package never chooses when to interrupt a user.
+- **Any analytics dependency.** Events are emitted; forwarding them is the app's choice.
+
+### Known limitations
+
+- iOS is not implemented; the package reports `unavailable` / `unsupported_platform` and does not break an iOS build.
+- App-open, native, and rewarded-interstitial formats, and cross-network mediation, are deferred.
+- `impression` for full-screen formats is derived from the ad opening rather than provider-reported, because the provider's full-screen event enum has no impression member. Banners carry a true provider impression. The distinction is exposed as `source: 'provider' | 'derived'`.
+
+### Compatibility notes
+
+- `react-native-google-mobile-ads` is pinned to **`>=16.0.3 <16.1.0`**, not an open caret. Bridge 16.1.0+ bundles Google Mobile Ads 25.x, which carries Kotlin 2.3.0 metadata that React Native 0.85's pinned Kotlin 2.1.x compiler cannot read. The closed upper bound makes that a resolution failure at install time rather than a build failure later. Revisit when React Native ships a Kotlin 2.3 compiler.
+- Consuming apps must declare `react-native-google-mobile-ads.android_app_id` in their own `app.json`. This package carries no application ID and no ad unit ID.
+- The provider's manifest merges `INTERNET`, `ACCESS_NETWORK_STATE`, and `WAKE_LOCK`; `com.google.android.gms.permission.AD_ID` arrives transitively from `play-services-ads`. Apps that must not access the Advertising ID remove it with `tools:node="remove"`.
+
+[0.1.0]: https://github.com/chipmobilesdk/ChipMobileSdk/releases/tag/rn-ads%400.1.0

package/README.md

@@ -0,0 +1,372 @@
+# @chipmobilesdk/rn-ads
+
+Reusable advertising capability for ChipMobileSdk-family React Native apps.
+
+The package owns **capability**: a safe, consistent, provider-neutral way to request and present ads. Your app owns **policy**: where ads appear, when, how often, to whom, under what consent, and whether they appear at all. There is no placement rule, no frequency cap, and no screen name in this package.
+
+**You never import the Google Mobile Ads SDK.** You name a placement key you chose, and the package does the rest.
+
+---
+
+## Scope
+
+| | v1 |
+|---|---|
+| **Platform** | Android only. iOS returns `unavailable` / `unsupported_platform` and never breaks a build. |
+| **Provider** | Google AdMob, via `react-native-google-mobile-ads` |
+| **Formats** | Anchored adaptive banner, interstitial, rewarded |
+| **Deferred** | App-open, native, rewarded-interstitial, mediation, iOS — see [Known limitations](#known-limitations) |
+
+## Compatibility
+
+| | Supported |
+|---|---|
+| React | `>=19` (verified against 19.2.3) |
+| React Native | `>=0.85`, New Architecture (verified against 0.85.3) |
+| Node | `>=22.11.0` |
+| Android | `minSdk 24`, `compileSdk 36`, `targetSdk 36`, Kotlin 2.1.x |
+| Provider bridge | `react-native-google-mobile-ads` **`>=16.0.3 <16.1.0`** |
+| Google Mobile Ads Android SDK | 24.9.0 (transitive) |
+
+> **Why the bridge range is closed at the top.** Bridge 16.1.0+ moves to Google Mobile Ads 25.x, which is compiled with Kotlin 2.3.0 metadata. React Native 0.85.3 pins the Kotlin **compiler** at 2.1.x, and the build fails with `Module was compiled with an incompatible version of Kotlin`. Raising the root `ext.kotlinVersion` does not fix it — that moves only `kotlin-stdlib`, not the compiler. An open caret would let a routine `npm install` walk straight back into a build failure, so the range refuses rather than drifts. Revisit when React Native ships a Kotlin 2.3 compiler.
+
+---
+
+## Install
+
+```sh
+npm install @chipmobilesdk/rn-ads react-native-google-mobile-ads@16.0.3
+```
+
+### Required Android configuration
+
+Add your AdMob **application ID** to the app's `app.json`. The bridge's Gradle script reads this key and merges it into `AndroidManifest.xml`; without it the native SDK crashes on startup.
+
+```jsonc
+{
+  "react-native-google-mobile-ads": {
+    // Google's public test application ID. Replace with your own for release.
+    "android_app_id": "ca-app-pub-3940256099942544~3347511713"
+  }
+}
+```
+
+**The shared package carries no application ID and no ad unit ID.** Both are per-app configuration.
+
+### Permissions merged into your manifest
+
+Contributed by the provider, not requested by this package:
+
+Verified against a real merged manifest, not a list from documentation:
+
+| Permission | Source |
+|---|---|
+| `android.permission.INTERNET` | bridge manifest |
+| `android.permission.ACCESS_NETWORK_STATE` | bridge manifest |
+| `android.permission.WAKE_LOCK` | bridge manifest |
+| `com.google.android.gms.permission.AD_ID` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_AD_ID` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_ATTRIBUTION` | `play-services-ads-api` |
+| `android.permission.ACCESS_ADSERVICES_TOPICS` | `play-services-ads-api` |
+
+The last three are **Android Privacy Sandbox** permissions covering the Privacy Sandbox ad ID, attribution reporting, and the Topics API. They matter for your Data safety declaration and they are easy to miss, because they appear only in the merged result — no library README lists them.
+
+Verify the actual merged result before release — read the file, don't trust this table:
+
+```sh
+cd android && ./gradlew :app:assembleDebug
+# then inspect android/app/build/intermediates/merged_manifests/**/AndroidManifest.xml
+```
+
+**To remove advertising identifier access** (required for child-directed apps under Play Families policy).
+
+Removing `AD_ID` alone is **not enough** — verified by rebuild, the three Privacy Sandbox permissions survive it and must be removed explicitly:
+
+```xml
+<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" tools:node="remove" />
+<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" tools:node="remove" />
+```
+
+Your `<manifest>` tag needs `xmlns:tools="http://schemas.android.com/tools"`. Rebuild and re-inspect the merged manifest to confirm — do not assume.
+
+---
+
+## Configure
+
+Placement keys are **yours**. Provider ad unit IDs appear here in configuration and nowhere else in your code.
+
+```ts
+import { createAds } from '@chipmobilesdk/rn-ads';
+
+const ads = createAds({
+  enabled: true,                 // your feature flag; false makes everything a safe no-op
+  environment: 'development',    // 'development' | 'test' | 'production'
+  placements: [
+    { key: 'home_footer',       format: 'banner',       androidAdUnitId: 'ca-app-pub-…/…' },
+    { key: 'level_break',       format: 'interstitial', androidAdUnitId: 'ca-app-pub-…/…' },
+    { key: 'completion_reward', format: 'rewarded',     androidAdUnitId: 'ca-app-pub-…/…' },
+  ],
+});
+```
+
+`createAds` **throws** on a malformed catalog — duplicate key, missing ad unit, unknown format, out-of-band timeout — naming the offending placement. Every other failure in the package is a typed result, never a throw.
+
+Reading configuration requires no dotenv library, no remote-config service, and no feature-flag system. Supply the values however you like.
+
+### How production traffic is made impossible
+
+In `development` and `test`, any ad unit that is not one of Google's official test units is **replaced** with one, and the substitution is reported — as a `config_warning` event naming every affected placement, and in observable state via `ads.getSubstitutedPlacements()`.
+
+```
+environment: development
+  home_footer -> ca-app-pub-REAL…/1234567890
+
+  ⚠ config_warning: test_ad_unit_substituted
+      placementKeys: ['home_footer']
+  → request sent with ca-app-pub-3940256099942544/9214589741
+  → your app keeps working
+```
+
+In `production`, nothing is substituted — your units are used exactly as configured.
+
+The one case substitution cannot cover is a **debug build declaring `production`**: that would send real requests from a build that should never generate traffic. It fails closed with `production_in_dev_build`.
+
+> Invalid traffic from non-production builds can get an AdMob account suspended. **Never click a production ad to verify anything.**
+
+---
+
+## Initialize — consent comes first
+
+The package will not initialize anything request-capable until your privacy gate permits it. This is enforced, not documented: with the gate withheld, **zero** provider calls occur.
+
+```tsx
+import { AdsProvider } from '@chipmobilesdk/rn-ads';
+
+await ads.initialize({
+  canRequestAds: true,        // your consent decision — the package renders no consent UI
+  consentUndetermined: false, // true means "not asked yet", distinct from "refused"
+  childDirected: false,
+  underAgeOfConsent: false,
+  maxAdContentRating: 'G',
+  personalizedAds: true,
+});
+
+<AdsProvider instance={ads}>{children}</AdsProvider>
+```
+
+**Ordering matters.** `childDirected`, `underAgeOfConsent`, and `maxAdContentRating` only take effect if they reach the provider *before* it initializes. Change one afterwards and `updatePrivacy` returns `requires_reinitialization` rather than pretending it applied.
+
+Resolving consent after being blocked is the normal path and creates **no** duplicate initialization:
+
+```ts
+await ads.initialize({ canRequestAds: false });   // → { status: 'blocked', reason: 'consent_required' }
+await ads.updatePrivacy({ canRequestAds: true }); // → { status: 'applied' }, one native init total
+```
+
+The package logs no personal data, no consent payload, and no advertising identifier.
+
+---
+
+## Banner
+
+You place it. It sizes itself to your container and re-adapts on rotation.
+
+```tsx
+import { AdsBanner, usePlacementState } from '@chipmobilesdk/rn-ads';
+
+function Footer() {
+  const state = usePlacementState('home_footer');
+  const reserve = state === 'loading' || state === 'ready';
+
+  return reserve ? (
+    <View style={styles.slot}>
+      {state === 'loading' ? <YourThemedPlaceholder /> : null}
+      <AdsBanner placementKey="home_footer" />
+    </View>
+  ) : null; // your decision to reclaim the space
+}
+```
+
+The component **ships no placeholder** — that is yours, so it matches your theme. When ads are disabled or unavailable it renders `null`, not an empty view, so it leaves the accessibility tree entirely rather than taking screen-reader focus ahead of your content.
+
+## Interstitial and rewarded
+
+Load ahead of time; show only when *you* decide.
+
+```ts
+await ads.load('level_break');
+const result = await ads.show('level_break');
+
+switch (result.status) {
+  case 'shown':        break;
+  case 'not_ready':    break; // no UI opened, nothing crashed
+  case 'busy':         break; // another full-screen ad is up — never queued
+  case 'consumed':     break; // load a fresh one first
+  case 'app_inactive': break; // backgrounded
+  case 'blocked':      break; // result.reason
+  case 'disabled':     break;
+  case 'unavailable':  break; // result.reason
+  case 'timeout':      break;
+  case 'failed':       break; // result.error
+}
+```
+
+Rewards are reported **only** when the provider confirms them:
+
+```ts
+ads.subscribeEvents(event => {
+  if (event.type === 'reward_earned') {
+    grant(event.reward.type, event.reward.amount); // your grant, not the package's
+  }
+  if (event.type === 'dismissed' && event.rewardEarned === false) {
+    // closed early — no reward, and none inferred
+  }
+});
+```
+
+`reward_earned` and `dismissed` may arrive from the provider in either order; the outcome is identical, and a duplicate confirmation is collapsed into one event. **The package grants nothing** — validating and delivering the benefit is yours.
+
+---
+
+## State, events, and errors
+
+**Initialization status**: `not_started` · `blocked` · `initializing` · `ready` · `disabled` · `unavailable` · `failed`
+
+**Placement state**: `idle` · `loading` · `ready` · `showing` · `consumed` · `failed` · `unavailable`
+
+**Events** carry the placement key, format, timestamp, and a `correlationId` tying one load/show cycle together — enough to reconstruct an ad's whole life from the stream alone. They carry no provider object, no advertising identifier, and no consent payload.
+
+`initialization` · `load_started` · `loaded` · `load_failed` · `display_started` · `impression` · `click` · `display_failed` · `dismissed` · `reward_earned` · `disabled` · `unavailable` · `config_warning` · `internal_error`
+
+> **One honest asymmetry.** `impression` carries `source: 'provider' | 'derived'`. Banners get a real provider impression callback. Full-screen formats have none in the provider's event enum, so theirs is derived from the ad opening. If you reconcile these events against AdMob revenue reporting, you need to know which is which.
+
+**Ordering and exactly-once** are documented and tested. Within one `correlationId`, `loaded` / `display_started` / `impression` / `dismissed` / `reward_earned` occur at most once; `click` may repeat. After `dispose()`, zero events are emitted — a late provider callback is dropped.
+
+**Errors** carry a stable `code`, a log-safe `message`, the `operation`, a `retryable` flag, and a redacted `cause`. Codes are public API; renaming one is a breaking change.
+
+Retryable: `no_fill` `network_error` `load_timeout` `show_timeout` `ad_expired` `not_ready` `busy` `consumed` `app_inactive` `provider_error`
+Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `unsupported_platform` `provider_missing` `disabled` `consent_required` `consent_undetermined` `requires_reinitialization` `internal_error`
+
+Attach any logger or analytics you already use. The package depends on none:
+
+```ts
+const unsubscribe = ads.subscribeEvents(event => yourLogger.track(event.type, event));
+```
+
+A listener that throws is caught and reported once; it cannot break the state machine or starve other listeners.
+
+### Timeouts, retry, and cleanup
+
+| | Default | Configurable range |
+|---|---|---|
+| Load timeout | 30 000 ms | 5 000 – 120 000 |
+| Show timeout | 10 000 ms | 5 000 – 30 000 |
+| Loaded-ad validity | 3 600 000 ms | 60 000 – 3 600 000 |
+
+Out-of-band values are a configuration error, not silently clamped. A loaded full-screen ad older than its validity window stops reporting `ready` and requires a reload — so you never render a button for an ad that will fail on tap.
+
+**There is no automatic retry in v1.** Retry pacing is yours: you are the only party who knows what a retry costs your users, and every retry is a billable request.
+
+`dispose()` cancels every timer and subscription and releases every handle. It is idempotent, and so is every `Unsubscribe`.
+
+### Turning ads off
+
+`enabled: false` at construction, or `setEnabled(false)` at runtime, makes initialize/load/show safe no-ops that create no request and report `disabled`. In-flight loads are released deterministically. An ad **already on screen is not force-closed** — the provider offers no safe way to do so, and yanking a full-screen ad out from under the user would be worse than letting it finish.
+
+---
+
+## Testing
+
+The whole suite runs with **no device, no network, and no ad inventory**.
+
+```ts
+import { createFakeAdsEngine } from '@chipmobilesdk/rn-ads/testing';
+
+const engine = createFakeAdsEngine();
+const ads = createAds(config, { engine, isDevBuild: true });
+
+await ads.initialize({ canRequestAds: true });
+await ads.load('level_break');
+
+expect(engine.adUnitIds()).toEqual([/* only official test units */]);
+```
+
+The fake records every call, lets you resolve or reject each load and show, and lets you emit provider callbacks in **any order** — which is how the reward-ordering and late-callback cases are tested.
+
+```
+engine.calls           every call the package made, in order
+engine.adUnitIds()     what actually reached the provider
+engine.liveHandles()   non-empty after dispose means a leak
+engine.emit(id, ev)    you control ordering
+engine.listenerCount() must reach zero after cleanup
+```
+
+On device, verify with Google's official test ads only. `npm run android`, then exercise each `Ads · …` screen in the demo app.
+
+---
+
+## Release checklists
+
+### Before you ship
+
+- [ ] `npm run validate:ads` is green (lint, test, typecheck, pack dry-run)
+- [ ] `npm run android` and `npm run build:apk` both succeed
+- [ ] Merged manifest inspected; permissions match the table above and nothing else is new
+- [ ] Zero production ad requests observed from a `development` build — captured from logcat as release evidence
+- [ ] `environment: 'production'` is set only in release builds
+- [ ] No production ad unit, credential, or secret in this package
+
+### AdMob Console (cannot be done in code)
+
+- [ ] Android app registered under the correct package / application ID
+- [ ] A production ad unit created per placement, in the matching format
+- [ ] Account status and payment details verified
+- [ ] `app-ads.txt` published if you use it
+- [ ] Consent/privacy messaging configured if you use it
+- [ ] Content rating (`maxAdContentRating`) reviewed — ad content affects your app's age rating
+- [ ] Policy, traffic, and serving restrictions checked
+- [ ] **No self-clicking, ever**
+
+### Google Play Console
+
+- [ ] App declared as containing ads
+- [ ] **Data safety** updated: the Google Mobile Ads SDK collects the Advertising ID, coarse device and app information, and ad interaction signals on your behalf — this package collects and stores nothing of its own
+- [ ] Privacy policy covers advertising data
+- [ ] Target audience and content completed
+- [ ] Content rating questionnaire reflects ad content
+- [ ] Families requirements met if applicable — see below
+- [ ] Advertising ID declaration matches your target SDK and actual behavior
+- [ ] Regional consent requirements satisfied
+
+> **Children and families.** Ads plus advertising identifiers in an app that may reach children is a high-risk combination. This package supports `childDirected` and `underAgeOfConsent` as enforced pre-initialization inputs and documents the `AD_ID` removal path — but **it does not and cannot determine a user's age.** That determination, and the policy built on it, are yours.
+
+---
+
+## Known limitations
+
+- **iOS is not implemented.** Importing and calling the package on iOS is safe and returns `unavailable` / `unsupported_platform`.
+- **App-open, native, and rewarded-interstitial ads are deferred.** Each has its own lifecycle, view construction, or presentation policy that does not fit the three formats v1 models. They are additive later — a new `AdFormat` member, a factory branch in the engine adapter, and their own official test units.
+- **Mediation across multiple ad networks is out of scope.**
+- **Full-screen presentation, focus handling, and dismissal affordances are rendered by the provider** and outside this package's control. The package cannot make them accessible; it can only report what happened.
+- **`impression` for full-screen formats is derived**, not provider-reported. See the asymmetry note above.
+- **Bridge versions 16.1.0+ are unusable** under React Native 0.85. See [Compatibility](#compatibility).
+
+## Extending to iOS
+
+Adding iOS contributes exactly three things and changes **nothing** you have already written:
+
+1. **`PlacementDefinition.iosAdUnitId`** — the optional field already exists in v1's type, so existing Android-only catalogs stay valid.
+2. **A second engine adapter** behind the existing `AdsEngine` port. The port names no platform and no provider; that is what makes this additive.
+3. **iOS entries in the private test-ad-unit table.**
+
+Your `createAds`, `initialize`, `load`, `show`, `AdsBanner`, and every subscription keep their current signatures. The exported state, event, and error models do not change.
+
+Still to be done at that time, none of it touching the public contract: CocoaPods linking, the AdMob application ID in `Info.plist`, the SKAdNetwork identifiers Google requires, App Tracking Transparency, UMP/consent evaluation, the privacy manifest, and App Store privacy labels.
+
+## Versioning
+
+Semantic versioning. The event catalog, error codes, state names, and result unions are public API. New formats, new platforms, and new optional configuration arrive as additive minor releases; renaming or removing any of the above is a major.
+
+`0.1.0` is the initial release. No migration.

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@chipmobilesdk/rn-ads",
+	"version": "0.1.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/diagnostics",
+		"src/engine",
+		"src/react",
+		"src/testing",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-google-mobile-ads": ">=16.0.3 <16.1.0"
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-ads/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: sdk-rn-ads
+description: "Advertising via @chipmobilesdk/rn-ads: AdMob banner/interstitial/rewarded behind a provider-neutral contract, placement keys, consent gating, per-environment test-ad substitution. Use when adding ads to a screen, debugging an ad that never loads, mapping ad units per environment, or answering a Data safety question about advertising."
+metadata:
+  package: "@chipmobilesdk/rn-ads"
+  packageVersion: "0.1.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ads
+
+Adaptive banner, interstitial and rewarded ads on Android via Google AdMob, behind a
+contract that names no provider. The app names a placement key; the package owns the
+request. Consuming code never imports the Google Mobile Ads SDK.
+
+## Use this when
+
+- Adding a banner, interstitial or rewarded ad to a screen
+- Mapping AdMob ad units to placement keys per environment
+- Debugging an ad that never loads, or a `blocked` / `unavailable` / `provider_error`
+- Wiring consent so requests cannot precede it
+- Answering a Data safety / App Privacy question about advertising
+
+## Do not use this for
+
+- **Consent UI or copy** — the package consumes a gate outcome and enforces ordering; it
+  renders no dialog and ships no legal text.
+- **Where or how often ads appear** — no frequency cap, no placement rule, no auto-insert.
+- **Granting the reward** — it reports `reward_earned`; entitlement is the app's.
+- iOS — not implemented; every call returns `unavailable` / `unsupported_platform`.
+
+## Nothing loads until consent and initialization complete
+
+This is enforced, and it is the answer to almost every "the ad never appears". With the
+gate withheld, **zero** provider calls occur — not even configuration. `childDirected`,
+`underAgeOfConsent` and `maxAdContentRating` take effect only if they reach
+`initialize()` *before* the provider starts; changing one later returns
+`requires_reinitialization` rather than silently not applying.
+See `## Initialize — consent comes first`.
+
+## Never gate `<AdsBanner>` on its own placement state
+
+`AdsBanner` is what measures the container and starts the load, so it must be mounted
+unconditionally. Rendering it only when the state is `loading`/`ready` deadlocks at
+`idle` and no ad ever appears. Use the state for the *surrounding* placeholder and to
+decide whether to hold or reclaim space — never to decide whether to mount the host. It
+renders `null` on its own when there is nothing to show.
+
+## Two things not to "fix"
+
+- **The bridge pin.** `react-native-google-mobile-ads` is peered at `>=16.0.3 <16.1.0`;
+  16.1.0+ carries Kotlin 2.3 metadata that React Native 0.85's pinned compiler cannot
+  read, and the Android build fails outright. Read `## Compatibility` before widening it.
+- **Test ads in dev.** Outside `production`, non-official ad units are replaced with
+  Google's test units and reported via `config_warning` / `getSubstitutedPlacements()`.
+  That is the safety guarantee working, not a misconfiguration. Never click a production
+  ad to verify anything.
+
+## Public API (v0.1.0)
+
+Runtime: `createAds` (throws `AdsConfigError` on a bad catalog; everything else returns a
+typed result rather than throwing) · `AdsProvider`, `useAds` · `AdsBanner` ·
+`usePlacementState`, `useAdsStatus`, `useAdsEvents` · `AdsError`, `AdsConfigError`,
+`isAdsError`, `isFullScreenFormat` · `DEFAULT_LOAD_TIMEOUT_MS`, `DEFAULT_SHOW_TIMEOUT_MS`,
+`DEFAULT_AD_VALIDITY_MS`, `LOAD_TIMEOUT_BOUNDS`, `SHOW_TIMEOUT_BOUNDS`,
+`AD_VALIDITY_BOUNDS` · `createFakeAdsEngine` from `@chipmobilesdk/rn-ads/testing`
+(test doubles only).
+
+Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setAppActive`, `getStatus`,
+`subscribeStatus`, `load`, `show`, `getPlacementState`, `subscribePlacement`,
+`subscribeEvents`, `getSubstitutedPlacements`, `dispose`.
+
+Types: `AdsInstance`, `AdsConfig`, `PlacementDefinition`, `PrivacyOptions`, `AdFormat`,
+`FullScreenFormat`, `Environment`, `InitStatus`, `PlacementState`, `InitResult`,
+`LoadResult`, `ShowResult`, `PrivacyUpdateResult`, `Reward`, `AdEvent`, `AdEventType`,
+`AdEventListener`, `ImpressionSource`, `AdsErrorCode`, `AdsOperation`, `TimeoutConfig`,
+`AdContentRating`, `PrivacyBlockReason`, `UnavailableReason`, `Unsubscribe`,
+`AdsBannerProps`, `AdsProviderProps`.
+
+Call `dispose()` when the owning screen unmounts; it is idempotent, and so is every
+`Unsubscribe`.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ads/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Configure` |
+| Consent ordering | `## Initialize — consent comes first` |
+| Rendering a banner | `## Banner` |
+| Full-screen formats | `## Interstitial and rewarded` |
+| Results, events, errors, timeouts, cleanup | `## State, events, and errors` |
+| Tests without a device | `## Testing` |
+| Permissions, Data safety, families | `## Install`, `## Release checklists` |
+| Build failure after a bridge upgrade | `## Compatibility` |
+| What is deferred | `## Known limitations`, `## Extending to iOS` |

package/src/config/resolveAdUnit.ts

@@ -0,0 +1,85 @@
+/**
+ * The production-traffic guarantee (FR-011, FR-011a).
+ *
+ * A pure function, deliberately. This is the single point where a production ad
+ * unit can be replaced by an official test one, which is what makes SC-002
+ * provable rather than merely intended: a guarantee enforced in one place can be
+ * asserted; one spread across three call sites is a hope.
+ *
+ * The rule, from the 2026-09-02 clarification session:
+ *
+ *   production            -> use what the app configured, always, no exceptions
+ *   development / test    -> if it is not one of our own official test units,
+ *                            replace it and say so, loudly, naming the key
+ *
+ * Substitution rather than rejection is a deliberate trade. Rejecting would
+ * block a developer whose only mistake was pulling a teammate's environment
+ * file, and turn a configuration smell into a broken integration at every
+ * startup. Substituting keeps the app working — which is what a non-production
+ * build is for — and reports the problem as a first-class signal. The accepted
+ * cost is that a warning can be ignored; it is bounded because production never
+ * substitutes, so the misconfiguration surfaces there as ordinary behavior
+ * rather than as hidden state.
+ */
+
+import type { Environment, PlacementDefinition } from './types';
+import { isOfficialTestAdUnit, testAdUnitFor } from '../engine/testAdUnits';
+
+export interface ResolvedAdUnit {
+	readonly effectiveAdUnitId: string;
+	/** True when the configured identifier was replaced. Drives FR-011a's warning. */
+	readonly substituted: boolean;
+}
+
+export function resolveAdUnit(
+	placement: PlacementDefinition,
+	environment: Environment,
+): ResolvedAdUnit {
+	const configured = placement.androidAdUnitId;
+
+	// Production is the one environment where the package must not second-guess
+	// the app. Substituting here would silently rewrite configuration that was
+	// asked for on purpose, and would cost the publisher live revenue.
+	if (environment === 'production') {
+		return { effectiveAdUnitId: configured, substituted: false };
+	}
+
+	// Structural detection: anything that is not a known official test unit is
+	// treated as production-owned. Not a parse of AdMob's publisher-id format —
+	// see the note in engine/testAdUnits.ts on why that rule would be a liability.
+	if (isOfficialTestAdUnit(configured)) {
+		return { effectiveAdUnitId: configured, substituted: false };
+	}
+
+	return { effectiveAdUnitId: testAdUnitFor(placement.format), substituted: true };
+}
+
+export interface ResolvedCatalog {
+	/** Placement key to the ad unit that will actually be requested. */
+	readonly byKey: ReadonlyMap<string, string>;
+	/** Every key whose identifier was replaced, in catalog order (FR-011a). */
+	readonly substitutedKeys: readonly string[];
+}
+
+/**
+ * Resolves a whole catalog at once, so the warning can name every affected
+ * placement in a single event rather than trickling one out per load — an
+ * integrator wants to fix the whole file, not discover it a placement at a time.
+ */
+export function resolvePlacementAdUnits(
+	placements: readonly PlacementDefinition[],
+	environment: Environment,
+): ResolvedCatalog {
+	const byKey = new Map<string, string>();
+	const substitutedKeys: string[] = [];
+
+	for (const placement of placements) {
+		const resolved = resolveAdUnit(placement, environment);
+		byKey.set(placement.key, resolved.effectiveAdUnitId);
+		if (resolved.substituted) {
+			substitutedKeys.push(placement.key);
+		}
+	}
+
+	return { byKey, substitutedKeys };
+}