@chipmobilesdk/rn-ads 0.1.0 → 0.2.0

package/src/core/timers.ts

@@ -22,17 +22,81 @@ export const DEFAULT_SHOW_TIMEOUT_MS = 10_000;
  */
 export const DEFAULT_AD_VALIDITY_MS = 3_600_000;
 
+/**
+ * App-open's own window, deliberately shorter than the hour the other
+ * full-screen formats get (FR-130).
+ *
+ * Worth being explicit about why: Google expires app-open ads after **four
+ * hours**, which is *longer* than DEFAULT_AD_VALIDITY_MS, so the provider does
+ * not constrain this at all. The shorter window is a product decision. An
+ * app-open ad shows at the most prominent moment the app has, and a creative
+ * cached for an hour is stale by then; thirty minutes still spares a returning
+ * user the spinner of a cold load, which is both the worst app-open experience
+ * and the specific behavior store policy penalizes.
+ */
+export const DEFAULT_APP_OPEN_VALIDITY_MS = 1_800_000;
+
+/**
+ * How long `enabled: 'undecided'` may go unresolved before one warning fires.
+ *
+ * Ten seconds is several times a realistic worst case for the round trip this
+ * state exists to cover — asking a store whether the user owns an ad-removal
+ * entitlement — so an app doing the right thing essentially never trips it,
+ * while an app that forgot to resolve trips it inside a single QA session,
+ * which is where it needs to be caught (FR-119).
+ */
+export const DEFAULT_UNDECIDED_WARNING_MS = 10_000;
+
 export const LOAD_TIMEOUT_BOUNDS = { min: 5_000, max: 120_000 } as const;
 export const SHOW_TIMEOUT_BOUNDS = { min: 5_000, max: 30_000 } as const;
 export const AD_VALIDITY_BOUNDS = { min: 60_000, max: 3_600_000 } as const;
+/** Ceiling is one hour so app-open can never outlive the general window. */
+export const APP_OPEN_VALIDITY_BOUNDS = { min: 60_000, max: 3_600_000 } as const;
+export const UNDECIDED_WARNING_BOUNDS = { min: 1_000, max: 120_000 } as const;
+
+/**
+ * Retry defaults (FR-136).
+ *
+ * Two retries rather than more: each one is a billable request, and two covers
+ * the transient network failure and the momentary no-fill — the cases where
+ * trying again plausibly helps. A third mostly pays for a failure that was not
+ * transient. 2s then 4s keeps both inside a window the user still associates
+ * with the action that triggered the load.
+ */
+export const DEFAULT_RETRY_POLICY = {
+	maxRetries: 2,
+	initialDelayMs: 2_000,
+	maxDelayMs: 30_000,
+} as const;
+
+export const RETRY_BOUNDS = {
+	maxRetries: { min: 1, max: 5 },
+	initialDelayMs: { min: 500, max: 30_000 },
+	maxDelayMs: { min: 1_000, max: 60_000 },
+} as const;
+
+/**
+ * Ad-originated return detection (FR-128).
+ *
+ * A background transition within CLICK_WINDOW of a click is attributed to a
+ * browser the ad opened. An absence longer than MAX_AWAY is no longer
+ * attributable to the ad — the user did something else in between. GRACE covers
+ * the moment right after the return, where an app-open show would otherwise
+ * fire, without outliving it and refusing a genuinely later show.
+ */
+export const AD_CLICK_WINDOW_MS = 2_000;
+export const AD_RETURN_MAX_AWAY_MS = 300_000;
+export const AD_RETURN_GRACE_MS = 10_000;
 
 export interface ResolvedTimeouts {
 	readonly load: number;
 	readonly show: number;
 	readonly adValidity: number;
+	readonly appOpenValidity: number;
+	readonly undecidedWarning: number;
 }
 
-function checkBand(
+export function checkBand(
 	label: string,
 	value: number,
 	bounds: { readonly min: number; readonly max: number },
@@ -45,10 +109,15 @@ function checkBand(
 	return value;
 }
 
-export function resolveTimeouts(
-	timeouts: TimeoutConfig | undefined,
-	adValidityMs: number | undefined,
-): ResolvedTimeouts {
+export interface TimeoutInput {
+	readonly timeouts?: TimeoutConfig;
+	readonly adValidityMs?: number;
+	readonly appOpenValidityMs?: number;
+	readonly undecidedWarningMs?: number;
+}
+
+export function resolveTimeouts(input: TimeoutInput): ResolvedTimeouts {
+	const { timeouts, adValidityMs, appOpenValidityMs, undecidedWarningMs } = input;
 	return {
 		load: checkBand('timeouts.load', timeouts?.load ?? DEFAULT_LOAD_TIMEOUT_MS, LOAD_TIMEOUT_BOUNDS),
 		show: checkBand('timeouts.show', timeouts?.show ?? DEFAULT_SHOW_TIMEOUT_MS, SHOW_TIMEOUT_BOUNDS),
@@ -57,9 +126,39 @@ export function resolveTimeouts(
 			adValidityMs ?? DEFAULT_AD_VALIDITY_MS,
 			AD_VALIDITY_BOUNDS,
 		),
+		appOpenValidity: checkBand(
+			'appOpenValidityMs',
+			appOpenValidityMs ?? DEFAULT_APP_OPEN_VALIDITY_MS,
+			APP_OPEN_VALIDITY_BOUNDS,
+		),
+		undecidedWarning: checkBand(
+			'undecidedWarningMs',
+			undecidedWarningMs ?? DEFAULT_UNDECIDED_WARNING_MS,
+			UNDECIDED_WARNING_BOUNDS,
+		),
 	};
 }
 
+/**
+ * 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".
+ */
+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
@@ -71,12 +170,12 @@ export interface TimerSet {
 	size(): number;
 }
 
-export function createTimerSet(): TimerSet {
-	const handles = new Set<ReturnType<typeof setTimeout>>();
+export function createTimerSet(scheduler: Scheduler = realScheduler): TimerSet {
+	const handles = new Set<unknown>();
 
 	return {
 		after(ms, callback) {
-			const handle = setTimeout(() => {
+			const handle = scheduler.setTimeout(() => {
 				handles.delete(handle);
 				callback();
 			}, ms);
@@ -87,13 +186,13 @@ export function createTimerSet(): TimerSet {
 					return;
 				}
 				cleared = true;
-				clearTimeout(handle);
+				scheduler.clearTimeout(handle);
 				handles.delete(handle);
 			};
 		},
 		clearAll() {
 			for (const handle of handles) {
-				clearTimeout(handle);
+				scheduler.clearTimeout(handle);
 			}
 			handles.clear();
 		},

package/src/diagnostics/errors.ts

@@ -27,10 +27,21 @@ export type AdsErrorCode =
 	| 'unsupported_platform'
 	| 'provider_missing'
 	| 'disabled'
+	// The app has not decided whether ads are on. Sibling of `disabled`, and
+	// non-retryable for the same reason: calling again changes nothing until the
+	// app resolves it (FR-115).
+	| 'undecided'
 	// Privacy — resolved by consent changing, not by calling again.
 	| 'consent_required'
 	| 'consent_undetermined'
 	| 'requires_reinitialization'
+	// The package's own consent flow has not produced permission. Distinct from
+	// `consent_required`, which means the app's own gate is closed — a refusal
+	// has to name which of the two inputs is blocking (FR-105a).
+	| 'consent_flow_required'
+	// The consent flow failed. Never retried by the package: FR-135 excludes
+	// consent errors, and re-running the flow is the app's call, not a backoff's.
+	| 'consent_flow_failed'
 	// Runtime.
 	| 'no_fill'
 	| 'network_error'
@@ -41,13 +52,26 @@ export type AdsErrorCode =
 	| 'busy'
 	| 'consumed'
 	| 'app_inactive'
+	// The user came back to the app from an ad, or from a browser an ad opened.
+	// Only the package can know this, which is why refusing it is a capability
+	// rather than a policy (FR-128). Not retryable: retry covers load, and this
+	// is a show refusal that resolves with time rather than with another attempt.
+	| 'ad_originated_return'
 	| 'provider_error'
-	| 'internal_error';
+	| 'internal_error'
+	// Configuration — a retry policy outside its bounds. Rejected rather than
+	// clamped, matching `timeout_out_of_bounds`: silently clamping tells the app
+	// it configured something it did not.
+	| 'retry_out_of_bounds';
 
 /**
  * "Retrying this operation could plausibly succeed" — not "retry immediately".
- * The package ships no automatic retry in v1; pacing belongs to the app, which
- * is the only party that knows what a retry costs its users (FR-036).
+ *
+ * 0.2.0 added an opt-in retry policy, and this set is what it is allowed to act
+ * on. Everything outside it is excluded deliberately: configuration and consent
+ * errors, an unsupported platform, and a disabled or undecided instance are all
+ * states another attempt cannot change, so retrying them would spend a billable
+ * request on a certainty (FR-135).
  */
 const RETRYABLE: ReadonlySet<AdsErrorCode> = new Set<AdsErrorCode>([
 	'no_fill',

package/src/diagnostics/events.ts

@@ -29,6 +29,10 @@ export type AdEventType =
 	| 'disabled'
 	| 'unavailable'
 	| 'config_warning'
+	// Emitted once per retry attempt, carrying the correlation id of the load
+	// cycle that triggered it. Each attempt is a billable request, so it has to
+	// be reconcilable against a bill from the event stream alone (FR-138).
+	| 'retry_scheduled'
 	| 'internal_error';
 
 interface BaseEvent {
@@ -65,14 +69,50 @@ export type AdEvent = BaseEvent &
 				readonly operation: AdsOperation;
 				readonly reason: UnavailableReason | PrivacyBlockReason;
 		  }
+		| {
+				readonly type: 'retry_scheduled';
+				/** 1-based: the first retry is attempt 1, not 0. */
+				readonly attempt: number;
+				readonly delayMs: number;
+				readonly error: AdsError;
+		  }
 		| {
 				readonly type: 'config_warning';
-				readonly warning: 'test_ad_unit_substituted';
+				readonly warning: ConfigWarning;
+				/**
+				 * Placements the warning concerns. Empty for warnings that are not
+				 * placement-scoped.
+				 *
+				 * Present on every config warning rather than only on the one that
+				 * uses it, so that 0.1.0 code which reads `placementKeys` after
+				 * checking `type === 'config_warning'` keeps compiling. Splitting
+				 * this into one variant per warning would have been tidier and
+				 * would have broken every such consumer for no behavioral gain.
+				 */
 				readonly placementKeys: readonly string[];
+				/** Consent tools ignored, for `consent_tool_ignored_in_production`. */
+				readonly tools?: readonly string[];
+				/** How long the app left the state unresolved, for the undecided warning. */
+				readonly elapsedMs?: number;
 		  }
 		| { readonly type: 'internal_error'; readonly error: AdsError }
 	);
 
+/**
+ * Configuration problems worth telling the app about, all under one event type.
+ *
+ * One type rather than three because FR-132 forbids a parallel vocabulary, and
+ * because a consumer already routing `config_warning` into its logging should
+ * not have to subscribe again to keep seeing everything.
+ */
+export type ConfigWarning =
+	/** A production ad unit was replaced with an official test unit (FR-011a). */
+	| 'test_ad_unit_substituted'
+	/** The app left `enabled: 'undecided'` unresolved past its window (FR-119). */
+	| 'enablement_undecided_timeout'
+	/** Consent testing tools were supplied in production and ignored (FR-113). */
+	| 'consent_tool_ignored_in_production';
+
 export type AdEventListener = (event: AdEvent) => void;
 
 /** Events that may occur at most once within one correlated cycle (FR-054). */

package/src/engine/admobEngine.ts

@@ -19,7 +19,15 @@
 import { Platform } from 'react-native';
 
 import type { AdContentRating, FullScreenFormat, Unsubscribe } from '../config/types';
-import type { AdsEngine, EngineAdEvent, EngineAdHandle, EnginePrivacy } from './port';
+import type {
+	AdsEngine,
+	ConsentPort,
+	EngineAdEvent,
+	EngineAdHandle,
+	EngineConsentInfo,
+	EngineConsentOptions,
+	EnginePrivacy,
+} from './port';
 
 /** The slice of the bridge this adapter uses. Kept local so nothing else sees it. */
 interface ProviderFullScreenAd {
@@ -39,9 +47,79 @@ interface ProviderModule {
 	RewardedAd: {
 		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
 	};
+	AppOpenAd: {
+		createForAdRequest(adUnitId: string, options?: Record<string, unknown>): ProviderFullScreenAd;
+	};
 	AdEventType: Record<string, string>;
 	RewardedAdEventType: Record<string, string>;
 	MaxAdContentRating: Record<string, string>;
+	AdsConsent: ProviderConsent;
+	AdsConsentDebugGeography: Record<string, number>;
+}
+
+/** The slice of the bridge's consent module this adapter uses. */
+interface ProviderConsent {
+	requestInfoUpdate(options?: Record<string, unknown>): Promise<ProviderConsentInfo>;
+	loadAndShowConsentFormIfRequired(): Promise<ProviderConsentInfo>;
+	getConsentInfo(): Promise<ProviderConsentInfo>;
+	reset(): void;
+}
+
+interface ProviderConsentInfo {
+	status?: string;
+	canRequestAds?: boolean;
+	isConsentFormAvailable?: boolean;
+}
+
+/**
+ * The provider's geography enum is numeric and its spelling is the provider's.
+ * Translating here rather than in `core/` is the same rule the rest of this file
+ * follows: the one module that knows a provider exists is the one that speaks
+ * its vocabulary.
+ */
+function toProviderGeography(
+	geography: EngineConsentOptions['debugGeography'],
+	values: Record<string, number>,
+): number | undefined {
+	switch (geography) {
+		case 'eea':
+			return values.EEA;
+		case 'not_eea':
+			return values.NOT_EEA;
+		case 'regulated_us_state':
+			return values.REGULATED_US_STATE;
+		case 'other':
+			return values.OTHER;
+		case 'disabled':
+			return values.DISABLED;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Normalizes the provider's consent shape into the engine's.
+ *
+ * `canRequestAds` is taken as reported and never inferred from the status: the
+ * provider is the authority on whether a request is permitted, and second-
+ * guessing it here is how a package ends up requesting ads it should not
+ * (FR-106, FR-107).
+ */
+function toEngineConsentInfo(info: ProviderConsentInfo): EngineConsentInfo {
+	const status = String(info.status ?? 'UNKNOWN').toUpperCase();
+	const normalized: EngineConsentInfo['status'] =
+		status === 'OBTAINED'
+			? 'obtained'
+			: status === 'REQUIRED'
+				? 'required'
+				: status === 'NOT_REQUIRED'
+					? 'not_required'
+					: 'unknown';
+	return {
+		status: normalized,
+		canRequestAds: info.canRequestAds === true,
+		isFormAvailable: info.isConsentFormAvailable === true,
+	};
 }
 
 function loadProvider(): ProviderModule | null {
@@ -137,7 +215,12 @@ export function createAdMobEngine(): AdsEngine {
 				throw new Error('provider_missing');
 			}
 
-			const factory = format === 'rewarded' ? module.RewardedAd : module.InterstitialAd;
+			const factory =
+				format === 'rewarded'
+					? module.RewardedAd
+					: format === 'app_open'
+						? module.AppOpenAd
+						: module.InterstitialAd;
 			const ad = factory.createForAdRequest(adUnitId, {
 				// The consumer-facing polarity is `personalizedAds`; the provider's
 				// is the inverse. The flip lives here, next to the API needing it.
@@ -227,5 +310,64 @@ export function createAdMobEngine(): AdsEngine {
 		dispose(handle) {
 			ads.delete(handle.id);
 		},
+
+		consent: createAdMobConsent(getProvider),
+	};
+}
+
+/**
+ * The consent platform adapter.
+ *
+ * It is deliberately thin. Every decision that could be made here — whether a
+ * region requires consent, whether an error means "no", whether a dismissed form
+ * counts — is made elsewhere or not at all: the provider owns the first, and
+ * `core/consentFlow.ts` owns the second and third. This file's only job is to
+ * call the right method and hand back a shape that names nothing Google.
+ */
+function createAdMobConsent(getProvider: () => ProviderModule | null): ConsentPort {
+	function requireConsent(): ProviderConsent {
+		const module = getProvider();
+		if (!module?.AdsConsent) {
+			throw new Error('provider_missing');
+		}
+		return module.AdsConsent;
+	}
+
+	return {
+		async requestInfoUpdate(options: EngineConsentOptions) {
+			const module = getProvider();
+			if (!module?.AdsConsent) {
+				throw new Error('provider_missing');
+			}
+			const debugGeography = toProviderGeography(
+				options.debugGeography,
+				module.AdsConsentDebugGeography ?? {},
+			);
+			const info = await module.AdsConsent.requestInfoUpdate({
+				// Passing `undefined` rather than omitting keeps the call shape
+				// stable; the bridge treats an absent value as "no override".
+				debugGeography,
+				tagForUnderAgeOfConsent: options.underAgeOfConsent,
+				testDeviceIdentifiers: options.testDeviceIds
+					? [...options.testDeviceIds]
+					: undefined,
+			});
+			return toEngineConsentInfo(info);
+		},
+
+		async showFormIfRequired() {
+			// The provider decides whether a form is needed and renders it. The
+			// package never draws consent UI of its own (FR-103).
+			const info = await requireConsent().loadAndShowConsentFormIfRequired();
+			return toEngineConsentInfo(info);
+		},
+
+		async getInfo() {
+			return toEngineConsentInfo(await requireConsent().getConsentInfo());
+		},
+
+		reset() {
+			requireConsent().reset();
+		},
 	};
 }

package/src/engine/port.ts

@@ -41,6 +41,47 @@ export interface EngineAdHandle {
 	readonly id: string;
 }
 
+/**
+ * Consent status as the engine reports it — the provider's own vocabulary,
+ * lowercased, with nothing provider-shaped attached. `core/consentFlow.ts`
+ * normalizes this into the public `ConsentState`; keeping the two separate is
+ * what lets an iOS adapter map a different mechanism onto the same public shape
+ * without either side changing.
+ */
+export interface EngineConsentInfo {
+	readonly status: 'unknown' | 'required' | 'not_required' | 'obtained';
+	readonly canRequestAds: boolean;
+	readonly isFormAvailable: boolean;
+}
+
+export interface EngineConsentOptions {
+	/** Already stripped by config validation when the environment is production. */
+	readonly debugGeography?: 'disabled' | 'eea' | 'not_eea' | 'regulated_us_state' | 'other';
+	readonly underAgeOfConsent?: boolean;
+	readonly testDeviceIds?: readonly string[];
+}
+
+/**
+ * The provider's consent platform, behind the same boundary as everything else.
+ *
+ * It is a separate member of `AdsEngine` rather than more methods on it because
+ * it is a genuinely separate native module - the ads SDK and the consent SDK
+ * initialize independently and neither requires the other.
+ *
+ * The package orchestrates; it never renders. `showFormIfRequired` asks the
+ * provider to present its own form and reports what came back (FR-103).
+ */
+export interface ConsentPort {
+	/** Refreshes consent information, applying any testing options. */
+	requestInfoUpdate(options: EngineConsentOptions): Promise<EngineConsentInfo>;
+	/** Presents the provider's form if one is required; a no-op otherwise. */
+	showFormIfRequired(): Promise<EngineConsentInfo>;
+	/** Last known information without contacting the network. */
+	getInfo(): Promise<EngineConsentInfo>;
+	/** Clears the stored decision. Inert in production by configuration. */
+	reset(): void;
+}
+
 export interface AdsEngine {
 	/**
 	 * True when this platform has a working adapter. Checked before anything
@@ -69,4 +110,7 @@ export interface AdsEngine {
 
 	/** Releases the handle's provider resources. Safe to call more than once. */
 	dispose(handle: EngineAdHandle): void;
+
+	/** The provider's consent platform. Only touched if the app opts in (FR-102). */
+	readonly consent: ConsentPort;
 }

package/src/engine/testAdUnits.ts

@@ -28,6 +28,9 @@ const ANDROID_TEST_AD_UNITS: Readonly<Record<AdFormat, string>> = {
 	banner: 'ca-app-pub-3940256099942544/9214589741',
 	interstitial: 'ca-app-pub-3940256099942544/1033173712',
 	rewarded: 'ca-app-pub-3940256099942544/5224354917',
+	// Added in 0.2.0 alongside the app-open format. Cross-checked against the
+	// bridge's own `TestIds.APP_OPEN` at 16.0.3.
+	app_open: 'ca-app-pub-3940256099942544/9257395921',
 };
 
 export function testAdUnitFor(format: AdFormat): string {

package/src/index.ts

@@ -21,6 +21,10 @@ export type {
 	AdContentRating,
 	AdFormat,
 	AdsConfig,
+	ConsentSnapshot,
+	ConsentState,
+	ConsentTestingOptions,
+	Enablement,
 	Environment,
 	FullScreenFormat,
 	InitStatus,
@@ -28,6 +32,7 @@ export type {
 	PlacementState,
 	PrivacyBlockReason,
 	PrivacyOptions,
+	RetryPolicy,
 	Reward,
 	TimeoutConfig,
 	UnavailableReason,
@@ -39,17 +44,28 @@ export { isFullScreenFormat } from './config/types';
 // rather than discovering them from a timeout in production (FR-032).
 export {
 	AD_VALIDITY_BOUNDS,
+	APP_OPEN_VALIDITY_BOUNDS,
 	DEFAULT_AD_VALIDITY_MS,
+	DEFAULT_APP_OPEN_VALIDITY_MS,
 	DEFAULT_LOAD_TIMEOUT_MS,
+	DEFAULT_RETRY_POLICY,
 	DEFAULT_SHOW_TIMEOUT_MS,
+	DEFAULT_UNDECIDED_WARNING_MS,
 	LOAD_TIMEOUT_BOUNDS,
+	RETRY_BOUNDS,
 	SHOW_TIMEOUT_BOUNDS,
+	UNDECIDED_WARNING_BOUNDS,
 } from './core/timers';
 
+// Enablement. `EnablementResult` is what `setEnabled` returns in place of
+// 0.1.0's `void` — the defect that let a re-enable fail in silence (FR-122).
+export type { EnablementResult } from './core/enablement';
+
 // Instance, lifecycle, and results
 export { createAds } from './core/adsInstance';
 export type {
 	AdsInstance,
+	ConsentApi,
 	InitResult,
 	LoadResult,
 	PrivacyUpdateResult,
@@ -66,4 +82,10 @@ export { useAdsEvents, useAdsStatus, usePlacementState } from './react/hooks';
 // Diagnostics
 export { AdsConfigError, AdsError, isAdsError } from './diagnostics/errors';
 export type { AdsErrorCode, AdsOperation } from './diagnostics/errors';
-export type { AdEvent, AdEventListener, AdEventType, ImpressionSource } from './diagnostics/events';
+export type {
+	AdEvent,
+	AdEventListener,
+	AdEventType,
+	ConfigWarning,
+	ImpressionSource,
+} from './diagnostics/events';

package/src/react/AdsBanner.tsx

@@ -102,8 +102,22 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 		// `unavailable` and let the app keep its layout decision open. Every other
 		// non-ready status — disabled, blocked, failed, unsupported — means there
 		// will be no ad, and the app should reclaim the space (FR-039, FR-042).
+		//
+		// `undecided` is the exception added in 0.2.0, and it is the entire reason
+		// the third state exists. It is reported as itself rather than folded into
+		// either neighbour: `idle` would say "an ad is coming", which is not known
+		// yet, and `unavailable` would say "there will be none", which is also not
+		// known. Only by reporting it honestly can the app decide whether to hold
+		// the space — the choice that keeps a paying user from watching an ad
+		// flash in and out (FR-116).
 		if (status !== 'ready') {
-			move(status === 'not_started' || status === 'initializing' ? 'idle' : 'unavailable');
+			move(
+				status === 'undecided'
+					? 'undecided'
+					: status === 'not_started' || status === 'initializing'
+						? 'idle'
+						: 'unavailable',
+			);
 			return;
 		}
 		if (!resolution?.ok) {
@@ -229,12 +243,20 @@ export function AdsBanner({ placementKey, onStateChange, style }: AdsBannerProps
 	// tree rather than render an empty host. `not_started` and `initializing` are
 	// excluded on purpose: the host must stay mounted through them, because it is
 	// what measures the container and starts the load once the instance is ready.
+	//
+	// `undecided` is excluded for the same reason: the app may still resolve it to
+	// enabled, and a host that unmounted would have to re-measure the container
+	// from scratch when it did. It renders no ad meanwhile — it renders the same
+	// empty measuring host it renders while initializing — and it reports
+	// `undecided` so the app can size the space it decided to keep.
 	if (status === 'disabled' || status === 'unavailable' || status === 'failed') {
 		return null;
 	}
 
 	if (resolution && !resolution.ok) {
 		const refusal = resolution.result;
+		// `undecided` deliberately absent: unlike `disabled`, it is not a settled
+		// no, so the host stays mounted (FR-116).
 		if (refusal.status === 'disabled' || refusal.status === 'unavailable') {
 			return null;
 		}