@chipmobilesdk/rn-ads 0.6.0 → 0.8.0

package/lib/commonjs/engine/testAdUnits.js

@@ -0,0 +1,61 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isOfficialTestAdUnit = isOfficialTestAdUnit;
+exports.testAdUnitFor = testAdUnitFor;
+/**
+ * Google's official test ad units (FR-013).
+ *
+ * PRIVATE. Never exported from `src/index.ts`.
+ *
+ * FR-013 forbids the package from carrying production identifiers, credentials,
+ * or host-app rules, and explicitly permits official test identifiers provided
+ * they are documented as such — this file is that documentation.
+ *
+ * They are hard-coded rather than read from configuration on purpose: FR-011's
+ * substitution guarantee must hold even when the app's configuration is the
+ * thing that is wrong, so it cannot depend on the app supplying anything. They
+ * are also not re-exported from the provider bridge's own `TestIds`, because
+ * that would put a provider symbol on this package's dependency path for a
+ * value that is really just four documented constants (FR-002).
+ *
+ * Source: Google Mobile Ads "Test ads" documentation, cross-checked against the
+ * bridge's `src/TestIds.ts` at version 16.0.3. These identifiers are public,
+ * are the same for every publisher, and always fill.
+ */
+
+/** Android. iOS units are added alongside these when the iOS adapter lands (FR-006). */
+const ANDROID_TEST_AD_UNITS = {
+  // The adaptive-banner unit, not the fixed-size one, because adaptive is the
+  // format this package actually requests (FR-038).
+  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'
+};
+function testAdUnitFor(format) {
+  return ANDROID_TEST_AD_UNITS[format];
+}
+
+/**
+ * Whether an identifier is one of ours.
+ *
+ * This is the structural test that drives substitution: anything that is not a
+ * known official test unit is treated as production-owned. Deliberately not a
+ * parse of AdMob's publisher-id format — a rule like that becomes wrong the day
+ * Google changes the format, and being wrong here means either sending a
+ * production request or blocking a legitimate one.
+ */
+function isOfficialTestAdUnit(adUnitId) {
+  for (const value of Object.values(ANDROID_TEST_AD_UNITS)) {
+    if (value === adUnitId) {
+      return true;
+    }
+  }
+  return false;
+}
+//# sourceMappingURL=testAdUnits.js.map

package/lib/commonjs/engine/testAdUnits.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ANDROID_TEST_AD_UNITS","banner","interstitial","rewarded","app_open","testAdUnitFor","format","isOfficialTestAdUnit","adUnitId","value","Object","values"],"sourceRoot":"../../../src","sources":["engine/testAdUnits.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA,MAAMA,qBAAyD,GAAG;EACjE;EACA;EACAC,MAAM,EAAE,wCAAwC;EAChDC,YAAY,EAAE,wCAAwC;EACtDC,QAAQ,EAAE,wCAAwC;EAClD;EACA;EACAC,QAAQ,EAAE;AACX,CAAC;AAEM,SAASC,aAAaA,CAACC,MAAgB,EAAU;EACvD,OAAON,qBAAqB,CAACM,MAAM,CAAC;AACrC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,oBAAoBA,CAACC,QAAgB,EAAW;EAC/D,KAAK,MAAMC,KAAK,IAAIC,MAAM,CAACC,MAAM,CAACX,qBAAqB,CAAC,EAAE;IACzD,IAAIS,KAAK,KAAKD,QAAQ,EAAE;MACvB,OAAO,IAAI;IACZ;EACD;EACA,OAAO,KAAK;AACb","ignoreList":[]}

package/lib/commonjs/index.js

@@ -0,0 +1,218 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "AD_VALIDITY_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.AD_VALIDITY_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "APP_OPEN_VALIDITY_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.APP_OPEN_VALIDITY_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "AdsBanner", {
+  enumerable: true,
+  get: function () {
+    return _AdsBanner.AdsBanner;
+  }
+});
+Object.defineProperty(exports, "AdsConfigError", {
+  enumerable: true,
+  get: function () {
+    return _errors.AdsConfigError;
+  }
+});
+Object.defineProperty(exports, "AdsError", {
+  enumerable: true,
+  get: function () {
+    return _errors.AdsError;
+  }
+});
+Object.defineProperty(exports, "AdsProvider", {
+  enumerable: true,
+  get: function () {
+    return _AdsProvider.AdsProvider;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_AD_VALIDITY_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_AD_VALIDITY_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_APP_OPEN_VALIDITY_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_APP_OPEN_VALIDITY_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS", {
+  enumerable: true,
+  get: function () {
+    return _requestThrottle.DEFAULT_BANNER_MIN_REQUEST_INTERVAL_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS", {
+  enumerable: true,
+  get: function () {
+    return _requestThrottle.DEFAULT_FULL_SCREEN_MIN_REQUEST_INTERVAL_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_LOAD_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_LOAD_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_RETRY_POLICY", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_RETRY_POLICY;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_SHOW_TIMEOUT_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_SHOW_TIMEOUT_MS;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_UNDECIDED_WARNING_MS", {
+  enumerable: true,
+  get: function () {
+    return _timers.DEFAULT_UNDECIDED_WARNING_MS;
+  }
+});
+Object.defineProperty(exports, "LOAD_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.LOAD_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "MIN_REQUEST_INTERVAL_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _requestThrottle.MIN_REQUEST_INTERVAL_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "RETRY_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.RETRY_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "SHOW_TIMEOUT_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.SHOW_TIMEOUT_BOUNDS;
+  }
+});
+Object.defineProperty(exports, "UNDECIDED_WARNING_BOUNDS", {
+  enumerable: true,
+  get: function () {
+    return _timers.UNDECIDED_WARNING_BOUNDS;
+  }
+});
+exports.createAds = createAds;
+Object.defineProperty(exports, "defaultMinRequestIntervalMs", {
+  enumerable: true,
+  get: function () {
+    return _requestThrottle.defaultMinRequestIntervalMs;
+  }
+});
+Object.defineProperty(exports, "isAdsError", {
+  enumerable: true,
+  get: function () {
+    return _errors.isAdsError;
+  }
+});
+Object.defineProperty(exports, "isFullScreenFormat", {
+  enumerable: true,
+  get: function () {
+    return _types.isFullScreenFormat;
+  }
+});
+Object.defineProperty(exports, "useAds", {
+  enumerable: true,
+  get: function () {
+    return _AdsProvider.useAds;
+  }
+});
+Object.defineProperty(exports, "useAdsEvents", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useAdsEvents;
+  }
+});
+Object.defineProperty(exports, "useAdsStatus", {
+  enumerable: true,
+  get: function () {
+    return _hooks.useAdsStatus;
+  }
+});
+Object.defineProperty(exports, "usePlacementState", {
+  enumerable: true,
+  get: function () {
+    return _hooks.usePlacementState;
+  }
+});
+var _adsInstance = require("./core/adsInstance.js");
+var _admobEngine = require("./engine/admobEngine.js");
+var _types = require("./config/types.js");
+var _timers = require("./core/timers.js");
+var _requestThrottle = require("./core/requestThrottle.js");
+var _AdsBanner = require("./react/AdsBanner.js");
+var _AdsProvider = require("./react/AdsProvider.js");
+var _hooks = require("./react/hooks.js");
+var _errors = require("./diagnostics/errors.js");
+/**
+ * @chipmobilesdk/rn-ads — reusable advertising capability for
+ * ChipMobileSdk-family React Native apps.
+ *
+ * This is the public entrypoint (LIB-003). Modules under `config/`, `core/`,
+ * `engine/`, `react/`, and `diagnostics/` are private; import them only through
+ * this file. The fake engine lives behind `@chipmobilesdk/rn-ads/testing` so
+ * test doubles cannot reach a production bundle.
+ *
+ * Nothing exported here names Google, AdMob, or any provider type (FR-002).
+ * `src/__tests__/public-api.test.ts` asserts that mechanically.
+ *
+ * The package owns capability: a safe, consistent way to request and present
+ * ads. The consuming app owns policy — where ads appear, when, how often, under
+ * what consent, and whether they appear at all. There is no placement rule, no
+ * frequency cap, and no screen name in this package (FR-045).
+ */
+
+// Configuration and state
+
+// Timeout policy — exported so a consumer can read the defaults it is bound by
+// rather than discovering them from a timeout in production (FR-032).
+
+// Request throttle — account safety, added in 0.3.0 (FR-140). Exported so an app
+// can read the floor it is bound by, and so the format-aware default is legible
+// rather than something to discover from a `throttled` state in production.
+
+// 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).
+
+// Instance, lifecycle, and results
+
+/**
+ * Creates an ads instance. This is the composition root: core's instance with
+ * the AdMob adapter as its default engine, so core/ itself never loads an
+ * adapter (ADS-14). The adapter resolves the provider bridge only on first use,
+ * so importing the package where there is no adapter, or no bridge, costs
+ * nothing and crashes nothing (FR-025, SC-004).
+ */
+function createAds(config, options = {}) {
+  return (0, _adsInstance.createAds)(config, options, _admobEngine.createAdMobEngine);
+}
+
+// React surface
+
+// Diagnostics
+//# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_adsInstance","require","_admobEngine","_types","_timers","_requestThrottle","_AdsBanner","_AdsProvider","_hooks","_errors","createAds","config","options","createInstance","createAdMobEngine"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBA,IAAAA,YAAA,GAAAC,OAAA;AAKA,IAAAC,YAAA,GAAAD,OAAA;AAyBA,IAAAE,MAAA,GAAAF,OAAA;AAIA,IAAAG,OAAA,GAAAH,OAAA;AAkBA,IAAAI,gBAAA,GAAAJ,OAAA;AAkCA,IAAAK,UAAA,GAAAL,OAAA;AAEA,IAAAM,YAAA,GAAAN,OAAA;AAEA,IAAAO,MAAA,GAAAP,OAAA;AAGA,IAAAQ,OAAA,GAAAR,OAAA;AAhHA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;;AAyBA;AACA;;AAgBA;AACA;AACA;;AAQA;AACA;;AAGA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASS,SAASA,CAACC,MAAiB,EAAEC,OAAyB,GAAG,CAAC,CAAC,EAAe;EACzF,OAAO,IAAAC,sBAAc,EAACF,MAAM,EAAEC,OAAO,EAAEE,8BAAiB,CAAC;AAC1D;;AAWA;;AAOA","ignoreList":[]}

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/commonjs/react/AdsBanner.js

@@ -0,0 +1,317 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AdsBanner = AdsBanner;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _errors = require("../diagnostics/errors.js");
+var _AdsProvider = require("./AdsProvider.js");
+var _adsInstance = require("../core/adsInstance.js");
+var _hooks = require("./hooks.js");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * Adaptive banner host (FR-038 – FR-042).
+ *
+ * The app puts this where it wants a banner. The component never inserts itself
+ * into the tree, never overlays app content, and ships no placeholder — the
+ * surrounding layout, and any loading or fallback presentation, belong to the
+ * app and its theme (FR-040, UX-001).
+ *
+ * When ads are disabled or unavailable it renders `null` rather than a
+ * zero-height view. That is not a micro-optimization: a rendered empty view
+ * still sits in the accessibility tree and can take screen-reader focus ahead of
+ * real content. `null` leaves the tree entirely (UX-003).
+ *
+ * The provider owns the banner's whole lifecycle through its own component, so
+ * this adapts those callbacks into the normalized event model instead of routing
+ * a banner through the load/show handle model, which does not fit it.
+ */
+
+function AdsBanner({
+  placementKey,
+  onStateChange,
+  style
+}) {
+  const ads = (0, _AdsProvider.useAds)();
+  // The instance's banner wiring (ADS-13). An instance the app wrote by hand has
+  // none, and is treated like a missing one.
+  const internals = (0, _react.useMemo)(() => ads ? (0, _adsInstance.getInternals)(ads) : null, [ads]);
+  // The throttle token for this mount: stable across renders and minted by React
+  // rather than by a counter, so a render that runs twice charges one slot.
+  const mountToken = (0, _react.useId)();
+  // The reported state lives in a ref rather than in component state: the host
+  // itself renders the same tree for every state, so storing it would only
+  // force re-renders the PERF-002 budget does not need to spend. The instance
+  // holds the authoritative value; `onStateChange` tells the app.
+  const stateRef = (0, _react.useRef)('idle');
+  const [containerWidth, setContainerWidth] = (0, _react.useState)(0);
+  // A new cycle id remounts the provider component, which is how a width change
+  // produces a genuinely re-adapted banner rather than a stretched old one.
+  const [cycle, setCycle] = (0, _react.useState)(0);
+  const correlationRef = (0, _react.useRef)(null);
+  // Whether the current correlation already reported `loaded`. The provider
+  // auto-refreshes a banner inside one mount; each refresh is a new cycle.
+  const loadedInCycleRef = (0, _react.useRef)(false);
+  const startedAtRef = (0, _react.useRef)(0);
+  // Whether this mount has already taken a throttle slot, and the refusal if it
+  // was refused. Resets with the mount, which is exactly the granularity FR-140
+  // needs.
+  const throttleRef = (0, _react.useRef)({
+    decided: false,
+    refusal: null
+  });
+  // Which attempt this mount is on. A refused mount asks again once the window
+  // passes (ADS-06), and each attempt needs its own token: the throttle replays
+  // the stored verdict for a token it has seen.
+  const throttleAttemptRef = (0, _react.useRef)(0);
+
+  // The engine's banner component (ADS-12): the host never names the provider.
+  const banner = (0, _react.useMemo)(() => internals?.banner() ?? null, [internals]);
+  // Initialization is asynchronous and a banner is almost always mounted before
+  // it finishes. Without this the resolution below would be computed once, while
+  // the instance was still `not_started`, be refused, and never be retried — the
+  // banner would sit at `unavailable` forever on a perfectly healthy app.
+  const status = (0, _hooks.useAdsStatus)();
+
+  // Keyed on `cycle` so a genuine width change starts a new, separately traceable
+  // load (FR-038, FR-052), and on `status` so the banner recovers the moment the
+  // instance becomes able to request. Pure: the cycle's correlation id is minted
+  // in the effect that starts it, not here (ADS-20).
+  const resolved = (0, _react.useMemo)(() => internals && status === 'ready' ? {
+    cycle,
+    value: internals.resolveBanner(placementKey)
+  } : null, [internals, placementKey, cycle, status]);
+  const resolution = resolved?.value ?? null;
+  const move = (0, _react.useCallback)(next => {
+    if (stateRef.current === next) {
+      return;
+    }
+    stateRef.current = next;
+    internals?.setPlacementState(placementKey, next);
+    onStateChange?.(next);
+  }, [internals, onStateChange, placementKey]);
+
+  // FR-140. Decided **during render**, not in the effect below, because the
+  // provider component requests an ad as part of this very render — an effect
+  // would refuse a request that had already gone out.
+  //
+  // Charged once per mount, guarded by the ref. That granularity is the whole
+  // distinction the throttle turns on: a fresh mount is the navigation burst it
+  // exists to stop (swiping between days, switching tabs, a row scrolling in and
+  // out), while a later cycle in the *same* mount is a width re-adaptation —
+  // rotation — which must not be refused or a rotated screen loses its banner
+  // for up to a minute.
+  if (internals && resolution?.ok && containerWidth > 0 && !throttleRef.current.decided) {
+    throttleRef.current = {
+      decided: true,
+      refusal: internals.commitBannerRequest(placementKey, `${mountToken}:${throttleAttemptRef.current}`)
+    };
+  }
+  const throttleRefusal = throttleRef.current.refusal;
+  const usable = Boolean(internals && banner && resolution?.ok && containerWidth > 0 && !throttleRefusal);
+  (0, _react.useEffect)(() => {
+    if (!internals || !banner) {
+      move('unavailable');
+      return;
+    }
+    // `not_started` and `initializing` are transient: the app is still on its
+    // way and the banner will resolve shortly, so report `idle` rather than
+    // `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 === 'undecided' ? 'undecided' : status === 'not_started' || status === 'initializing' ? 'idle' : 'unavailable');
+      return;
+    }
+    if (!resolution?.ok) {
+      move('unavailable');
+      return;
+    }
+    if (containerWidth <= 0) {
+      // FR-039: a zero-width container is reported rather than turned into a
+      // request for an ad at a nonsensical size.
+      move('idle');
+      return;
+    }
+    // The slot was taken during render; here is where the refusal becomes
+    // observable. Reported as `throttled` rather than folded into
+    // `unavailable`: that would say "there will be no ad here", when in fact
+    // this placement asked too recently and will work again shortly. Most apps
+    // collapse the space for both, but only one is worth investigating.
+    if (throttleRefusal) {
+      move('throttled');
+      internals.emit({
+        type: 'request_throttled',
+        timestamp: internals.now(),
+        placementKey,
+        format: 'banner',
+        retryAfterMs: throttleRefusal.retryAfterMs,
+        minRequestIntervalMs: internals.throttleFloorFor(placementKey)
+      });
+      // ADS-06: ask again in this same mount once the window has passed. Until
+      // 0.7.0 a refused banner stayed empty until it was remounted, so a banner
+      // pinned to a screen the user returned to within a minute never filled.
+      return internals.schedule(throttleRefusal.retryAfterMs, () => {
+        throttleRef.current = {
+          decided: false,
+          refusal: null
+        };
+        throttleAttemptRef.current += 1;
+        setCycle(value => value + 1);
+      });
+    }
+    const correlationId = internals.nextCorrelationId();
+    correlationRef.current = correlationId;
+    loadedInCycleRef.current = false;
+    startedAtRef.current = internals.now();
+    move('loading');
+    internals.emit({
+      type: 'load_started',
+      timestamp: startedAtRef.current,
+      placementKey,
+      format: 'banner',
+      correlationId
+    });
+    // Deliberately keyed on `cycle`, not on every render: FR-041 forbids a
+    // re-render from producing a second uncontrolled request.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [internals, banner, status, resolution, containerWidth, cycle]);
+  const onLayout = (0, _react.useCallback)(event => {
+    const width = Math.round(event.nativeEvent.layout.width);
+    setContainerWidth(previous => {
+      if (previous === width) {
+        return previous;
+      }
+      // FR-038: a genuine width or orientation change re-adapts. The
+      // rounding above stops sub-pixel layout jitter from doing so.
+      if (previous > 0 && width > 0) {
+        setCycle(value => value + 1);
+      }
+      return width;
+    });
+  }, []);
+  const emit = (0, _react.useCallback)(event => {
+    internals?.emit(event);
+  }, [internals]);
+  const clock = (0, _react.useCallback)(() => internals?.now() ?? Date.now(), [internals]);
+  const handleLoaded = (0, _react.useCallback)(() => {
+    // A second load in one correlation is the provider's auto-refresh: a new
+    // ad, so a new cycle. Under the old correlation its `loaded` and
+    // `impression` were deduplicated away and revenue went uncounted (ADS-05).
+    // For a refresh, `durationMs` is the time since the previous load.
+    if (loadedInCycleRef.current && internals) {
+      correlationRef.current = internals.nextCorrelationId();
+    }
+    loadedInCycleRef.current = true;
+    const loadedAt = clock();
+    move('ready');
+    emit({
+      type: 'loaded',
+      timestamp: loadedAt,
+      placementKey,
+      format: 'banner',
+      correlationId: correlationRef.current ?? undefined,
+      durationMs: loadedAt - startedAtRef.current
+    });
+    startedAtRef.current = loadedAt;
+  }, [internals, clock, emit, move, placementKey]);
+  const handleFailed = (0, _react.useCallback)((error, kind) => {
+    const normalized = (0, _errors.normalizeProviderError)(error, {
+      operation: 'load',
+      placementKey,
+      format: 'banner'
+    }, kind);
+    move('failed');
+    emit({
+      type: 'load_failed',
+      timestamp: clock(),
+      placementKey,
+      format: 'banner',
+      correlationId: correlationRef.current ?? undefined,
+      error: normalized
+    });
+  }, [clock, emit, move, placementKey]);
+  const handleImpression = (0, _react.useCallback)(() => {
+    emit({
+      type: 'impression',
+      timestamp: clock(),
+      placementKey,
+      format: 'banner',
+      correlationId: correlationRef.current ?? undefined,
+      // A real provider impression, unlike the derived one full-screen
+      // formats get. The distinction is load-bearing for revenue
+      // reconciliation, so it is recorded rather than flattened (R5).
+      source: 'provider'
+    });
+  }, [clock, emit, placementKey]);
+  const handleClicked = (0, _react.useCallback)(() => {
+    emit({
+      type: 'click',
+      timestamp: clock(),
+      placementKey,
+      format: 'banner',
+      correlationId: correlationRef.current ?? undefined
+    });
+  }, [clock, emit, placementKey]);
+
+  // FR-041: nothing survives unmount. No retained native view, no dangling
+  // correlation, no state written into a disposed instance.
+  (0, _react.useEffect)(() => {
+    return () => {
+      correlationRef.current = null;
+    };
+  }, []);
+  if (!internals || !banner) {
+    // FR-042, UX-003 — out of the tree entirely, blocking no touch.
+    return null;
+  }
+
+  // A terminal non-ready status means there will be no ad at all, so leave the
+  // 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;
+    }
+  }
+  const BannerComponent = banner.Component;
+  const adUnitId = resolution?.ok ? resolution.adUnitId : null;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: style,
+    onLayout: onLayout,
+    testID: `ads-banner-${placementKey}`,
+    children: usable && adUnitId && resolution?.ok ? /*#__PURE__*/(0, _jsxRuntime.jsx)(BannerComponent, {
+      adUnitId: adUnitId,
+      personalizedAds: resolution.personalizedAds,
+      onLoaded: handleLoaded,
+      onFailed: handleFailed,
+      onImpression: handleImpression,
+      onClicked: handleClicked
+    }, `${placementKey}-${cycle}`) : null
+  });
+}
+//# sourceMappingURL=AdsBanner.js.map

package/lib/commonjs/react/AdsBanner.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","_interopRequireWildcard","require","_reactNative","_errors","_AdsProvider","_adsInstance","_hooks","_jsxRuntime","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","AdsBanner","placementKey","onStateChange","style","ads","useAds","internals","useMemo","getInternals","mountToken","useId","stateRef","useRef","containerWidth","setContainerWidth","useState","cycle","setCycle","correlationRef","loadedInCycleRef","startedAtRef","throttleRef","decided","refusal","throttleAttemptRef","banner","status","useAdsStatus","resolved","value","resolveBanner","resolution","move","useCallback","next","current","setPlacementState","ok","commitBannerRequest","throttleRefusal","usable","Boolean","useEffect","emit","type","timestamp","now","format","retryAfterMs","minRequestIntervalMs","throttleFloorFor","schedule","correlationId","nextCorrelationId","onLayout","event","width","Math","round","nativeEvent","layout","previous","clock","Date","handleLoaded","loadedAt","undefined","durationMs","handleFailed","error","kind","normalized","normalizeProviderError","operation","handleImpression","source","handleClicked","result","BannerComponent","Component","adUnitId","jsx","View","testID","children","personalizedAds","onLoaded","onFailed","onImpression","onClicked"],"sourceRoot":"../../../src","sources":["react/AdsBanner.tsx"],"mappings":"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","ignoreList":[]}