@chipmobilesdk/rn-ads 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # @chipmobilesdk/rn-ads
 
+## 0.6.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+### Patch Changes
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -268,10 +268,12 @@ ads.subscribeEvents(event => {
 
 **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.
+**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. `AdsError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text.
+
+A config value outside its band names its own field and code: a timeout or validity window is `timeout_out_of_bounds`, a retry policy `retry_out_of_bounds`, a placement's `minRequestIntervalMs` `invalid_config`.
 
 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`
+Not retryable: `invalid_config` `duplicate_placement_key` `missing_ad_unit_id` `format_mismatch` `placement_not_found` `production_in_dev_build` `timeout_out_of_bounds` `retry_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:
 
@@ -741,6 +743,11 @@ engine.failConsentInfoRead();                   // the re-read after a failure r
 engine.consentCalls                             // includes 'showPrivacyOptionsForm'
 ```
 
+`runAdsEngineConformance(harness)` from `./testing` holds the checks every `AdsEngine`
+must pass — initialization, `loaded` reaching a subscriber and nothing after it
+unsubscribes, a reward and a dismissal, one handle per ad, and a dispose that is safe
+twice. The package runs it against the fake engine and the AdMob adapter.
+
 On device, verify with Google's official test ads only. `npm run android`, then exercise each `Ads · …` screen in the demo app.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-ads",
-	"version": "0.5.1",
+	"version": "0.6.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -31,9 +31,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -173,8 +173,8 @@ policy; everything else returns a typed result rather than throwing) · `AdsProv
 `SHOW_TIMEOUT_BOUNDS`, `AD_VALIDITY_BOUNDS`, `APP_OPEN_VALIDITY_BOUNDS`, `RETRY_BOUNDS`,
 `UNDECIDED_WARNING_BOUNDS`, `DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS`,
 `DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS`, `MIN_REQUEST_INTERVAL_BOUNDS`,
-`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock` from
-`@chipmobilesdk/rn-ads/testing` (test doubles only).
+`defaultMinRequestIntervalMs` · `createFakeAdsEngine`, `createTestClock`,
+`runAdsEngineConformance` from `@chipmobilesdk/rn-ads/testing` (test doubles only).
 
 Instance: `initialize`, `updatePrivacy`, `setEnabled`, `setEnablement`, `setAppActive`,
 `consent`, `getStatus`, `subscribeStatus`, `load`, `show`, `getPlacementState`,

package/src/config/validate.ts

@@ -146,10 +146,12 @@ export function validateConfig(config: AdsConfig, options: ValidateOptions): Res
 			key,
 			placement.minRequestIntervalMs === undefined
 				? defaultMinRequestIntervalMs(placement.format)
-				: checkBand(
+				: // A request floor, not a timeout: its own code (ADS-16).
+					checkBand(
 						`placements["${key}"].minRequestIntervalMs`,
 						placement.minRequestIntervalMs,
 						MIN_REQUEST_INTERVAL_BOUNDS,
+						'invalid_config',
 					),
 		);
 	}

package/src/core/adsInstance.ts

@@ -16,6 +16,12 @@
  * the caller injects — the AdMob adapter in production, the fake in tests.
  */
 
+import {
+	createListenerSet,
+	isDevBuild as detectDevBuild,
+	type ListenerSet,
+} from '@chipmobilesdk/rn-core';
+
 import {
 	isFullScreenFormat,
 	type AdFormat,
@@ -314,18 +320,23 @@ interface PlacementRuntime {
 	cancelLoadTimer: Unsubscribe | null;
 	cancelShowTimer: Unsubscribe | null;
 	rewarded: RewardedSession | null;
-	listeners: Set<(state: PlacementState) => void>;
+	listeners: ListenerSet<[PlacementState]>;
 	/** Retries already spent in this load cycle. Reset when a new cycle starts. */
 	retryAttempts: number;
 	/** Cancels a scheduled retry. Called by disable, undecided, and dispose. */
 	cancelRetry: Unsubscribe | null;
 }
 
-function detectDevBuild(): boolean {
-	return typeof __DEV__ !== 'undefined' ? Boolean(__DEV__) : false;
-}
-
-export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): AdsInstance {
+/**
+ * The instance itself. The public `createAds` (src/index.ts) passes the AdMob
+ * adapter as `defaultEngine`: core/ never loads an adapter, so it stays testable
+ * in Node and the provider stays replaceable (ADS-14).
+ */
+export function createAds(
+	config: AdsConfig,
+	options: CreateAdsOptions = {},
+	defaultEngine: () => AdsEngine = noDefaultEngine,
+): AdsInstance {
 	const isDevBuild = options.isDevBuild ?? detectDevBuild();
 	const now = options.now ?? (() => Date.now());
 
@@ -333,7 +344,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	// before anything else: a misconfigured instance should not exist at all.
 	const resolved: ResolvedConfig = validateConfig(config, { isDevBuild });
 
-	const engine: AdsEngine = options.engine ?? createDefaultEngine();
+	const engine: AdsEngine = options.engine ?? defaultEngine();
 	const events = createEventEmitter();
 	const correlation = createCorrelationIssuer();
 	// FR-140. Account safety, not product policy — see core/requestThrottle.ts.
@@ -387,7 +398,21 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	let disposed = false;
 	let warnedSubstitution = false;
 
-	const statusListeners = new Set<(status: InitStatus) => void>();
+	/**
+	 * Status, consent and placement listeners are consumer code. A failure is
+	 * isolated from the rest and reported the way an event listener's is: as an
+	 * `internal_error` event (FR-056).
+	 */
+	function reportListenerFailure(error: unknown): void {
+		events.emit({
+			type: 'internal_error',
+			timestamp: now(),
+			error: new AdsError('internal_error', { message: 'consumer listener threw', cause: error }),
+		});
+	}
+	const listenerOptions = { onListenerError: reportListenerFailure };
+
+	const statusListeners = createListenerSet<[InitStatus]>(listenerOptions);
 	const placements = new Map<string, PlacementRuntime>();
 
 	for (const key of resolved.placements.keys()) {
@@ -402,23 +427,17 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			cancelLoadTimer: null,
 			cancelShowTimer: null,
 			rewarded: null,
-			listeners: new Set(),
+			listeners: createListenerSet(listenerOptions),
 			retryAttempts: 0,
 			cancelRetry: null,
 		});
 	}
 
-	const consentListeners = new Set<(snapshot: ConsentSnapshot) => void>();
+	const consentListeners = createListenerSet<[ConsentSnapshot]>(listenerOptions);
 
 	function setConsent(next: ConsentSnapshot): void {
 		consent = next;
-		for (const listener of Array.from(consentListeners)) {
-			try {
-				listener(next);
-			} catch {
-				// Consumer code; isolated exactly as event listeners are (FR-056).
-			}
-		}
+		consentListeners.notify(next);
 	}
 
 	/**
@@ -487,14 +506,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			status: next.status,
 			retryable: next.error?.retryable,
 		});
-		for (const listener of Array.from(statusListeners)) {
-			try {
-				listener(next.status);
-			} catch {
-				// A status listener is consumer code; its failure is isolated the
-				// same way an event listener's is (FR-056).
-			}
-		}
+		statusListeners.notify(next.status);
 	}
 
 	function setPlacement(key: string, next: PlacementSnapshot): void {
@@ -506,13 +518,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			return;
 		}
 		runtime.snapshot = next;
-		for (const listener of Array.from(runtime.listeners)) {
-			try {
-				listener(next.state);
-			} catch {
-				// Isolated, as above.
-			}
-		}
+		runtime.listeners.notify(next.state);
 	}
 
 	function dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void {
@@ -1331,17 +1337,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			return init.status;
 		},
 
-		subscribeStatus(listener) {
-			statusListeners.add(listener);
-			let active = true;
-			return () => {
-				if (!active) {
-					return;
-				}
-				active = false;
-				statusListeners.delete(listener);
-			};
-		},
+		subscribeStatus: listener => statusListeners.add(listener),
 
 		async load(placementKey) {
 			if (disposed) {
@@ -1610,15 +1606,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 			if (!runtime) {
 				return () => undefined;
 			}
-			runtime.listeners.add(listener);
-			let active = true;
-			return () => {
-				if (!active) {
-					return;
-				}
-				active = false;
-				runtime.listeners.delete(listener);
-			};
+			return runtime.listeners.add(listener);
 		},
 
 		subscribeEvents(listener) {
@@ -1759,17 +1747,7 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 				return consent;
 			},
 
-			subscribe(listener) {
-				consentListeners.add(listener);
-				let active = true;
-				return () => {
-					if (!active) {
-						return;
-					}
-					active = false;
-					consentListeners.delete(listener);
-				};
-			},
+			subscribe: listener => consentListeners.add(listener),
 
 			async reset() {
 				if (disposed) {
@@ -1914,16 +1892,8 @@ export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): Ad
 	return instance;
 }
 
-/**
- * Resolved lazily so importing the package on a platform with no adapter — or
- * with the bridge absent — costs nothing and crashes nothing (FR-025, SC-004).
- */
-function createDefaultEngine(): AdsEngine {
-	// Deferred require keeps the provider off the import graph of every module
-	// that merely mentions `createAds`.
-	const { createAdMobEngine } =
-		require('../engine/admobEngine') as typeof import('../engine/admobEngine');
-	return createAdMobEngine();
+function noDefaultEngine(): AdsEngine {
+	throw new Error(
+		'core/createAds was called without an engine; production code uses createAds from the package entrypoint.',
+	);
 }
-
-declare const __DEV__: boolean | undefined;

package/src/core/retryPolicy.ts

@@ -21,6 +21,8 @@
  * TimerSet so `dispose()` can prove it released everything.
  */
 
+import { computeBackoff } from '@chipmobilesdk/rn-core';
+
 import { AdsConfigError } from '../diagnostics/errors';
 import { checkBand, DEFAULT_RETRY_POLICY, RETRY_BOUNDS } from './timers';
 import type { RetryPolicy } from '../config/types';
@@ -47,16 +49,20 @@ export function resolveRetryPolicy(policy: RetryPolicy, label: string): Resolved
 		`${label}.maxRetries`,
 		policy.maxRetries ?? DEFAULT_RETRY_POLICY.maxRetries,
 		RETRY_BOUNDS.maxRetries,
+		'retry_out_of_bounds',
+		'',
 	);
 	const initialDelayMs = checkBand(
 		`${label}.initialDelayMs`,
 		policy.initialDelayMs ?? DEFAULT_RETRY_POLICY.initialDelayMs,
 		RETRY_BOUNDS.initialDelayMs,
+		'retry_out_of_bounds',
 	);
 	const maxDelayMs = checkBand(
 		`${label}.maxDelayMs`,
 		policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
 		RETRY_BOUNDS.maxDelayMs,
+		'retry_out_of_bounds',
 	);
 
 	if (!Number.isInteger(maxRetries)) {
@@ -117,8 +123,12 @@ export function resolveEffectiveRetry(
  * than a property that does not apply.
  */
 export function delayForAttempt(policy: ResolvedRetryPolicy, attempt: number): number {
-	const raw = policy.initialDelayMs * Math.pow(2, Math.max(0, attempt - 1));
-	return Math.min(raw, policy.maxDelayMs);
+	return computeBackoff(attempt, {
+		initialDelayMs: policy.initialDelayMs,
+		maxDelayMs: policy.maxDelayMs,
+		factor: 2,
+		jitter: 'none',
+	});
 }
 
 /** Whether another attempt is permitted. `attemptsMade` counts retries only. */

package/src/core/timers.ts

@@ -8,8 +8,10 @@
  * something it did not (FR-008).
  */
 
-import { AdsConfigError } from '../diagnostics/errors';
-import type { TimeoutConfig, Unsubscribe } from '../config/types';
+import { checkRange, type Range } from '@chipmobilesdk/rn-core';
+
+import { AdsConfigError, type AdsErrorCode } from '../diagnostics/errors';
+import type { TimeoutConfig } from '../config/types';
 
 /** Comfortably longer than a normal fill on a slow mobile network, still bounded. */
 export const DEFAULT_LOAD_TIMEOUT_MS = 30_000;
@@ -96,17 +98,19 @@ export interface ResolvedTimeouts {
 	readonly undecidedWarning: number;
 }
 
+/**
+ * `value` when it is inside `bounds`, else an `AdsConfigError` with `code`: each
+ * field reports the code its documentation names, so a retry policy out of bounds
+ * is `retry_out_of_bounds`, not a timeout's code (CORE-04, ADS-16).
+ */
 export function checkBand(
 	label: string,
 	value: number,
-	bounds: { readonly min: number; readonly max: number },
+	bounds: Range,
+	code: AdsErrorCode = 'timeout_out_of_bounds',
+	unit = 'ms',
 ): number {
-	if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
-		throw new AdsConfigError('timeout_out_of_bounds', {
-			message: `${label} must be between ${bounds.min}ms and ${bounds.max}ms; received ${value}`,
-		});
-	}
-	return value;
+	return checkRange(label, value, bounds, message => new AdsConfigError(code, { message }), unit);
 }
 
 export interface TimeoutInput {
@@ -148,67 +152,11 @@ export function resolveTimeouts(input: TimeoutInput): ResolvedTimeouts {
 }
 
 /**
- * How timers are actually scheduled.
- *
- * Injectable so a test can drive retry backoff, app-open expiry, and the
- * undecided warning by moving a clock rather than by waiting. The production
- * default is `setTimeout`; the fake engine supplies a controllable one. Without
- * this, every timing assertion in the suite would either sleep for real or
- * depend on the test runner's timer mocking, and NFR-103's "no device, no
- * network" would quietly become "no device, no network, but several seconds".
+ * How timers are scheduled, and the set that tracks them so `dispose()` can prove
+ * it released every one (SC-008): rn-core's, injectable so a test drives retry
+ * backoff, app-open expiry and the undecided warning by moving a clock.
  */
-export interface Scheduler {
-	setTimeout(callback: () => void, ms: number): unknown;
-	clearTimeout(handle: unknown): void;
-}
-
-const realScheduler: Scheduler = {
-	setTimeout: (callback, ms) => setTimeout(callback, ms),
-	clearTimeout: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
-
-/**
- * Tracks every timer the instance owns so `dispose()` can prove it released
- * them. Counting is not incidental — SC-008 asserts the count reaches zero, and
- * a leaked timer is otherwise invisible until it fires into a disposed consumer.
- */
-export interface TimerSet {
-	after(ms: number, callback: () => void): Unsubscribe;
-	clearAll(): void;
-	size(): number;
-}
-
-export function createTimerSet(scheduler: Scheduler = realScheduler): TimerSet {
-	const handles = new Set<unknown>();
-
-	return {
-		after(ms, callback) {
-			const handle = scheduler.setTimeout(() => {
-				handles.delete(handle);
-				callback();
-			}, ms);
-			handles.add(handle);
-			let cleared = false;
-			return () => {
-				if (cleared) {
-					return;
-				}
-				cleared = true;
-				scheduler.clearTimeout(handle);
-				handles.delete(handle);
-			};
-		},
-		clearAll() {
-			for (const handle of handles) {
-				scheduler.clearTimeout(handle);
-			}
-			handles.clear();
-		},
-		size() {
-			return handles.size;
-		},
-	};
-}
+export { createTimerSet, type Scheduler, type TimerSet } from '@chipmobilesdk/rn-core';
 
 /** A loaded ad past its validity window must never be reported ready (FR-034). */
 export function isStale(loadedAtMs: number, nowMs: number, adValidityMs: number): boolean {

package/src/diagnostics/errors.ts

@@ -10,6 +10,8 @@
  * carrier for identifiers the package promises never to emit (FR-021).
  */
 
+import { SdkError, createRedactor } from '@chipmobilesdk/rn-core';
+
 import type { AdFormat } from '../config/types';
 
 export type AdsOperation = 'initialize' | 'load' | 'show' | 'configure';
@@ -94,9 +96,8 @@ export interface AdsErrorOptions {
 	readonly cause?: unknown;
 }
 
-export class AdsError extends Error {
-	readonly code: AdsErrorCode;
-	readonly retryable: boolean;
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-ads'`. */
+export class AdsError extends SdkError<AdsErrorCode> {
 	readonly operation?: AdsOperation;
 	readonly placementKey?: string;
 	readonly format?: AdFormat;
@@ -104,15 +105,17 @@ export class AdsError extends Error {
 	readonly cause?: string;
 
 	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
-		super(options.message ?? code);
+		const cause = options.cause === undefined ? undefined : redact(options.cause);
+		super('rn-ads', code, {
+			message: options.message,
+			retryable: RETRYABLE.has(code),
+			redactedCause: cause,
+		});
 		this.name = 'AdsError';
-		this.code = code;
-		this.retryable = RETRYABLE.has(code);
 		this.operation = options.operation;
 		this.placementKey = options.placementKey;
 		this.format = options.format;
-		this.cause = options.cause === undefined ? undefined : redact(options.cause);
-		Object.setPrototypeOf(this, AdsError.prototype);
+		this.cause = cause;
 	}
 }
 
@@ -125,7 +128,6 @@ export class AdsConfigError extends AdsError {
 	constructor(code: AdsErrorCode, options: AdsErrorOptions = {}) {
 		super(code, { ...options, operation: options.operation ?? 'configure' });
 		this.name = 'AdsConfigError';
-		Object.setPrototypeOf(this, AdsConfigError.prototype);
 	}
 }
 
@@ -133,23 +135,15 @@ export function isAdsError(value: unknown): value is AdsError {
 	return value instanceof AdsError;
 }
 
-const REDACTED = '[redacted]';
-
 /** An AdMob unit or app id. Redacted so a log never carries a live identifier. */
 const AD_UNIT_PATTERN = /ca-app-pub-\d+[~/]\d+/g;
-/** GAID and any other dashed UUID an SDK might put in a message. */
-const UUID_PATTERN = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g;
-/** Base64-ish runs long enough to be an encoded payload such as a consent string. */
-const PAYLOAD_PATTERN = /[A-Za-z0-9+/=_-]{40,}/g;
-/** Anything path- or URL-like, which can carry query parameters with identifiers. */
-const URL_PATTERN = /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"']+/g;
 
 /**
  * Keys dropped wholesale rather than pattern-matched, because their values are
  * sensitive regardless of shape — a bare advertising id has no separator for a
  * pattern to catch.
  */
-const SENSITIVE_KEYS = new Set([
+const SENSITIVE_KEYS = [
 	'adid',
 	'adUnitId',
 	'advertisingId',
@@ -160,54 +154,30 @@ const SENSITIVE_KEYS = new Set([
 	'tcString',
 	'token',
 	'userId',
-]);
+];
 
-function redactString(value: string): string {
-	return value
-		.replace(URL_PATTERN, REDACTED)
-		.replace(AD_UNIT_PATTERN, REDACTED)
-		.replace(UUID_PATTERN, REDACTED)
-		.replace(PAYLOAD_PATTERN, REDACTED);
-}
+/**
+ * rn-core's pattern redaction (URLs, JWTs, e-mail addresses, UUIDs, payload-sized
+ * runs) plus ad unit ids, with the keys above dropped. Provider messages are kept
+ * readable: they describe the failure, and every identifier in them is shaped.
+ */
+const redactor = createRedactor({
+	text: 'patterns',
+	patterns: [AD_UNIT_PATTERN],
+	dropKeys: SENSITIVE_KEYS,
+	maxDepth: 2,
+});
 
 /**
  * Reduces an arbitrary provider value to a safe string (FR-053, NFR-006).
  *
  * Returns a string rather than a structure on purpose: a redacted object still
  * hands the consumer a reference into provider-owned memory, and the contract
- * promises no provider object crosses the boundary.
+ * promises no provider object crosses the boundary. An `AdsError` reduces to its
+ * code.
  */
-export function redact(value: unknown, depth = 0): string {
-	if (value === null || value === undefined) {
-		return '';
-	}
-	if (typeof value === 'string') {
-		return redactString(value);
-	}
-	if (typeof value === 'number' || typeof value === 'boolean') {
-		return String(value);
-	}
-	if (value instanceof Error) {
-		return redactString(value.message);
-	}
-	if (depth >= 2) {
-		return REDACTED;
-	}
-	if (Array.isArray(value)) {
-		return value.map(item => redact(item, depth + 1)).join(', ');
-	}
-	if (typeof value === 'object') {
-		const parts: string[] = [];
-		for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-			if (SENSITIVE_KEYS.has(key)) {
-				parts.push(`${key}=${REDACTED}`);
-				continue;
-			}
-			parts.push(`${key}=${redact(entry, depth + 1)}`);
-		}
-		return parts.join(' ');
-	}
-	return REDACTED;
+export function redact(value: unknown): string {
+	return redactor.text(value);
 }
 
 /**

package/src/diagnostics/events.ts

@@ -19,7 +19,14 @@ import type {
 	UnavailableReason,
 	Unsubscribe,
 } from '../config/types';
-import { AdsError, type AdsErrorCode, type AdsOperation } from './errors';
+import {
+	createDiagnosticChannel,
+	createEmitter,
+	type DiagnosticSeverity,
+	type Emitter,
+} from '@chipmobilesdk/rn-core';
+
+import { AdsError, type AdsOperation } from './errors';
 
 export type AdEventType =
 	| 'initialization'
@@ -151,79 +158,83 @@ export interface AdEventEmitter {
 	listenerCount(): number;
 }
 
-export function createEventEmitter(): AdEventEmitter {
-	const listeners = new Set<AdEventListener>();
-	// `${correlationId}:${type}` for everything already emitted in a cycle.
-	const emittedOnce = new Set<string>();
-	let disposed = false;
-	// Guards against an internal_error thrown by a listener re-entering dispatch
-	// and recursing forever.
-	let reportingListenerFailure = false;
-
-	function dispatch(event: AdEvent): void {
-		for (const listener of Array.from(listeners)) {
-			try {
-				listener(event);
-			} catch (error) {
-				if (reportingListenerFailure) {
-					continue;
-				}
-				reportingListenerFailure = true;
-				try {
-					dispatch({
-						type: 'internal_error',
-						timestamp: Date.now(),
-						placementKey: event.placementKey,
-						format: event.format,
-						correlationId: event.correlationId,
-						error: new AdsError('internal_error' as AdsErrorCode, {
-							message: 'consumer event listener threw',
-							cause: error,
-						}),
-					});
-				} finally {
-					reportingListenerFailure = false;
-				}
-			}
-		}
+/**
+ * How many once-per-cycle keys the emitter remembers. A cycle's duplicates arrive
+ * within that cycle, so forgetting the oldest keys past this bound loses nothing,
+ * and memory stays flat however long the instance lives (CORE-12, ADS-05).
+ */
+const DEDUPE_CAPACITY = 256;
+
+/** Every delivered event also goes to the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<AdEventType>('rn-ads');
+
+function severityOf(event: AdEvent): DiagnosticSeverity {
+	switch (event.type) {
+		case 'internal_error':
+			return 'error';
+		case 'load_failed':
+		case 'display_failed':
+		case 'config_warning':
+			return 'warn';
+		default:
+			return 'info';
 	}
+}
+
+/** What a sink may see: where and which cycle, and an error's code. Never a payload. */
+function contextOf(event: AdEvent): Record<string, unknown> {
+	return {
+		...(event.placementKey === undefined ? {} : { placementKey: event.placementKey }),
+		...(event.format === undefined ? {} : { format: event.format }),
+		...('error' in event ? { code: event.error.code, retryable: event.error.retryable } : {}),
+	};
+}
+
+export function createEventEmitter(): AdEventEmitter {
+	// The event whose listeners are running, so a listener's failure is reported
+	// against the placement and cycle it broke (FR-056).
+	let dispatching: AdEvent | null = null;
+	const emitter: Emitter<AdEvent> = createEmitter<AdEvent>({
+		onListenerError(error) {
+			emitter.emit({
+				type: 'internal_error',
+				timestamp: Date.now(),
+				placementKey: dispatching?.placementKey,
+				format: dispatching?.format,
+				correlationId: dispatching?.correlationId,
+				error: new AdsError('internal_error', {
+					message: 'consumer event listener threw',
+					cause: error,
+				}),
+			});
+		},
+		dedupe: {
+			key: event =>
+				event.correlationId && ONCE_PER_CYCLE.has(event.type)
+					? `${event.correlationId}:${event.type}`
+					: undefined,
+			capacity: DEDUPE_CAPACITY,
+		},
+	});
 
 	return {
 		emit(event) {
 			// After dispose, a late provider callback updates nothing and emits
-			// nothing (FR-035, SC-008).
-			if (disposed) {
-				return;
-			}
-			if (event.correlationId && ONCE_PER_CYCLE.has(event.type)) {
-				const key = `${event.correlationId}:${event.type}`;
-				if (emittedOnce.has(key)) {
-					return;
+			// nothing (FR-035, SC-008); the rn-core emitter enforces both.
+			const previous = dispatching;
+			dispatching = event;
+			try {
+				if (emitter.emit(event)) {
+					channel.emit(event.type, severityOf(event), contextOf(event), event.correlationId);
 				}
-				emittedOnce.add(key);
+			} finally {
+				dispatching = previous;
 			}
-			dispatch(event);
-		},
-		subscribe(listener) {
-			listeners.add(listener);
-			let active = true;
-			return () => {
-				// Idempotent: a second call is a no-op, not an error (FR-005).
-				if (!active) {
-					return;
-				}
-				active = false;
-				listeners.delete(listener);
-			};
-		},
-		dispose() {
-			disposed = true;
-			listeners.clear();
-			emittedOnce.clear();
-		},
-		listenerCount() {
-			return listeners.size;
 		},
+		// Idempotent unsubscribe (FR-005).
+		subscribe: listener => emitter.subscribe(listener),
+		dispose: () => emitter.dispose(),
+		listenerCount: () => emitter.listenerCount(),
 	};
 }
 

package/src/engine/admobEngine.ts

@@ -16,6 +16,8 @@
  * applied.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
 import { Platform } from 'react-native';
 
 import type { AdContentRating, FullScreenFormat, Unsubscribe } from '../config/types';
@@ -141,15 +143,24 @@ function toEnginePrivacyOptions(value: string | undefined): EngineConsentInfo['p
 	}
 }
 
-function loadProvider(): ProviderModule | null {
+/**
+ * The provider bridge, loaded on first use (rn-core's lazy peer). It is a required
+ * peer, but a consumer can still have it missing mid-install or excluded from a
+ * build: reporting `provider_missing` beats crashing the host app's launch
+ * (FR-025, NFR-005). The banner component reaches it through the same loader.
+ */
+export const admobProvider = lazyPeer('react-native-google-mobile-ads', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
 	try {
 		return require('react-native-google-mobile-ads') as ProviderModule;
-	} catch {
-		// The bridge is a required peer, but a consumer can still have it missing
-		// mid-install or excluded from a build. Reporting `provider_missing`
-		// beats crashing the host app's launch (FR-025, NFR-005).
-		return null;
+	} catch (cause) {
+		throw cause;
 	}
+});
+
+function loadProvider(): ProviderModule | null {
+	const result = admobProvider.get();
+	return result.ok ? result.module : null;
 }
 
 function toProviderRating(

package/src/index.ts

@@ -16,6 +16,14 @@
  * frequency cap, and no screen name in this package (FR-045).
  */
 
+import type { AdsConfig } from './config/types';
+import {
+	createAds as createInstance,
+	type AdsInstance,
+	type CreateAdsOptions,
+} from './core/adsInstance';
+import { createAdMobEngine } from './engine/admobEngine';
+
 // Configuration and state
 export type {
 	AdContentRating,
@@ -73,7 +81,17 @@ export {
 export type { EnablementResult } from './core/enablement';
 
 // Instance, lifecycle, and results
-export { createAds } from './core/adsInstance';
+
+/**
+ * Creates an ads instance. This is the composition root: core's instance with
+ * the AdMob adapter as its default engine, so core/ itself never loads an
+ * adapter (ADS-14). The adapter resolves the provider bridge only on first use,
+ * so importing the package where there is no adapter, or no bridge, costs
+ * nothing and crashes nothing (FR-025, SC-004).
+ */
+export function createAds(config: AdsConfig, options: CreateAdsOptions = {}): AdsInstance {
+	return createInstance(config, options, createAdMobEngine);
+}
 export type {
 	AdsInstance,
 	ConsentApi,

package/src/react/AdsBanner.tsx

@@ -21,6 +21,7 @@ import { View, type LayoutChangeEvent, type ViewStyle } from 'react-native';
 
 import type { PlacementState } from '../config/types';
 import { AdsError, normalizeProviderError } from '../diagnostics/errors';
+import { admobProvider } from '../engine/admobEngine';
 import { useAds } from './AdsProvider';
 import type { ThrottledResult } from '../core/adsInstance';
 import { useAdsStatus } from './hooks';
@@ -38,12 +39,11 @@ interface ProviderBannerModule {
 	BannerAdSize: Record<string, string>;
 }
 
+// The engine's lazy loader, so the bridge is required in one place (ADS-12 still
+// tracks giving the banner its own seam on the engine port).
 function loadBannerModule(): ProviderBannerModule | null {
-	try {
-		return require('react-native-google-mobile-ads') as ProviderBannerModule;
-	} catch {
-		return null;
-	}
+	const result = admobProvider.get();
+	return result.ok ? (result.module as unknown as ProviderBannerModule) : null;
 }
 
 export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps) {
@@ -58,6 +58,9 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 	// produces a genuinely re-adapted banner rather than a stretched old one.
 	const [cycle, setCycle] = useState(0);
 	const correlationRef = useRef<string | null>(null);
+	// Whether the current correlation already reported `loaded`. The provider
+	// auto-refreshes a banner inside one mount; each refresh is a new cycle.
+	const loadedInCycleRef = useRef(false);
 	const startedAtRef = useRef(0);
 	// Whether this mount has already taken a throttle slot, and the refusal if it
 	// was refused. Resets with the mount, which is exactly the granularity FR-140
@@ -176,6 +179,7 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 			return;
 		}
 		correlationRef.current = resolution.correlationId;
+		loadedInCycleRef.current = false;
 		startedAtRef.current = Date.now();
 		move('loading');
 		ads.internals.emit({
@@ -213,16 +217,26 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 	);
 
 	const handleLoaded = useCallback(() => {
+		// A second load in one correlation is the provider's auto-refresh: a new
+		// ad, so a new cycle. Under the old correlation its `loaded` and
+		// `impression` were deduplicated away and revenue went uncounted (ADS-05).
+		// For a refresh, `durationMs` is the time since the previous load.
+		if (loadedInCycleRef.current && ads) {
+			correlationRef.current = ads.internals.nextCorrelationId();
+		}
+		loadedInCycleRef.current = true;
+		const loadedAt = Date.now();
 		move('ready');
 		emit({
 			type: 'loaded',
-			timestamp: Date.now(),
+			timestamp: loadedAt,
 			placementKey,
 			format: 'banner',
 			correlationId: correlationRef.current ?? undefined,
-			durationMs: Date.now() - startedAtRef.current,
+			durationMs: loadedAt - startedAtRef.current,
 		});
-	}, [emit, move, placementKey]);
+		startedAtRef.current = loadedAt;
+	}, [ads, emit, move, placementKey]);
 
 	const handleFailed = useCallback(
 		(error: unknown) => {

package/src/react/AdsProvider.tsx

@@ -10,8 +10,8 @@
  * startup where the app can decide what to do about it.
  */
 
+import { appLifecycle } from '@chipmobilesdk/rn-core';
 import React, { createContext, useContext, useEffect, type ReactNode } from 'react';
-import { AppState, type AppStateStatus } from 'react-native';
 
 import type { AdsInstance } from '../core/adsInstance';
 
@@ -23,7 +23,9 @@ export interface AdsProviderProps {
 	 * Whether the provider forwards foreground/background transitions to the
 	 * instance. On by default: FR-034's "never show while inactive" and
 	 * "re-evaluate a stale ad on return" both depend on the instance being told.
-	 * Turn it off only when the app already drives `setAppActive` itself.
+	 * Turn it off only when the app already drives `setAppActive` itself. The
+	 * transitions come from rn-core's shared `appLifecycle()`; `inactive` counts as
+	 * not active.
 	 */
 	readonly trackAppState?: boolean;
 	readonly children: ReactNode;
@@ -34,12 +36,9 @@ export function AdsProvider({ instance, trackAppState = true, children }: AdsPro
 		if (!trackAppState) {
 			return;
 		}
-		const subscription = AppState.addEventListener('change', (status: AppStateStatus) => {
-			instance.setAppActive(status === 'active');
+		return appLifecycle().subscribe(state => {
+			instance.setAppActive(state === 'active');
 		});
-		return () => {
-			subscription.remove();
-		};
 	}, [instance, trackAppState]);
 
 	return <AdsContext.Provider value={instance}>{children}</AdsContext.Provider>;

package/src/react/hooks.ts

@@ -10,7 +10,8 @@
  * state; it never holds provider-owned memory (FR-027).
  */
 
-import { useEffect, useState } from 'react';
+import { useExternalStore, useLatestCallback } from '@chipmobilesdk/rn-core/react';
+import { useCallback, useEffect } from 'react';
 
 import type { InitStatus, PlacementState } from '../config/types';
 import type { AdEventListener } from '../diagnostics/events';
@@ -19,42 +20,33 @@ import { useAds } from './AdsProvider';
 /** Live state for one placement. `unavailable` outside a provider. */
 export function usePlacementState(placementKey: string): PlacementState {
 	const ads = useAds();
-	const [state, setState] = useState<PlacementState>(() =>
-		ads ? ads.getPlacementState(placementKey) : 'unavailable',
+	const subscribe = useCallback(
+		(listener: () => void) =>
+			ads ? ads.subscribePlacement(placementKey, listener) : NO_SUBSCRIPTION,
+		[ads, placementKey],
 	);
-
-	useEffect(() => {
-		if (!ads) {
-			setState('unavailable');
-			return;
-		}
-		// Re-read on subscribe: the state may have moved between the initial
-		// render and this effect, and dropping that transition would leave the
-		// UI showing a state the instance has already left.
-		setState(ads.getPlacementState(placementKey));
-		return ads.subscribePlacement(placementKey, setState);
-	}, [ads, placementKey]);
-
-	return state;
+	const getSnapshot = useCallback(
+		(): PlacementState => (ads ? ads.getPlacementState(placementKey) : 'unavailable'),
+		[ads, placementKey],
+	);
+	// useSyncExternalStore: tear-free, and no transition lost between render and
+	// subscription, which the useState copy had to re-read to avoid.
+	return useExternalStore(subscribe, getSnapshot);
 }
 
 /** Live initialization status. `unavailable` outside a provider. */
 export function useAdsStatus(): InitStatus {
 	const ads = useAds();
-	const [status, setStatus] = useState<InitStatus>(() => (ads ? ads.getStatus() : 'unavailable'));
-
-	useEffect(() => {
-		if (!ads) {
-			setStatus('unavailable');
-			return;
-		}
-		setStatus(ads.getStatus());
-		return ads.subscribeStatus(setStatus);
-	}, [ads]);
-
-	return status;
+	const subscribe = useCallback(
+		(listener: () => void) => (ads ? ads.subscribeStatus(listener) : NO_SUBSCRIPTION),
+		[ads],
+	);
+	const getSnapshot = useCallback((): InitStatus => (ads ? ads.getStatus() : 'unavailable'), [ads]);
+	return useExternalStore(subscribe, getSnapshot);
 }
 
+const NO_SUBSCRIPTION = (): void => undefined;
+
 /**
  * Forwards every event to a listener without causing a render.
  *
@@ -65,11 +57,14 @@ export function useAdsStatus(): InitStatus {
  */
 export function useAdsEvents(listener: AdEventListener): void {
 	const ads = useAds();
+	// An inline listener is a new function every render; subscribing through the
+	// latest one keeps a single subscription per instance (PERF-13).
+	const latest = useLatestCallback(listener);
 
 	useEffect(() => {
 		if (!ads) {
 			return;
 		}
-		return ads.subscribeEvents(listener);
-	}, [ads, listener]);
+		return ads.subscribeEvents(latest);
+	}, [ads, latest]);
 }

package/src/testing/conformance.ts

@@ -0,0 +1,112 @@
+/**
+ * What any `AdsEngine` must do (IOS-12, ADS-13).
+ *
+ * The same checks run against the fake engine and against the AdMob adapter over
+ * the provider mock (or the real provider, from a demo screen on a device), so a
+ * test that drives the fake proves something about the device path. The subject
+ * says how the provider delivers its callbacks; the checks only use the port.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { Reward } from '../config/types';
+import type { AdsEngine, EngineAdEvent, EngineAdHandle } from '../engine/port';
+
+export interface AdsEngineSubject {
+	readonly engine: AdsEngine;
+	/** The provider finishes loading the ad behind `handle`. */
+	deliverLoad(handle: EngineAdHandle): void;
+	/** The provider grants a reward for the ad behind `handle`. */
+	deliverReward(handle: EngineAdHandle, reward: Reward): void;
+	/** The user closes the ad behind `handle`. */
+	deliverDismiss(handle: EngineAdHandle): void;
+}
+
+export interface AdsEngineHarness {
+	create(): AdsEngineSubject;
+}
+
+/** Lets callbacks a provider delivers on a later microtask arrive. */
+async function settle(): Promise<void> {
+	for (let turn = 0; turn < 3; turn += 1) {
+		await Promise.resolve();
+	}
+}
+
+export const adsEngineChecks: readonly Check<AdsEngineHarness>[] = [
+	{
+		name: 'is available, and initializes with privacy applied',
+		async run(harness) {
+			const { engine } = harness.create();
+			ensure(engine.isAvailable(), 'reported unavailable');
+			await engine.initialize({ childDirected: true, maxAdContentRating: 'G' });
+		},
+	},
+	{
+		name: 'delivers loaded to a subscriber of an interstitial, and nothing after unsubscribing',
+		async run(harness) {
+			const subject = harness.create();
+			const handle = await subject.engine.createFullScreen('interstitial', 'conformance/1');
+			ensure(typeof handle.id === 'string' && handle.id !== '', 'handle has no id');
+			const seen: EngineAdEvent['type'][] = [];
+			const stop = subject.engine.subscribe(handle, event => seen.push(event.type));
+			subject.deliverLoad(handle);
+			await settle();
+			ensure(seen.join(',') === 'loaded', `subscriber saw ${seen.join(',') || 'nothing'}`);
+			stop();
+			stop();
+			subject.deliverDismiss(handle);
+			await settle();
+			ensure(seen.length === 1, `notified after unsubscribing: ${seen.join(',')}`);
+		},
+	},
+	{
+		name: 'delivers the reward and the dismissal of a rewarded ad',
+		async run(harness) {
+			const subject = harness.create();
+			const handle = await subject.engine.createFullScreen('rewarded', 'conformance/2', {
+				personalizedAds: false,
+			});
+			const seen: EngineAdEvent[] = [];
+			subject.engine.subscribe(handle, event => seen.push(event));
+			subject.deliverLoad(handle);
+			await settle();
+			subject.deliverReward(handle, { type: 'coins', amount: 5 });
+			subject.deliverDismiss(handle);
+			await settle();
+			const reward = seen.find(event => event.type === 'rewarded');
+			ensure(reward?.type === 'rewarded', `no reward among ${seen.map(e => e.type).join(',')}`);
+			ensure(
+				reward.reward.type === 'coins' && reward.reward.amount === 5,
+				`reward ${JSON.stringify(reward.reward)}`,
+			);
+			ensure(seen.at(-1)?.type === 'dismissed', `last event ${seen.at(-1)?.type}`);
+		},
+	},
+	{
+		name: 'gives every ad its own handle',
+		async run(harness) {
+			const { engine } = harness.create();
+			const first = await engine.createFullScreen('interstitial', 'conformance/1');
+			const second = await engine.createFullScreen('interstitial', 'conformance/1');
+			ensure(first.id !== second.id, 'two ads share a handle');
+		},
+	},
+	{
+		name: 'disposes safely twice',
+		async run(harness) {
+			const { engine } = harness.create();
+			const handle = await engine.createFullScreen('interstitial', 'conformance/1');
+			engine.dispose(handle);
+			engine.dispose(handle);
+		},
+	},
+];
+
+export function runAdsEngineConformance(harness: AdsEngineHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, adsEngineChecks);
+}

package/src/testing/index.ts

@@ -203,6 +203,15 @@ export interface FakeAdsEngine extends AdsEngine {
 	failConsentInfoRead(cause?: unknown): void;
 }
 
+/**
+ * Runs `task` on the next microtask, which is when a provider's callbacks would
+ * arrive. Written out because React Native's type declarations omit
+ * `queueMicrotask`, although Hermes has it.
+ */
+function nextMicrotask(task: () => void): void {
+	Promise.resolve().then(task);
+}
+
 export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEngine {
 	const calls: FakeEngineCall[] = [];
 	const consentCalls: FakeConsentCall[] = [];
@@ -375,7 +384,7 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 			if (!options.neverCallBack) {
 				// `show` is called with a listener already attached, so this one
 				// can go out directly on the next microtask.
-				queueMicrotask(() => {
+				nextMicrotask(() => {
 					for (const listener of Array.from(listeners.get(handle.id) ?? [])) {
 						listener({ type: 'opened' });
 					}
@@ -395,7 +404,7 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 			const queued = pending.get(handle.id);
 			if (queued) {
 				pending.delete(handle.id);
-				queueMicrotask(() => {
+				nextMicrotask(() => {
 					for (const target of Array.from(listeners.get(handle.id) ?? [])) {
 						target(queued);
 					}
@@ -461,3 +470,6 @@ export function createFakeAdsEngine(options: FakeEngineOptions = {}): FakeAdsEng
 		},
 	};
 }
+
+export { adsEngineChecks, runAdsEngineConformance } from './conformance';
+export type { AdsEngineHarness, AdsEngineSubject } from './conformance';