@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/src/core/adsInstance.ts

@@ -12,320 +12,37 @@
  *   FR-031  a consumed ad is never reused
  *   FR-035  after dispose, a late callback updates nothing and emits nothing
  *
- * Nothing in this file imports the provider. It talks to the engine port, which
- * 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,
-	type AdsConfig,
-	type ConsentSnapshot,
-	type Enablement,
-	type FullScreenFormat,
-	type InitStatus,
-	type PlacementDefinition,
-	type PlacementState,
-	type PrivacyBlockReason,
-	type PrivacyOptions,
-	type UnavailableReason,
-	type Unsubscribe,
-} from '../config/types';
-import { validateConfig, type ResolvedConfig } from '../config/validate';
-import { AdsError, normalizeProviderError } from '../diagnostics/errors';
-import {
-	createEventEmitter,
-	type AdEvent,
-	type AdEventListener,
-	type ImpressionSource,
-} from '../diagnostics/events';
-import { createRequestThrottle } from './requestThrottle';
-import { createCorrelationIssuer } from '../diagnostics/correlation';
-import type { AdsEngine, EngineAdEvent, EngineAdHandle } from '../engine/port';
-import { createFullScreenLock } from './fullScreenLock';
-import { canRequest, canStart, initialInit, initReducer, type InitSnapshot } from './initMachine';
-import {
-	canLoad,
-	initialPlacement,
-	placementReducer,
-	type PlacementSnapshot,
-} from './placementMachine';
-import {
-	evaluateGate,
-	requiresReinitialization,
-	toEnginePrivacy,
-	toEngineRequest,
-} from './privacyGate';
-import { evaluateGates, type ConsentGateInput, type GateDecision } from './gates';
-import { createRewardedSession, type RewardedSession } from './rewardedSession';
-import { createTimerSet, isStale, type Scheduler } from './timers';
-import { canResume, permitsRequests, type EnablementResult } from './enablement';
-import { canRetry, delayForAttempt } from './retryPolicy';
-import { createAdOriginatedTracker } from './adOriginatedReturn';
-import {
-	buildConsentOptions,
-	INITIAL_CONSENT,
-	needsForm,
-	normalizeConsent,
-	runConsentStep,
-	toConsentError,
-	toGateInput,
-} from './consentFlow';
-
-export type InitResult =
-	| { readonly status: 'ready' }
-	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
-	| { readonly status: 'disabled' }
-	/** The app has not decided whether ads are on. Nothing was requested (FR-115). */
-	| { readonly status: 'undecided' }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
-	| { readonly status: 'failed'; readonly error: AdsError };
-
-export type PrivacyUpdateResult =
-	| { readonly status: 'applied' }
-	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
-	| { readonly status: 'requires_reinitialization' }
-	| { readonly status: 'disabled' }
-	| { readonly status: 'undecided' }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
-	/**
-	 * The initialization this update triggered failed (added in 0.5.0). Before,
-	 * it was reported as `applied`, so the app never retried and no ad ever
-	 * showed, with nothing to say why.
-	 */
-	| { readonly status: 'failed'; readonly error: AdsError };
-
-export type LoadResult =
-	| { readonly status: 'loaded'; readonly correlationId: string }
-	| { readonly status: 'disabled' }
-	| { readonly status: 'undecided' }
-	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
-	| { readonly status: 'no_fill' }
-	/**
-	 * Refused by the per-placement request throttle (FR-140), added in 0.3.0.
-	 *
-	 * Nothing was requested and nothing is broken — this placement asked too
-	 * recently. Distinct from `no_fill` on purpose: no-fill means the network had
-	 * nothing to give, this means we did not ask. An app that treats them the same
-	 * will misdiagnose the first time a banner goes quiet.
-	 */
-	| ThrottledResult
-	| { readonly status: 'timeout' }
-	| { readonly status: 'failed'; readonly error: AdsError };
-
-export interface ThrottledResult {
-	readonly status: 'throttled';
-	readonly retryAfterMs: number;
-}
-
-/** A gate refusal: what a load gets when it may not ask at all. */
-type LoadRefusal = Extract<
-	LoadResult,
-	{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
->;
-
-export type ShowResult =
-	| { readonly status: 'shown'; readonly correlationId: string }
-	| { readonly status: 'not_ready' }
-	| { readonly status: 'busy' }
-	| { readonly status: 'consumed' }
-	| { readonly status: 'app_inactive' }
-	/**
-	 * The user came back to the app from an ad, or from a browser an ad opened,
-	 * so an app-open ad would be an ad immediately after an ad. Distinct from
-	 * `busy` and `not_ready` because the app cannot detect this itself and
-	 * therefore cannot infer it from either of those (FR-128).
-	 */
-	| { readonly status: 'ad_originated_return' }
-	| { readonly status: 'disabled' }
-	| { readonly status: 'undecided' }
-	| { readonly status: 'blocked'; readonly reason: PrivacyBlockReason }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason }
-	| { readonly status: 'timeout' }
-	| { readonly status: 'failed'; readonly error: AdsError };
-
-/**
- * What `consent.showPrivacyOptionsForm()` reports (FR-151), added in 0.4.0.
+ * This file only composes. Each responsibility lives in `core/instance/` and
+ * takes the shared context (ADS-10): the gate, initialization and enablement,
+ * full-screen load, show, consent, and the banner host's internals.
  *
- * Every refusal is its own member, so an app can tell "there is nothing to
- * offer here" from "you asked too early" from "it broke" without parsing an
- * error. None of them throws.
+ * Nothing here imports the provider. It talks to the engine port, which the
+ * caller injects — the AdMob adapter in production, the fake in tests.
  */
-export type PrivacyOptionsFormResult =
-	/**
-	 * The provider's form was presented and has closed. `consent` is the state it
-	 * left behind, already applied to the gate. A user who closed the form without
-	 * changing anything lands here too, with the state they already had.
-	 */
-	| { readonly status: 'shown'; readonly consent: ConsentSnapshot }
-	/** The provider does not require privacy options here. Nothing was presented. */
-	| { readonly status: 'not_required' }
-	/**
-	 * The requirement is not known yet: no successful `requestInfoUpdate()` since
-	 * the instance was created or reset, or the last one failed. Nothing was
-	 * presented.
-	 */
-	| { readonly status: 'info_update_required' }
-	/** A consent form is already on screen. Nothing was presented. */
-	| { readonly status: 'busy' }
-	/**
-	 * The form could not be presented or failed while open. The consent state is
-	 * whatever the provider reports it still holds, and never a new grant.
-	 */
-	| { readonly status: 'failed'; readonly error: AdsError }
-	| { readonly status: 'unavailable'; readonly reason: UnavailableReason };
-
-/**
- * The optional consent capability (FR-101).
- *
- * Grouped under its own namespace rather than flattened onto the instance so
- * that FR-102's optionality stays legible: an app that never touches
- * `ads.consent` never starts a flow. Five loose methods on the instance would
- * invite the assumption that they are part of the normal path.
- */
-export interface ConsentApi {
-	/** Refreshes consent information from the provider. */
-	requestInfoUpdate(): Promise<ConsentSnapshot>;
-	/** Presents the provider's form if one is required. Renders nothing itself. */
-	showFormIfRequired(): Promise<ConsentSnapshot>;
-	/**
-	 * Presents the provider's privacy options form, so a user can change an
-	 * answer already given (FR-151). Added in 0.4.0.
-	 *
-	 * Offer it when `getState().privacyOptionsRequirement` is `required`. Where
-	 * the entry point lives, and what it says, stay the app's. The outcome feeds
-	 * the privacy gate by itself, exactly as `showFormIfRequired` does.
-	 */
-	showPrivacyOptionsForm(): Promise<PrivacyOptionsFormResult>;
-	getState(): ConsentSnapshot;
-	subscribe(listener: (snapshot: ConsentSnapshot) => void): Unsubscribe;
-	/** Clears the stored decision. Inert in production (FR-113). */
-	reset(): Promise<void>;
-}
-
-export interface AdsInstance {
-	initialize(privacy: PrivacyOptions): Promise<InitResult>;
-	updatePrivacy(privacy: PrivacyOptions): Promise<PrivacyUpdateResult>;
-	/**
-	 * Turns ads on or off. Returns a result rather than `void` (FR-122).
-	 *
-	 * 0.1.0 returned nothing, which meant an app re-enabling ads after a lapsed
-	 * subscription had no way to learn that it also had to re-initialize — and
-	 * every load and show after that was refused in silence.
-	 */
-	setEnabled(enabled: boolean): EnablementResult;
-	/** The same, including the third state the app has not resolved yet. */
-	setEnablement(next: Enablement): EnablementResult;
-	setAppActive(active: boolean): void;
-	readonly consent: ConsentApi;
-	getStatus(): InitStatus;
-	subscribeStatus(listener: (status: InitStatus) => void): Unsubscribe;
-
-	load(placementKey: string): Promise<LoadResult>;
-	show(placementKey: string): Promise<ShowResult>;
-	getPlacementState(placementKey: string): PlacementState;
-	subscribePlacement(key: string, listener: (state: PlacementState) => void): Unsubscribe;
-
-	subscribeEvents(listener: AdEventListener): Unsubscribe;
-
-	/** FR-011a — substitution is observable state, not only a log line. */
-	getSubstitutedPlacements(): readonly string[];
-	/** FR-113 — the same treatment for consent tools dropped in production. */
-	getIgnoredConsentTools(): readonly string[];
-	/** Internal wiring for the banner host; not part of the documented surface. */
-	readonly internals: InstanceInternals;
-
-	dispose(): void;
-}
-
-/** What `AdsBanner` needs. Deliberately not documented as consumer API. */
-export interface InstanceInternals {
-	resolveBanner(placementKey: string):
-		| {
-				readonly ok: true;
-				readonly adUnitId: string;
-				readonly correlationId: string;
-				/** Current at resolution time, so a banner request honors `updatePrivacy`. */
-				readonly personalizedAds: boolean;
-		  }
-		| { readonly ok: false; readonly result: LoadResult };
-	/**
-	 * Takes the throttle slot for a banner cycle (FR-140).
-	 *
-	 * Called from the banner host's effect, after `resolveBanner` allowed it and
-	 * immediately before the provider component mounts. Idempotent for one
-	 * `correlationId`, so React running the effect twice charges one slot.
-	 *
-	 * Returns the refusal if the window closed between resolve and commit — rare,
-	 * but a second banner for the same placement mounting in the same tick would
-	 * do it.
-	 *
-	 * Emits nothing and sets no state: it is called during render, so the host
-	 * reports the refusal from its effect instead.
-	 */
-	commitBannerRequest(placementKey: string, correlationId: string): ThrottledResult | null;
-	/** The configured floor for a placement, so the host can report the cause. */
-	throttleFloorFor(placementKey: string): number;
-	emit(event: AdEvent): void;
-	setPlacementState(key: string, state: PlacementState): void;
-	isReady(): boolean;
-	nextCorrelationId(): string;
-	timerCount(): number;
-}
-
-export interface CreateAdsOptions {
-	/** Injected in tests; the AdMob adapter is the default in production. */
-	readonly engine?: AdsEngine;
-	/** Injected so the FR-012 rule is testable without touching a global. */
-	readonly isDevBuild?: boolean;
-	readonly now?: () => number;
-	/**
-	 * Injected so retry backoff, app-open expiry, and the undecided warning can
-	 * be driven by a test clock instead of by waiting. Production uses real
-	 * timers.
-	 */
-	readonly scheduler?: Scheduler;
-}
-
-interface PlacementRuntime {
-	snapshot: PlacementSnapshot;
-	/**
-	 * The cycle's correlation id, held here rather than read from the snapshot:
-	 * the reducer resets the snapshot on dismissal, and events emitted around
-	 * that transition must still carry the id of the cycle they belong to.
-	 */
-	correlationId: string | null;
-	/**
-	 * Whether this cycle already reported a dismissal. Format-independent — the
-	 * rewarded session guards its own, but interstitials need the same guard and
-	 * would otherwise report a repeated provider callback twice.
-	 */
-	dismissed: boolean;
-	handle: EngineAdHandle | null;
-	unsubscribeEngine: Unsubscribe | null;
-	inFlightLoad: Promise<LoadResult> | null;
-	/**
-	 * Settles the in-flight load with a given result. Only a consent withdrawal
-	 * uses it (FR-153): the caller awaiting `load()` is told `blocked` instead of
-	 * waiting on a request that has been abandoned.
-	 */
-	abortLoad: ((result: LoadResult) => void) | null;
-	cancelLoadTimer: Unsubscribe | null;
-	cancelShowTimer: Unsubscribe | null;
-	rewarded: RewardedSession | null;
-	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;
-}
+import type { AdsConfig } from '../config/types';
+import type { AdsEngine } from '../engine/port';
+import { createConsentApi } from './instance/consent';
+import { createInstanceContext } from './instance/context';
+import { cancelAllRetries, disarmUndecidedWarning } from './instance/gate';
+import { createInitController } from './instance/init';
+import { attachInternals, createInternals } from './instance/internals';
+import { createLoader } from './instance/load';
+import { createShower } from './instance/show';
+import type { AdsInstance, CreateAdsOptions } from './instance/types';
+
+export type {
+	AdsInstance,
+	ConsentApi,
+	CreateAdsOptions,
+	InitResult,
+	LoadRefusal,
+	LoadResult,
+	PrivacyOptionsFormResult,
+	PrivacyUpdateResult,
+	ShowResult,
+	ThrottledResult,
+} from './instance/types';
+export { getInternals, type InstanceInternals } from './instance/internals';
 
 /**
  * The instance itself. The public `createAds` (src/index.ts) passes the AdMob
@@ -337,1558 +54,84 @@ export function createAds(
 	options: CreateAdsOptions = {},
 	defaultEngine: () => AdsEngine = noDefaultEngine,
 ): AdsInstance {
-	const isDevBuild = options.isDevBuild ?? detectDevBuild();
-	const now = options.now ?? (() => Date.now());
-
-	// Throws on a structural fault or the FR-012 fail-closed case. Deliberately
-	// before anything else: a misconfigured instance should not exist at all.
-	const resolved: ResolvedConfig = validateConfig(config, { isDevBuild });
-
-	const engine: AdsEngine = options.engine ?? defaultEngine();
-	const events = createEventEmitter();
-	const correlation = createCorrelationIssuer();
-	// FR-140. Account safety, not product policy — see core/requestThrottle.ts.
-	const requestThrottle = createRequestThrottle(now);
-	const timers = createTimerSet(options.scheduler);
-	const lock = createFullScreenLock();
-	const adReturn = createAdOriginatedTracker();
-
-	/**
-	 * An instance told it is `undecided` says so from the moment it exists.
-	 *
-	 * Without this it reports `not_started` until `initialize()` runs, which is
-	 * indistinguishable from a disabled instance at exactly the point an app is
-	 * deciding whether to reserve the banner's space — so FR-116 would hold only
-	 * after a call the app has no reason to make yet. Found on device, not in a
-	 * unit test, because the demo screen defers initialization the way a real
-	 * entitlement-gated app does.
-	 *
-	 * `disabled` deliberately keeps 0.1.0's `not_started` here: that behavior is
-	 * observable today and BC-004 protects it. The asymmetry is the cost of not
-	 * changing something that already shipped.
-	 */
-	let init: InitSnapshot =
-		resolved.enablement === 'undecided'
-			? initReducer(initialInit, { type: 'UNDECIDE' })
-			: initialInit;
-	let enablement: Enablement = resolved.enablement;
-	let appActive = true;
-	let consent: ConsentSnapshot = INITIAL_CONSENT;
-	let consentStarted = false;
-	/**
-	 * Consent forms currently on screen. A count rather than a flag because
-	 * `showFormIfRequired` has never refused a concurrent call and 0.4.0 does not
-	 * start now; only the privacy options form reads it, to report `busy`.
-	 */
-	let consentFormsOpen = 0;
-	let privacyOptionsFormOpen = false;
-	/**
-	 * Whether the provider has been natively initialized, ever, by this instance.
-	 *
-	 * Tracked apart from the init status because the status can leave `ready` —
-	 * a withdrawn consent moves it to `blocked` — while the native SDK stays
-	 * initialized. Re-granting must resume, not initialize again (FR-022, FR-154).
-	 */
-	let providerInitialized = false;
-	let undecidedWarned = false;
-	let cancelUndecidedTimer: Unsubscribe | null = null;
-	let appliedPrivacy: PrivacyOptions | null = null;
-	let currentPrivacy: PrivacyOptions | null = null;
-	let inFlightInit: Promise<InitResult> | null = null;
-	let disposed = false;
-	let warnedSubstitution = false;
-
-	/**
-	 * 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()) {
-		placements.set(key, {
-			snapshot: initialPlacement,
-			correlationId: null,
-			dismissed: false,
-			handle: null,
-			unsubscribeEngine: null,
-			inFlightLoad: null,
-			abortLoad: null,
-			cancelLoadTimer: null,
-			cancelShowTimer: null,
-			rewarded: null,
-			listeners: createListenerSet(listenerOptions),
-			retryAttempts: 0,
-			cancelRetry: null,
-		});
-	}
-
-	const consentListeners = createListenerSet<[ConsentSnapshot]>(listenerOptions);
-
-	function setConsent(next: ConsentSnapshot): void {
-		consent = next;
-		consentListeners.notify(next);
-	}
-
-	/**
-	 * The consent flow's contribution to the gate, or `null` when the app never
-	 * opted in.
-	 *
-	 * `null` is what makes FR-102 structural rather than conditional: with no
-	 * flow started, the gate sees only the app's own input and behaves exactly as
-	 * 0.1.0 did. There is no code path to skip and therefore none to forget.
-	 */
-	function consentGateInput(): ConsentGateInput {
-		return consentStarted ? toGateInput(consent) : null;
-	}
-
-	/**
-	 * Warns once if the app leaves `undecided` unresolved (FR-119).
-	 *
-	 * Once, not repeatedly: a warning that fires every ten seconds becomes noise
-	 * that gets filtered, which defeats the diagnostic. And it only warns — the
-	 * package never resolves the state itself, because doing so would mean
-	 * guessing at exactly the business decision FR-120 forbids it from knowing.
-	 */
-	function armUndecidedWarning(): void {
-		if (enablement !== 'undecided' || undecidedWarned || cancelUndecidedTimer) {
-			return;
-		}
-		const armedAt = now();
-		cancelUndecidedTimer = timers.after(resolved.timeouts.undecidedWarning, () => {
-			cancelUndecidedTimer = null;
-			if (disposed || enablement !== 'undecided' || undecidedWarned) {
-				return;
-			}
-			undecidedWarned = true;
-			events.emit({
-				type: 'config_warning',
-				timestamp: now(),
-				warning: 'enablement_undecided_timeout',
-				placementKeys: [],
-				elapsedMs: now() - armedAt,
-			});
-		});
-	}
-
-	function disarmUndecidedWarning(): void {
-		cancelUndecidedTimer?.();
-		cancelUndecidedTimer = null;
-	}
-
-	/** Cancels every pending retry, everywhere (FR-137). */
-	function cancelAllRetries(): void {
-		for (const runtime of placements.values()) {
-			runtime.cancelRetry?.();
-			runtime.cancelRetry = null;
-		}
-	}
-
-	function setInit(next: InitSnapshot): void {
-		if (next === init || next.status === init.status) {
-			init = next;
-			return;
-		}
-		init = next;
-		events.emit({
-			type: 'initialization',
-			timestamp: now(),
-			status: next.status,
-			retryable: next.error?.retryable,
-		});
-		statusListeners.notify(next.status);
-	}
-
-	function setPlacement(key: string, next: PlacementSnapshot): void {
-		const runtime = placements.get(key);
-		if (!runtime || runtime.snapshot.state === next.state) {
-			if (runtime) {
-				runtime.snapshot = next;
-			}
-			return;
-		}
-		runtime.snapshot = next;
-		runtime.listeners.notify(next.state);
-	}
-
-	function dispatchPlacement(key: string, event: Parameters<typeof placementReducer>[1]): void {
-		const runtime = placements.get(key);
-		const definition = resolved.placements.get(key);
-		if (!runtime || !definition) {
-			return;
-		}
-		setPlacement(key, placementReducer(runtime.snapshot, event, definition.format));
-	}
-
-	/**
-	 * The single gate evaluation (FR-140).
-	 *
-	 * Assembles the three inputs and defers the precedence entirely to
-	 * `evaluateGates`. Nothing in this file compares gate state itself — the
-	 * whole point of FR-140 is that the order is a decision made once, not four
-	 * `if` chains that happen to agree today.
-	 *
-	 * Note the order differs from 0.1.0's, which checked `enabled` before
-	 * availability. That was never observable in isolation, only when two gates
-	 * were closed at once, and the case it changes — disabled on an unsupported
-	 * platform, previously decided by whichever transition arrived last — is the
-	 * incidental ordering FR-140a exists to fix.
-	 */
-	function currentGate(): GateDecision {
-		return evaluateGates({
-			available: engine.isAvailable()
-				? { ok: true }
-				: { ok: false, reason: 'unsupported_platform' },
-			enablement,
-			appGate: (() => {
-				const gate = evaluateGate(currentPrivacy);
-				return gate.allowed
-					? ({ permitted: true } as const)
-					: ({ permitted: false, reason: gate.reason } as const);
-			})(),
-			consentGate: consentGateInput(),
-		});
-	}
-
-	/** Maps a closed gate onto the refusal shape load, show, and the banner share. */
-	function refusalFor(
-		decision: Extract<GateDecision, { allowed: false }>,
-	): Extract<LoadResult, { status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }> {
-		switch (decision.kind) {
-			case 'unavailable':
-				return { status: 'unavailable', reason: decision.reason };
-			case 'disabled':
-				return { status: 'disabled' };
-			case 'undecided':
-				return { status: 'undecided' };
-			default:
-				return { status: 'blocked', reason: decision.reason };
-		}
-	}
+	// Throws on a structural fault or the FR-012 fail-closed case, before
+	// anything else exists.
+	const context = createInstanceContext(config, options, defaultEngine);
+	const { state, engine, resolved, events } = context;
 
-	/** Every refusal that applies before a placement is even looked up. */
-	function gateCheck():
-		| { readonly ok: true }
-		| {
-				readonly ok: false;
-				readonly result: Extract<
-					LoadResult,
-					{ status: 'disabled' | 'undecided' | 'blocked' | 'unavailable' }
-				>;
-		  } {
-		const decision = currentGate();
-		if (decision.allowed) {
-			return { ok: true };
-		}
-		return { ok: false, result: refusalFor(decision) };
-	}
-
-	function emitRefusal(
-		operation: 'initialize' | 'load' | 'show',
-		result: { readonly status: string; readonly reason?: string },
-		placementKey?: string,
-		format?: AdFormat,
-	): void {
-		if (result.status === 'disabled' || result.status === 'undecided') {
-			// `undecided` reuses the `disabled` event rather than minting a new
-			// one: for an observer of the event stream the fact is the same — no
-			// request was made — and the distinction that matters is carried by
-			// the typed result and the init status, where the app reads it.
-			events.emit({ type: 'disabled', timestamp: now(), operation, placementKey, format });
-		} else if (result.status === 'unavailable' || result.status === 'blocked') {
-			events.emit({
-				type: 'unavailable',
-				timestamp: now(),
-				operation,
-				placementKey,
-				format,
-				reason: (result.reason ?? 'unsupported_platform') as UnavailableReason | PrivacyBlockReason,
-			});
-		}
-	}
-
-	/**
-	 * Consumes a throttle slot for a placement, or reports the refusal (FR-140).
-	 *
-	 * Returns `null` when the request may proceed, so the two call sites read as a
-	 * guard clause. On refusal it moves the placement to `throttled` and emits,
-	 * which is what makes the refusal observable rather than a silent absence of
-	 * ads — the app would otherwise have no way to tell this from no-fill.
-	 *
-	 * A placement still holding a `ready` ad keeps that state: the refusal is
-	 * about asking again, and overwriting it would strand an ad that was already
-	 * paid for and is still showable.
-	 */
-	function reportThrottled(
-		key: string,
-		format: AdFormat,
-		retryAfterMs: number,
-		minRequestIntervalMs: number,
-	): LoadResult {
-		const runtime = placements.get(key);
-		if (runtime && runtime.snapshot.state !== 'ready') {
-			setPlacement(key, { ...runtime.snapshot, state: 'throttled' });
-		}
-		events.emit({
-			type: 'request_throttled',
-			timestamp: now(),
-			placementKey: key,
-			format,
-			retryAfterMs,
-			minRequestIntervalMs,
-		});
-		return { status: 'throttled', retryAfterMs };
-	}
-
-	/** Consumes a slot, or reports the refusal. `null` means proceed. */
-	function checkThrottle(key: string, format: AdFormat, token?: string): LoadResult | null {
-		const minRequestIntervalMs = resolved.minRequestIntervalByKey.get(key) ?? 0;
-		const decision = requestThrottle.tryAcquire(key, minRequestIntervalMs, token);
-		return decision.allowed
-			? null
-			: reportThrottled(key, format, decision.retryAfterMs, minRequestIntervalMs);
-	}
-
-	function warnSubstitutionOnce(): void {
-		if (warnedSubstitution || resolved.catalog.substitutedKeys.length === 0) {
-			return;
-		}
-		warnedSubstitution = true;
-		events.emit({
-			type: 'config_warning',
-			timestamp: now(),
-			warning: 'test_ad_unit_substituted',
-			placementKeys: resolved.catalog.substitutedKeys,
-		});
-	}
-
-	function releasePlacementResources(key: string): void {
-		const runtime = placements.get(key);
-		if (!runtime) {
-			return;
-		}
-		runtime.cancelLoadTimer?.();
-		runtime.cancelLoadTimer = null;
-		runtime.cancelShowTimer?.();
-		runtime.cancelShowTimer = null;
-		runtime.unsubscribeEngine?.();
-		runtime.unsubscribeEngine = null;
-		if (runtime.handle) {
-			engine.dispose(runtime.handle);
-			runtime.handle = null;
-		}
-		runtime.inFlightLoad = null;
-		runtime.abortLoad = null;
-		runtime.rewarded = null;
-		runtime.cancelRetry?.();
-		runtime.cancelRetry = null;
-	}
-
-	/**
-	 * Stops every request a gate that just closed forbids (FR-125, FR-153,
-	 * FR-159) — ads turned off, turned undecided, or consent withdrawn.
-	 *
-	 * In-flight loads are abandoned and their resources released, a loaded ad
-	 * that may no longer be shown is released with them, and an ad already on
-	 * screen is left alone — the provider offers no safe way to close it.
-	 *
-	 * An abandoned load *settles*: its caller gets `refusal`, the same answer a
-	 * load started now would get. Until 0.4.0 disabling released the resources
-	 * but never resolved the caller's promise, so an app awaiting `load()` across
-	 * a purchase of ad removal waited forever — and a handle the provider handed
-	 * back after the disable was adopted and went on loading.
-	 */
-	function haltPlacements(refusal: LoadRefusal): void {
-		for (const [key, runtime] of placements) {
-			if (runtime.snapshot.state === 'showing') {
-				continue;
-			}
-			const abort = runtime.abortLoad;
-			releasePlacementResources(key);
-			dispatchPlacement(key, { type: 'RESET' });
-			if (abort) {
-				emitRefusal('load', refusal, key, resolved.placements.get(key)?.format);
-				abort(refusal);
-			}
-		}
-	}
-
-	/** App-open expires on its own, shorter window (FR-130). */
-	function validityFor(format: AdFormat): number {
-		return format === 'app_open' ? resolved.timeouts.appOpenValidity : resolved.timeouts.adValidity;
-	}
-
-	async function doInitialize(privacy: PrivacyOptions): Promise<InitResult> {
-		const enginePrivacy = toEnginePrivacy(privacy, resolved.testDeviceIds);
-		try {
-			// The adapter applies privacy configuration before initializing the
-			// provider; that ordering is the whole reason FR-017 is enforceable.
-			await engine.initialize(enginePrivacy);
-			// Recorded before the status moves, and whether or not it moves: a gate
-			// that closed while this was in flight leaves the status `blocked`, but
-			// the provider is initialized all the same and must not be again.
-			providerInitialized = true;
-			appliedPrivacy = privacy;
-			setInit(initReducer(init, { type: 'SUCCEED' }));
-			warnSubstitutionOnce();
-			return { status: 'ready' };
-		} catch (error) {
-			const normalized = normalizeProviderError(error, { operation: 'initialize' });
-			setInit(initReducer(init, { type: 'FAIL', error: normalized }));
-			return { status: 'failed', error: normalized };
-		} finally {
-			inFlightInit = null;
-		}
-	}
-
-	function handleEngineEvent(
-		key: string,
-		definition: PlacementDefinition,
-		event: EngineAdEvent,
-	): void {
-		// After dispose nothing is honored: a late provider callback must not
-		// update a consumer that has gone away (FR-035, SC-008).
-		if (disposed) {
-			return;
-		}
-		const runtime = placements.get(key);
-		if (!runtime) {
-			return;
-		}
-		const correlationId = runtime.correlationId ?? undefined;
-		const base = { timestamp: now(), placementKey: key, format: definition.format, correlationId };
-
-		switch (event.type) {
-			case 'opened': {
-				// The provider confirming an ad is on screen is what arms
-				// ad-originated return detection (FR-128). Taken from here rather
-				// than from the app's background report, which arrives too late to
-				// be trusted — see core/adOriginatedReturn.ts.
-				if (isFullScreenFormat(definition.format)) {
-					adReturn.noteFullScreenShown(now());
-				}
-				events.emit({ ...base, type: 'display_started' });
-				// R5: the provider exposes no impression callback for full-screen
-				// formats, so this one is derived from the ad opening. Labelled
-				// honestly rather than passed off as the provider's own.
-				events.emit({ ...base, type: 'impression', source: 'derived' as ImpressionSource });
-				break;
-			}
-			case 'clicked':
-				// Recorded so that a background transition moments later is
-				// recognized as "the ad opened a browser" — the only signal the
-				// provider gives for that case (FR-128).
-				adReturn.noteClick(now());
-				events.emit({ ...base, type: 'click' });
-				break;
-			case 'rewarded': {
-				const first = runtime.rewarded?.confirmReward(event.reward) ?? null;
-				if (first) {
-					events.emit({ ...base, type: 'reward_earned', reward: first });
-				}
-				break;
-			}
-			case 'dismissed': {
-				const rewardedFirst = runtime.rewarded ? runtime.rewarded.dismiss() : true;
-				if (runtime.dismissed || !rewardedFirst) {
-					break;
-				}
-				runtime.dismissed = true;
-				lock.release(key);
-				runtime.cancelShowTimer?.();
-				runtime.cancelShowTimer = null;
-				events.emit({
-					...base,
-					type: 'dismissed',
-					rewardEarned: runtime.rewarded ? runtime.rewarded.rewardEarned : undefined,
-				});
-				dispatchPlacement(key, { type: 'DISMISSED' });
-				// Deliberately NOT released here. FR-049 requires the reward and
-				// the dismissal to be handled in either order, and a provider that
-				// confirms the reward *after* closing the ad would otherwise have
-				// its confirmation dropped by a torn-down listener — silently
-				// costing the user a reward they earned.
-				//
-				// This is a retained resource, not a leak: at most one handle and
-				// one listener per placement, released deterministically by the
-				// next load of that placement or by dispose().
-				break;
-			}
-			case 'failed': {
-				const normalized = normalizeProviderError(event.cause, {
-					operation: 'show',
-					placementKey: key,
-					format: definition.format,
-				});
-				lock.release(key);
-				events.emit({ ...base, type: 'display_failed', error: normalized });
-				dispatchPlacement(key, { type: 'SHOW_FAILED', error: normalized });
-				releasePlacementResources(key);
-				break;
-			}
-			default:
-				break;
-		}
-	}
-
-	function loadFullScreen(
-		key: string,
-		definition: PlacementDefinition,
-		adUnitId: string,
-		correlationId: string,
-	): Promise<LoadResult> {
-		const runtime = placements.get(key)!;
-		const format = definition.format as FullScreenFormat;
-		const startedAt = now();
-
-		return new Promise<LoadResult>(resolve => {
-			let settled = false;
-
-			const finish = (result: LoadResult) => {
-				if (settled) {
-					return;
-				}
-				settled = true;
-				runtime.cancelLoadTimer?.();
-				runtime.cancelLoadTimer = null;
-				runtime.inFlightLoad = null;
-				if (runtime.abortLoad === finish) {
-					runtime.abortLoad = null;
-				}
-				resolve(result);
-			};
-			// `settled` is what makes this safe: a handle the provider hands back
-			// after an abort is disposed by the `.then` below instead of adopted.
-			runtime.abortLoad = finish;
-
-			runtime.cancelLoadTimer = timers.after(resolved.timeouts.load, () => {
-				const error = new AdsError('load_timeout', {
-					operation: 'load',
-					placementKey: key,
-					format,
-					message: `load timed out after ${resolved.timeouts.load}ms`,
-				});
-				events.emit({
-					type: 'load_failed',
-					timestamp: now(),
-					placementKey: key,
-					format,
-					correlationId,
-					error,
-				});
-				dispatchPlacement(key, { type: 'LOAD_FAILED', error });
-				releasePlacementResources(key);
-				finish({ status: 'timeout' });
-			});
-
-			engine
-				.createFullScreen(format, adUnitId, toEngineRequest(currentPrivacy))
-				.then(handle => {
-					if (disposed || settled) {
-						engine.dispose(handle);
-						return;
-					}
-					runtime.handle = handle;
-					runtime.unsubscribeEngine = engine.subscribe(handle, event => {
-						if (event.type === 'loaded') {
-							dispatchPlacement(key, { type: 'LOADED', atMs: now() });
-							events.emit({
-								type: 'loaded',
-								timestamp: now(),
-								placementKey: key,
-								format,
-								correlationId,
-								durationMs: now() - startedAt,
-							});
-							finish({ status: 'loaded', correlationId });
-							return;
-						}
-						if (event.type === 'failed') {
-							const normalized = normalizeProviderError(event.cause, {
-								operation: 'load',
-								placementKey: key,
-								format,
-							});
-							events.emit({
-								type: 'load_failed',
-								timestamp: now(),
-								placementKey: key,
-								format,
-								correlationId,
-								error: normalized,
-							});
-							dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
-							releasePlacementResources(key);
-							finish(
-								normalized.code === 'no_fill'
-									? { status: 'no_fill' }
-									: { status: 'failed', error: normalized },
-							);
-							return;
-						}
-						handleEngineEvent(key, definition, event);
-					});
-				})
-				.catch(error => {
-					const normalized = normalizeProviderError(error, {
-						operation: 'load',
-						placementKey: key,
-						format,
-					});
-					events.emit({
-						type: 'load_failed',
-						timestamp: now(),
-						placementKey: key,
-						format,
-						correlationId,
-						error: normalized,
-					});
-					dispatchPlacement(key, { type: 'LOAD_FAILED', error: normalized });
-					finish(
-						normalized.code === 'no_fill'
-							? { status: 'no_fill' }
-							: { status: 'failed', error: normalized },
-					);
-				});
-		});
-	}
-
-	/**
-	 * One load, plus however many bounded retries the policy allows (FR-134).
-	 *
-	 * Off unless configured, so an upgraded 0.1.0 consumer goes through here once
-	 * and issues exactly the requests it always did. When on, only errors already
-	 * flagged `retryable` are retried — a configuration or consent failure is a
-	 * state another attempt cannot change, and retrying it would spend a billable
-	 * request on a certainty (FR-135).
-	 *
-	 * Every attempt is emitted before it is waited on, carrying the cycle's
-	 * correlation id, so the event stream can be reconciled against a bill
-	 * without inferring anything (FR-138).
-	 */
-	async function loadWithRetry(
-		key: string,
-		definition: PlacementDefinition,
-		adUnitId: string,
-		correlationId: string,
-	): Promise<LoadResult> {
-		const runtime = placements.get(key)!;
-		const policy = resolved.retryByKey.get(key) ?? null;
-
-		for (;;) {
-			const result = await loadFullScreen(key, definition, adUnitId, correlationId);
-			if (result.status === 'loaded' || disposed) {
-				return result;
-			}
-
-			const error =
-				result.status === 'failed'
-					? result.error
-					: result.status === 'no_fill'
-						? new AdsError('no_fill', { operation: 'load', placementKey: key })
-						: result.status === 'timeout'
-							? new AdsError('load_timeout', { operation: 'load', placementKey: key })
-							: null;
-
-			// A refusal — disabled, undecided, blocked, unavailable — is not a
-			// failure to retry. Nothing was requested, and nothing about asking
-			// again would change that.
-			if (!error || !error.retryable) {
-				return result;
-			}
-			// The whole gate, not just enablement: a retry is a new provider request
-			// and needs the same permission the first one had (FR-017).
-			if (!canRetry(policy, runtime.retryAttempts) || !currentGate().allowed) {
-				return result;
-			}
-
-			runtime.retryAttempts += 1;
-			const delayMs = delayForAttempt(policy!, runtime.retryAttempts);
-			events.emit({
-				type: 'retry_scheduled',
-				timestamp: now(),
-				placementKey: key,
-				format: definition.format,
-				correlationId,
-				attempt: runtime.retryAttempts,
-				delayMs,
-				error,
-			});
-
-			const waited = await new Promise<boolean>(resolve => {
-				runtime.cancelRetry = timers.after(delayMs, () => {
-					runtime.cancelRetry = null;
-					resolve(true);
-				});
-				const cancel = runtime.cancelRetry;
-				// Cancellation replaces the handle, so a disable or dispose that
-				// clears it resolves this wait as "do not continue" rather than
-				// leaving a promise nobody will settle.
-				runtime.cancelRetry = () => {
-					cancel?.();
-					runtime.cancelRetry = null;
-					resolve(false);
-				};
-			});
-
-			if (!waited || disposed || !currentGate().allowed) {
-				return result;
-			}
-
-			dispatchPlacement(key, { type: 'LOAD' });
-		}
-	}
-
-	/**
-	 * Applies a consent outcome to the gate without a second initialization.
-	 *
-	 * This is FR-105's "the app does not wire it by hand" in one function. When
-	 * consent opens the gate and the instance was blocked, it initializes — and
-	 * because `initialize` is idempotent and shares one in-flight operation, the
-	 * total native initialization count across a whole consent flow stays at one
-	 * (FR-022, SC-102). When consent closes the gate, requests stop and every
-	 * pending retry is cancelled with them (FR-137).
-	 *
-	 * Since 0.4.0 a closed gate also moves a `ready` instance to `blocked` and
-	 * abandons in-flight loads (FR-153). 0.3.0 left the status at `ready`, which
-	 * was harmless while the only consent outcome that could close the gate ran
-	 * before anything was loaded. The privacy options form changes that: a user
-	 * can withdraw consent with a banner mounted, and a banner host keyed on
-	 * `ready` would otherwise keep requesting. Re-granting resumes through
-	 * `initialize`, which knows the provider is already up and does not touch it
-	 * again (FR-154).
-	 */
-	async function reevaluateAfterConsent(): Promise<void> {
-		if (disposed || !currentPrivacy) {
-			return;
-		}
-		const decision = currentGate();
-		if (!decision.allowed) {
-			cancelAllRetries();
-			if (decision.kind === 'blocked') {
-				haltPlacements({ status: 'blocked', reason: decision.reason });
-				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
-			}
-			return;
-		}
-		if (init.status === 'ready' || init.status === 'initializing') {
-			return;
-		}
-		await instance.initialize(currentPrivacy);
-	}
-
-	/**
-	 * Answers `initialize` without a native call when the provider is already up
-	 * (FR-022, FR-154), or returns `null` to let a real initialization proceed.
-	 *
-	 * The status leaves `ready` when a gate closes, but nothing is torn down, so
-	 * the gate reopening resumes. Init-time-only flags that changed in the
-	 * meantime fall through to a real initialization: it is the only way they can
-	 * take effect, and it is what 0.3.0 did.
-	 *
-	 * Only reached once the caller has passed the whole gate, consent flow
-	 * included, so an app that re-runs `initialize` on a consent change cannot
-	 * reopen what the user just closed.
-	 */
-	function resumeInitialized(privacy: PrivacyOptions): InitResult | null {
-		if (
-			!providerInitialized ||
-			!canStart(init.status) ||
-			requiresReinitialization(appliedPrivacy, privacy)
-		) {
-			return null;
-		}
-		setInit(initReducer(init, { type: 'RESUME' }));
-		return { status: 'ready' };
-	}
+	const init = createInitController(context);
+	const loader = createLoader(context);
+	const shower = createShower(context);
 
 	const instance: AdsInstance = {
-		async initialize(privacy) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-			currentPrivacy = privacy;
-
-			// Availability first, then enablement, then consent — the one order,
-			// evaluated in the one place (FR-140).
-			const decision = currentGate();
-			if (!decision.allowed && decision.kind === 'unavailable') {
-				setInit(initReducer(init, { type: 'UNAVAILABLE', reason: decision.reason }));
-				const result = { status: 'unavailable', reason: decision.reason } as const;
-				emitRefusal('initialize', result);
-				return result;
-			}
-			if (!decision.allowed && decision.kind === 'disabled') {
-				setInit(initReducer(init, { type: 'DISABLE' }));
-				const result = { status: 'disabled' } as const;
-				emitRefusal('initialize', result);
-				return result;
-			}
-			if (!decision.allowed && decision.kind === 'undecided') {
-				// FR-115. Nothing provider-facing happens, exactly as when
-				// disabled — but the status the app observes says `undecided`, so
-				// a banner host can hold its space instead of reclaiming it.
-				setInit(initReducer(init, { type: 'UNDECIDE' }));
-				armUndecidedWarning();
-				const result = { status: 'undecided' } as const;
-				emitRefusal('initialize', result);
-				return result;
-			}
-
-			if (!decision.allowed && decision.kind === 'blocked') {
-				// FR-017, FR-158. Nothing provider-facing happens here at all — not a
-				// configuration call, not an initialization. The engine is untouched.
-				//
-				// `decision` is the full gate: the app's own input *and*, once the app
-				// has opted into it, the package's consent flow. Until 0.4.0 this
-				// checked the app's input alone, so a user who declined the consent
-				// form still got a natively initialized SDK — `load` refused, but the
-				// provider was up, which is exactly what the provider's own guidance
-				// says not to do before `canRequestAds`. The consent flow opening the
-				// gate later initializes it, through `reevaluateAfterConsent`.
-				setInit(initReducer(init, { type: 'BLOCK', reason: decision.reason }));
-				const result = { status: 'blocked', reason: decision.reason } as const;
-				emitRefusal('initialize', result);
-				return result;
-			}
-
-			if (init.status === 'ready') {
-				return { status: 'ready' };
-			}
-
-			const resumed = resumeInitialized(privacy);
-			if (resumed) {
-				return resumed;
-			}
-
-			// FR-022, SC-005. Racing callers share one operation, so the provider
-			// initializes exactly once however many arrive.
-			if (inFlightInit) {
-				return inFlightInit;
-			}
-			if (!canStart(init.status)) {
-				return { status: 'ready' };
-			}
+		initialize: privacy => init.initialize(privacy),
+		updatePrivacy: privacy => init.updatePrivacy(privacy),
+		setEnabled: enabled => init.setEnablement(enabled ? 'enabled' : 'disabled'),
+		setEnablement: next => init.setEnablement(next),
+		setAppActive: active => shower.setAppActive(active),
+		consent: createConsentApi(context, () => init.reevaluateAfterConsent()),
 
-			setInit(initReducer(init, { type: 'START' }));
-			inFlightInit = doInitialize(privacy);
-			return inFlightInit;
-		},
-
-		async updatePrivacy(privacy) {
-			if (disposed) {
-				// The same answer initialize and load give a disposed instance.
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-			if (enablement === 'undecided') {
-				return { status: 'undecided' };
-			}
-			if (enablement === 'disabled') {
-				return { status: 'disabled' };
-			}
-			if (!engine.isAvailable()) {
-				return { status: 'unavailable', reason: 'unsupported_platform' };
-			}
-
-			// FR-020: a flag the provider only honors at initialization cannot be
-			// applied now. Say so, rather than accepting it and running half-old.
-			if (requiresReinitialization(appliedPrivacy, privacy)) {
-				return { status: 'requires_reinitialization' };
-			}
-
-			currentPrivacy = privacy;
-			const gate = evaluateGate(privacy);
-			if (!gate.allowed) {
-				// FR-017, FR-137, FR-153: the same teardown as a consent outcome that
-				// closes the gate. Without it a retry already waiting on its backoff
-				// would still reach the provider after the app withdrew consent.
-				cancelAllRetries();
-				haltPlacements({ status: 'blocked', reason: gate.reason });
-				setInit(initReducer(init, { type: 'BLOCK', reason: gate.reason }));
-				return { status: 'blocked', reason: gate.reason };
-			}
-
-			// FR-019: resolving consent after a block must not produce a second
-			// native initialization.
-			if (init.status === 'ready') {
-				return { status: 'applied' };
-			}
-			// Exhaustive on purpose (ADS-04): the old ternary mapped only `ready` and
-			// `blocked`, and every other outcome — `failed` included — fell through to
-			// `applied`. A new InitResult member now fails to compile here.
-			const result = await instance.initialize(privacy);
-			switch (result.status) {
-				case 'ready':
-					return { status: 'applied' };
-				case 'blocked':
-				case 'disabled':
-				case 'undecided':
-				case 'unavailable':
-				case 'failed':
-					return result;
-				default: {
-					const unreachable: never = result;
-					return unreachable;
-				}
-			}
-		},
+		getStatus: () => state.init.status,
+		subscribeStatus: listener => context.statusListeners.add(listener),
 
-		setEnabled(next) {
-			return instance.setEnablement(next ? 'enabled' : 'disabled');
-		},
-
-		setEnablement(next) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-			if (enablement === next) {
-				return { status: 'unchanged' };
-			}
-
-			const previous = enablement;
-			enablement = next;
-
-			if (next === 'disabled' || next === 'undecided') {
-				// FR-037 and FR-125: new work is prevented and in-flight resources
-				// released deterministically, and moving to `undecided` from
-				// `enabled` follows the same rules as disabling. An ad already on
-				// screen is left alone — the provider offers no safe way to close
-				// it, and yanking it would be worse than letting it finish.
-				cancelAllRetries();
-				haltPlacements(next === 'disabled' ? { status: 'disabled' } : { status: 'undecided' });
-				setInit(initReducer(init, { type: next === 'disabled' ? 'DISABLE' : 'UNDECIDE' }));
-				if (next === 'undecided') {
-					armUndecidedWarning();
-					return { status: 'undecided' };
-				}
-				disarmUndecidedWarning();
-				return { status: 'disabled' };
-			}
-
-			// Turning ads on. This is the path 0.1.0 got wrong: it dropped the
-			// status to `not_started` and returned nothing, so an app whose user
-			// lost their entitlement turned ads back on and then had every load
-			// silently refused (FR-121).
-			disarmUndecidedWarning();
-			const resumable = canResume(init.resumeTo);
-			setInit(initReducer(init, { type: 'ENABLE' }));
-
-			if (init.status === 'unavailable') {
-				return { status: 'unavailable', reason: init.unavailableReason ?? 'unsupported_platform' };
-			}
-			if (resumable && init.status === 'ready') {
-				// The provider was never un-initialized, so there is genuinely
-				// nothing to redo — and FR-022 forbids initializing it twice.
-				return { status: 'resumed', initStatus: init.status };
-			}
-			if (previous === 'undecided' && init.status === 'ready') {
-				return { status: 'resumed', initStatus: init.status };
-			}
-			// Said out loud rather than left for the app to discover from a
-			// refused load. The package will not initialize implicitly: that would
-			// hide an asynchronous, billable operation behind a setter the caller
-			// may not be awaiting.
-			return { status: 'requires_initialization' };
-		},
-
-		setAppActive(active) {
-			if (disposed) {
-				return;
-			}
-			appActive = active;
-			if (!active) {
-				// Arming happens when the provider reports an ad opened, not here:
-				// this event can be delivered late enough that the ad is already
-				// gone. All this adds is the browser case, where a background
-				// closely follows a click (FR-128).
-				adReturn.noteBackground(now());
-				return;
-			}
-			adReturn.noteForeground(now());
-			// FR-034: on return to the foreground, re-evaluate what was loaded.
-			// An ad that went stale while the app was away must stop reporting
-			// `ready` before the app offers a button that would fail on tap.
-			const current = now();
-			for (const [key, runtime] of placements) {
-				const definition = resolved.placements.get(key);
-				if (
-					runtime.snapshot.state === 'ready' &&
-					runtime.snapshot.loadedAtMs !== null &&
-					definition !== undefined &&
-					isStale(runtime.snapshot.loadedAtMs, current, validityFor(definition.format))
-				) {
-					releasePlacementResources(key);
-					dispatchPlacement(key, { type: 'EXPIRE' });
-				}
-			}
-		},
-
-		getStatus() {
-			return init.status;
-		},
-
-		subscribeStatus: listener => statusListeners.add(listener),
-
-		async load(placementKey) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-
-			const definition = resolved.placements.get(placementKey);
-			if (!definition) {
-				return {
-					status: 'failed',
-					error: new AdsError('placement_not_found', {
-						operation: 'load',
-						placementKey,
-						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
-					}),
-				};
-			}
-
-			const gate = gateCheck();
-			if (!gate.ok) {
-				emitRefusal('load', gate.result, placementKey, definition.format);
-				return gate.result;
-			}
-
-			if (!canRequest(init.status)) {
-				return {
-					status: 'failed',
-					error: new AdsError('not_ready', {
-						operation: 'load',
-						placementKey,
-						format: definition.format,
-						message: 'initialize() must complete before loading',
-					}),
-				};
-			}
-
-			if (definition.format === 'banner') {
-				return {
-					status: 'failed',
-					error: new AdsError('format_mismatch', {
-						operation: 'load',
-						placementKey,
-						format: definition.format,
-						message: `"${placementKey}" is a banner; banners render through <AdsBanner> rather than load()`,
-					}),
-				};
-			}
-
-			const runtime = placements.get(placementKey)!;
-
-			// FR-029, SC-002's sibling guarantee: a repeat load while one is in
-			// flight joins it instead of creating a second provider request.
-			if (runtime.inFlightLoad) {
-				return runtime.inFlightLoad;
-			}
-
-			if (runtime.snapshot.state === 'showing') {
-				return {
-					status: 'failed',
-					error: new AdsError('busy', { operation: 'load', placementKey }),
-				};
-			}
-
-			if (!canLoad(runtime.snapshot.state)) {
-				return {
-					status: 'failed',
-					error: new AdsError('not_ready', { operation: 'load', placementKey }),
-				};
-			}
-
-			// FR-140. Checked after the in-flight join so a caller that merely
-			// arrived twice for one cycle is answered by the join, not charged a
-			// throttle slot; after the busy and not-ready guards so a load that was
-			// never going to request anything does not spend one either; and before
-			// the correlation id and `load_started`, because a refused request is
-			// not a cycle and must not look like one in the event stream.
-			const throttled = checkThrottle(placementKey, definition.format);
-			if (throttled) {
-				return throttled;
-			}
-
-			releasePlacementResources(placementKey);
-
-			const correlationId = correlation.next();
-			runtime.correlationId = correlationId;
-			runtime.dismissed = false;
-			dispatchPlacement(placementKey, { type: 'LOAD' });
-			setPlacement(placementKey, { ...runtime.snapshot, correlationId });
-			events.emit({
-				type: 'load_started',
-				timestamp: now(),
-				placementKey,
-				format: definition.format,
-				correlationId,
-			});
-
-			const adUnitId = resolved.catalog.byKey.get(placementKey)!;
-			runtime.retryAttempts = 0;
-			const promise = loadWithRetry(placementKey, definition, adUnitId, correlationId);
-			runtime.inFlightLoad = promise;
-			return promise;
-		},
-
-		async show(placementKey) {
-			if (disposed) {
-				return { status: 'unavailable', reason: 'provider_missing' };
-			}
-
-			const definition = resolved.placements.get(placementKey);
-			if (!definition) {
-				return {
-					status: 'failed',
-					error: new AdsError('placement_not_found', {
-						operation: 'show',
-						placementKey,
-						message: `unknown placement "${placementKey}"; configured keys are ${[...resolved.placements.keys()].join(', ')}`,
-					}),
-				};
-			}
-
-			if (!isFullScreenFormat(definition.format)) {
-				return {
-					status: 'failed',
-					error: new AdsError('format_mismatch', {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-						message: `"${placementKey}" is a banner; banners are rendered, not shown`,
-					}),
-				};
-			}
-
-			const gate = gateCheck();
-			if (!gate.ok) {
-				emitRefusal('show', gate.result, placementKey, definition.format);
-				return gate.result;
-			}
-
-			// FR-028: never open an ad while the app is not in front of the user.
-			if (!appActive) {
-				return { status: 'app_inactive' };
-			}
-
-			// FR-128. Only app-open is refused: the user just came back from an ad
-			// or from a browser an ad opened, and app-open is the format that
-			// would fire on exactly that return. An interstitial at the same
-			// moment is the app's own deliberate choice, made somewhere the
-			// package cannot see, so refusing it would be policy rather than
-			// capability.
-			if (definition.format === 'app_open' && adReturn.isRefusing(now())) {
-				return { status: 'ad_originated_return' };
-			}
-
-			const runtime = placements.get(placementKey)!;
-
-			if (runtime.snapshot.state === 'consumed') {
-				return { status: 'consumed' };
-			}
-
-			// FR-034: a stale ad is not shown and is not reported ready.
-			if (
-				runtime.snapshot.state === 'ready' &&
-				runtime.snapshot.loadedAtMs !== null &&
-				isStale(runtime.snapshot.loadedAtMs, now(), validityFor(definition.format))
-			) {
-				releasePlacementResources(placementKey);
-				dispatchPlacement(placementKey, { type: 'EXPIRE' });
-				return { status: 'not_ready' };
-			}
-
-			if (runtime.snapshot.state !== 'ready' || !runtime.handle) {
-				return { status: 'not_ready' };
-			}
-
-			// FR-030. Acquired before anything else can open a screen, and never
-			// queued: a refused show is refused now, not deferred to a moment the
-			// app never chose.
-			if (!lock.acquire(placementKey)) {
-				return { status: 'busy' };
-			}
-
-			const correlationId = runtime.correlationId ?? correlation.next();
-			runtime.rewarded = definition.format === 'rewarded' ? createRewardedSession() : null;
-			dispatchPlacement(placementKey, { type: 'SHOW' });
-
-			let settled = false;
-			const showTimeout = new Promise<ShowResult>(resolve => {
-				runtime.cancelShowTimer = timers.after(resolved.timeouts.show, () => {
-					if (settled) {
-						return;
-					}
-					settled = true;
-					const error = new AdsError('show_timeout', {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-						message: `show timed out after ${resolved.timeouts.show}ms`,
-					});
-					lock.release(placementKey);
-					events.emit({
-						type: 'display_failed',
-						timestamp: now(),
-						placementKey,
-						format: definition.format,
-						correlationId,
-						error,
-					});
-					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error });
-					releasePlacementResources(placementKey);
-					resolve({ status: 'timeout' });
-				});
-			});
-
-			const attempt = engine
-				.show(runtime.handle)
-				.then<ShowResult>(() => {
-					settled = true;
-					runtime.cancelShowTimer?.();
-					runtime.cancelShowTimer = null;
-					return { status: 'shown', correlationId };
-				})
-				.catch<ShowResult>(error => {
-					settled = true;
-					runtime.cancelShowTimer?.();
-					runtime.cancelShowTimer = null;
-					const normalized = normalizeProviderError(error, {
-						operation: 'show',
-						placementKey,
-						format: definition.format,
-					});
-					lock.release(placementKey);
-					events.emit({
-						type: 'display_failed',
-						timestamp: now(),
-						placementKey,
-						format: definition.format,
-						correlationId,
-						error: normalized,
-					});
-					dispatchPlacement(placementKey, { type: 'SHOW_FAILED', error: normalized });
-					releasePlacementResources(placementKey);
-					return { status: 'failed', error: normalized };
-				});
-
-			return Promise.race([attempt, showTimeout]);
-		},
+		load: placementKey => loader.load(placementKey),
+		show: placementKey => shower.show(placementKey),
 
 		getPlacementState(placementKey) {
 			if (!resolved.placements.has(placementKey)) {
 				return 'unavailable';
 			}
-			if (!engine.isAvailable() || enablement === 'disabled') {
+			if (!engine.isAvailable() || state.enablement === 'disabled') {
 				return 'unavailable';
 			}
 			// Reported distinctly from `unavailable` so the app can choose to hold
-			// the banner's space rather than reclaim it. That choice is the entire
-			// reason the third state is worth having (FR-116).
-			if (enablement === 'undecided') {
+			// the banner's space rather than reclaim it (FR-116).
+			if (state.enablement === 'undecided') {
 				return 'undecided';
 			}
-			return placements.get(placementKey)?.snapshot.state ?? 'idle';
+			return context.placements.get(placementKey)?.snapshot.state ?? 'idle';
 		},
 
 		subscribePlacement(key, listener) {
-			const runtime = placements.get(key);
-			if (!runtime) {
-				return () => undefined;
-			}
-			return runtime.listeners.add(listener);
+			return context.placements.get(key)?.listeners.add(listener) ?? (() => undefined);
 		},
 
-		subscribeEvents(listener) {
-			return events.subscribe(listener);
-		},
+		subscribeEvents: listener => events.subscribe(listener),
 
-		getSubstitutedPlacements() {
-			return resolved.catalog.substitutedKeys;
-		},
-
-		getIgnoredConsentTools() {
-			return resolved.ignoredConsentTools;
-		},
-
-		consent: {
-			async requestInfoUpdate() {
-				if (disposed) {
-					return consent;
-				}
-				// Marks the flow as in use. Until this is called the gate sees no
-				// consent input at all, which is how an app that supplies its own
-				// gate keeps 0.1.0 behavior without opting out of anything
-				// (FR-102).
-				consentStarted = true;
-				if (resolved.consentTesting?.resetOnStart) {
-					try {
-						engine.consent.reset();
-					} catch {
-						// A reset that fails must not abort the update; the flow
-						// continues against whatever state is stored.
-					}
-				}
-				const next = await runConsentStep(
-					() =>
-						engine.consent.requestInfoUpdate(
-							buildConsentOptions(
-								resolved.consentTesting,
-								currentPrivacy?.underAgeOfConsent,
-								resolved.testDeviceIds,
-							),
-						),
-					'consent information update failed',
-				);
-				if (disposed) {
-					return consent;
-				}
-				setConsent(next);
-				await reevaluateAfterConsent();
-				return next;
-			},
-
-			async showFormIfRequired() {
-				if (disposed) {
-					return consent;
-				}
-				consentStarted = true;
-				if (!needsForm(consent) || privacyOptionsFormOpen) {
-					// Nothing to present. Not an error: a region that does not
-					// require consent is the normal case, and showing a form there
-					// is exactly what FR-107 forbids the package from deciding.
-					// Nor is a privacy options form already on screen — one
-					// provider form at a time.
-					return consent;
-				}
-				consentFormsOpen += 1;
-				let next: ConsentSnapshot;
-				try {
-					next = await runConsentStep(
-						() => engine.consent.showFormIfRequired(),
-						'consent form failed',
-					);
-				} finally {
-					consentFormsOpen -= 1;
-				}
-				if (disposed) {
-					return consent;
-				}
-				setConsent(next);
-				await reevaluateAfterConsent();
-				return next;
-			},
-
-			async showPrivacyOptionsForm() {
-				// The refusals, most immovable first — the same reading order as
-				// the request gates, so the answer is the most useful one rather
-				// than the first one checked.
-				if (disposed) {
-					return { status: 'unavailable', reason: 'provider_missing' };
-				}
-				if (!engine.isAvailable()) {
-					return { status: 'unavailable', reason: 'unsupported_platform' };
-				}
-				if (privacyOptionsFormOpen || consentFormsOpen > 0) {
-					return { status: 'busy' };
-				}
-				if (consent.privacyOptionsRequirement === 'unknown') {
-					return { status: 'info_update_required' };
-				}
-				if (consent.privacyOptionsRequirement !== 'required') {
-					// The provider's verdict, not a region guess of ours (FR-150).
-					return { status: 'not_required' };
-				}
-
-				privacyOptionsFormOpen = true;
-				let next: ConsentSnapshot;
-				let failure: AdsError | null = null;
-				try {
-					next = normalizeConsent(await engine.consent.showPrivacyOptionsForm());
-				} catch (cause) {
-					failure = toConsentError(cause, 'privacy options form failed');
-					// The form did not complete, so the stored decision is the
-					// provider's to report — ask it rather than assume. Collapsing to
-					// `error` the way a failed first-time form does would revoke a
-					// consent the user never changed: that form runs while the gate is
-					// already closed, this one usually while it is open. If the
-					// provider cannot answer either, the gate closes; a failure is
-					// never consent (FR-106). Nothing is asked of a disposed instance.
-					next = disposed
-						? consent
-						: await runConsentStep(
-								() => engine.consent.getInfo(),
-								'consent information could not be read after the privacy options form failed',
-							);
-				} finally {
-					privacyOptionsFormOpen = false;
-				}
-				// dispose() during the form: the form is the provider's and stays
-				// until the user closes it, but its outcome reaches nobody (FR-157).
-				if (disposed) {
-					return { status: 'unavailable', reason: 'provider_missing' };
-				}
-				setConsent(next);
-				await reevaluateAfterConsent();
-				return failure ? { status: 'failed', error: failure } : { status: 'shown', consent: next };
-			},
-
-			getState() {
-				return consent;
-			},
-
-			subscribe: listener => consentListeners.add(listener),
-
-			async reset() {
-				if (disposed) {
-					return;
-				}
-				// Config validation already stripped the testing tools in
-				// production, so this is inert there without a check here (FR-113).
-				if (!resolved.consentTesting) {
-					return;
-				}
-				try {
-					engine.consent.reset();
-				} catch {
-					// Nothing to report: the stored state is the provider's, and a
-					// failed reset leaves it as it was.
-				}
-				setConsent(INITIAL_CONSENT);
-			},
-		},
-
-		internals: {
-			resolveBanner(placementKey) {
-				const definition = resolved.placements.get(placementKey);
-				if (!definition) {
-					return {
-						ok: false,
-						result: {
-							status: 'failed',
-							error: new AdsError('placement_not_found', {
-								operation: 'load',
-								placementKey,
-								message: `unknown placement "${placementKey}"`,
-							}),
-						},
-					};
-				}
-				if (definition.format !== 'banner') {
-					return {
-						ok: false,
-						result: {
-							status: 'failed',
-							error: new AdsError('format_mismatch', {
-								operation: 'load',
-								placementKey,
-								format: definition.format,
-								message: `"${placementKey}" is not a banner placement`,
-							}),
-						},
-					};
-				}
-				const gate = gateCheck();
-				if (!gate.ok) {
-					return { ok: false, result: gate.result };
-				}
-				if (!canRequest(init.status)) {
-					return { ok: false, result: { status: 'blocked', reason: 'consent_required' } };
-				}
-				// The throttle is deliberately **not** consulted here. It cannot be
-				// decided from configuration alone: a fresh mount must be throttled
-				// (that is the navigation burst the feature exists for) while a width
-				// re-adaptation of an already-mounted banner must not be (that is
-				// rotation, and refusing it would leave the user with no banner for a
-				// minute). Only the host knows which it is, so the host calls
-				// `commitBannerRequest` (FR-140).
-				return {
-					ok: true,
-					adUnitId: resolved.catalog.byKey.get(placementKey)!,
-					correlationId: correlation.next(),
-					personalizedAds: toEngineRequest(currentPrivacy).personalizedAds,
-				};
-			},
-			commitBannerRequest(placementKey, correlationId) {
-				if (!resolved.placements.has(placementKey)) {
-					return null;
-				}
-				const minRequestIntervalMs = resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
-				const decision = requestThrottle.tryAcquire(
-					placementKey,
-					minRequestIntervalMs,
-					correlationId,
-				);
-				// Deliberately silent: the host calls this during render, because the
-				// provider component requests as part of that same render and an effect
-				// would be too late to stop it. Emitting an event or setting placement
-				// state here would mean mutating during another component's render, so
-				// the refusal is only returned — the host reports it from its effect.
-				return decision.allowed
-					? null
-					: { status: 'throttled', retryAfterMs: decision.retryAfterMs };
-			},
-			throttleFloorFor(placementKey) {
-				return resolved.minRequestIntervalByKey.get(placementKey) ?? 0;
-			},
-			emit(event) {
-				events.emit(event);
-			},
-			setPlacementState(key, state) {
-				const runtime = placements.get(key);
-				if (runtime) {
-					setPlacement(key, { ...runtime.snapshot, state });
-				}
-			},
-			isReady() {
-				return permitsRequests(enablement) && engine.isAvailable() && canRequest(init.status);
-			},
-			nextCorrelationId() {
-				return correlation.next();
-			},
-			timerCount() {
-				return timers.size();
-			},
-		},
+		/** FR-011a — substitution is observable state, not only a log line. */
+		getSubstitutedPlacements: () => resolved.catalog.substitutedKeys,
+		/** FR-113 — the same treatment for consent tools dropped in production. */
+		getIgnoredConsentTools: () => resolved.ignoredConsentTools,
 
 		dispose() {
 			// FR-005: idempotent. A second call is a no-op, not an error.
-			if (disposed) {
+			if (state.disposed) {
 				return;
 			}
-			disposed = true;
-			cancelAllRetries();
-			disarmUndecidedWarning();
-			for (const [key, runtime] of placements) {
+			state.disposed = true;
+			cancelAllRetries(context);
+			disarmUndecidedWarning(context);
+			for (const [key, runtime] of context.placements) {
 				const abort = runtime.abortLoad;
-				releasePlacementResources(key);
+				context.releasePlacementResources(key);
 				runtime.listeners.clear();
 				// Settled rather than left hanging, with the answer a `load` after
-				// dispose gets (FR-159). No refusal event goes with it: nothing is
-				// emitted after dispose (FR-035).
+				// dispose gets (FR-159). No refusal event: nothing is emitted after
+				// dispose (FR-035).
 				abort?.({ status: 'unavailable', reason: 'provider_missing' });
 			}
-			timers.clearAll();
-			requestThrottle.clear();
-			lock.reset();
-			adReturn.reset();
-			statusListeners.clear();
-			consentListeners.clear();
+			context.timers.clearAll();
+			context.requestThrottle.clear();
+			context.lock.reset();
+			context.adReturn.reset();
+			context.statusListeners.clear();
+			context.consentListeners.clear();
 			events.dispose();
-			inFlightInit = null;
+			state.inFlightInit = null;
 		},
 	};
 
+	attachInternals(instance, createInternals(context));
 	return instance;
 }