@streamlayer/feature-advertisement 1.1.1-rc.1350 → 1.1.1-rc.2.pf58ff685

package/lib/units/external-ad.js

@@ -9,6 +9,7 @@ import '@streamlayer/sdk-web-api';
 import VMAP from 'vmap';
 import { gam } from './gam.js';
 import { parseVastExtension } from './parse-vast-extensions.js';
+import { collectAssets, selectCardLogo } from './sponsor-logo.js';
 const log = createLogger('ui:gam-external-ad');
 /** Default budget for a single VAST resolution before it is treated as "no ad". */
 const VAST_FETCH_TIMEOUT_MS = 10_000;
@@ -38,7 +39,7 @@ const withTimeout = (promise, ms) => {
  * Get the first valid creative from an ad
  */
 const getCreative = (ad) => {
-    return ad.creatives.find((creative) => creative.mediaFiles);
+    return ad.creatives.find((creative) => getMediaFileUrl(creative));
 };
 /**
  * Get the URL of the first media file in the creative
@@ -59,31 +60,10 @@ const getClickThrough = (creative) => {
     // @ts-ignore — vast-client types `videoClickThroughURLTemplate` loosely
     return creative?.videoClickThroughURLTemplate?.url || undefined;
 };
-/**
- * Extract every `<Companion>` variation of the first `<CompanionAds>` creative that carries a
- * `<StaticResource>`, in document order. `width`/`height` are XML attributes (strings at
- * runtime), normalised to numbers so the size mapping can compare them.
- */
-const getCompanions = (ad) => {
-    const creative = ad.creatives.find((item) => item.type === 'companion');
-    return (creative?.variations || []).reduce((acc, variation) => {
-        const imageUrl = variation?.staticResources?.[0]?.url;
-        if (!imageUrl) {
-            return acc;
-        }
-        return acc.concat({
-            imageUrl,
-            clickUrl: variation.companionClickThroughURLTemplate ?? undefined,
-            width: Number(variation.width) || undefined,
-            height: Number(variation.height) || undefined,
-            creative,
-            variation,
-        });
-    }, []);
-};
 /** Product companion mapping: the 300x75 companion is the logo, the banner-sized one the media. */
 const LOGO_COMPANION_WIDTH = 300;
 const LOGO_COMPANION_HEIGHT = 75;
+const isLogoSized = (companion) => companion?.width === LOGO_COMPANION_WIDTH && companion?.height === LOGO_COMPANION_HEIGHT;
 const companionArea = (companion) => (companion.width || 0) * (companion.height || 0);
 /**
  * Split a `<CompanionAds>` creative's variations into the logo and media slots.
@@ -91,11 +71,18 @@ const companionArea = (companion) => (companion.width || 0) * (companion.height
  * The pair mapping activates only for a tag that ships an exact 300x75 companion next to at
  * least one other. Deliberately conservative pending broader product sizes: on any other tag
  * no companion is promoted to the logo slot and the first one stays the media/strip candidate.
+ *
+ * Both halves of that gate are load-bearing and neither is an aspect rule: a 320x80 companion is
+ * the same 4:1 shape as 300x75 and is still rejected, and a lone 300x75 companion is rejected too
+ * (the Standard Ad Sidebar recovers that one as `AdData.loneLogo` when a Linear / NonLinear is
+ * the media, so it is not needed here).
+ * This is **narrower than iOS**, which has no size rule at all and fills its logo slot from a
+ * single companion — see `docs/wiki/programmatic-ads-display-ios-parity.md`. Exported for
+ * `external-ad.spec.ts` only; `src/index.ts` re-exports names explicitly, so this stays out of the
+ * package's public API.
  */
-const selectCompanions = (companions) => {
-    const logo = companions.length > 1
-        ? companions.find((companion) => companion.width === LOGO_COMPANION_WIDTH && companion.height === LOGO_COMPANION_HEIGHT)
-        : undefined;
+export const selectCompanions = (companions) => {
+    const logo = companions.length > 1 ? companions.find((companion) => isLogoSized(companion)) : undefined;
     if (!logo) {
         return { logo: undefined, media: companions[0] };
     }
@@ -105,40 +92,26 @@ const selectCompanions = (companions) => {
         .pop();
     return { logo, media };
 };
-/**
- * Extract the first `<NonLinearAds>` creative's static-image variation. Both the creative (which
- * owns the `<TrackingEvents>`) and the variation (which owns the click-through) are kept —
- * `VASTTracker` needs both.
- *
- * `@dailymotion/vast-client` 6.4.2 emits `nonlinearClickThroughURLTemplate` (lower-case `l`),
- * which the `@types/vast-client` shim declares as `nonLinearClickThroughURLTemplate` — the
- * runtime spelling is authoritative.
- */
-const getNonLinear = (ad) => {
-    const creative = ad.creatives.find((item) => item.type === 'nonlinear');
-    const variation = creative?.variations?.[0];
-    const imageUrl = variation?.staticResource;
-    if (!creative || !variation || !imageUrl) {
-        return undefined;
-    }
-    return {
-        imageUrl,
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore — see the runtime-vs-shim spelling note above
-        clickUrl: variation.nonlinearClickThroughURLTemplate ?? undefined,
-        width: Number(variation.width) || undefined,
-        height: Number(variation.height) || undefined,
-        creative,
-        variation,
-    };
-};
 /**
  * Map a parsed VAST response into our `AdData` shape. Shared by both acquisition
  * paths — the GAM/VMAP tag flow and the Prebid auction flow — so the two always
- * produce identical downstream data. Returns `undefined` when the response has no
- * ad carrying creatives.
+ * produce identical downstream data.
+ *
+ * Returns `undefined` for a no-ad, which is two distinct shapes: a response with no ad carrying
+ * creatives, and an ad whose creatives carry no RENDERABLE asset — no linear `<MediaFile>`, no
+ * `<NonLinear>` still and no `<Companion>` image. Both callers `filter(Boolean)` the result, so a
+ * no-ad leaves `ads: []` and the card keeps whatever the server configured for it.
+ *
+ * Exported for `vast-mapping.spec.ts`, which drives it over the same fixture corpus the iOS suite
+ * uses. `src/index.ts` re-exports names explicitly, so this stays out of the package's public API.
  */
-const buildAdData = (parsedVAST, order) => {
+export const buildAdData = (parsedVAST, order) => {
+    // Defensive, and unreachable through either production path: `@dailymotion/vast-client` discards
+    // an ad whose creatives all fail to parse (empty `<Linear>`, empty/missing `<Creatives>`, unknown
+    // creative element) before `parseVAST` resolves, so it never yields an Ad with zero creatives.
+    // Kept because it costs nothing and `buildAdData` is also reachable from tests with a hand-built
+    // response — see the `invalid_ad` case in `vast-mapping.spec.ts`, which pins the parser contract
+    // this relies on rather than pretending to exercise the guard.
     const validAd = parsedVAST.ads.find((ads) => ads.creatives.length > 0);
     if (!validAd) {
         log.warn({ order, ads: parsedVAST.ads.length }, 'vast response carries no ad with creatives — treated as no-ad');
@@ -150,10 +123,47 @@ const buildAdData = (parsedVAST, order) => {
     const parsedExtension = parseVastExtension(extension);
     const creative = getCreative(validAd);
     const mediaFileUrl = getMediaFileUrl(creative);
-    const companions = getCompanions(validAd);
+    const images = collectAssets(validAd);
+    const companions = images.filter((asset) => asset.origin === 'companion');
+    const nonLinear = images.find((asset) => asset.origin === 'nonlinear');
+    // An ad the parser KEPT whose creatives carry nothing any shell can draw is a no-ad, exactly
+    // like a response with no ad at all. vast-client only discards a creative it cannot parse; a
+    // `<NonLinear>` or `<Companion>` whose `<StaticResource>` body is empty parses fine and just
+    // yields no url, so the guard above cannot catch it. Without this the fabricated promotion still
+    // took the slot and drew the ad's TEXT — title and description over an empty media box — which
+    // is a billable impression for a creative that does not exist.
+    //
+    // "Renderable" is the union of the three slots the shells can fill: a linear `<MediaFile>`, a
+    // `<NonLinear>` still, or a `<Companion>` image. `collectAssets` already drops the imageless
+    // ones, so a non-empty `companions` means at least one drawable image. A tag carrying only a
+    // `<Mezzanine>` never reaches here — the parser drops that Linear itself — but it lands in the
+    // same place either way.
+    if (!mediaFileUrl && !nonLinear && companions.length === 0) {
+        log.warn({ order, adId: validAd.id, creatives: validAd.creatives.length }, 'vast ad carries no renderable asset (no media file, no nonlinear, no companion) — treated as no-ad');
+        return undefined;
+    }
     const { logo, media: mediaCompanion } = selectCompanions(companions);
-    const nonLinear = getNonLinear(validAd);
     const clickThrough = getClickThrough(creative) || nonLinear?.clickUrl || mediaCompanion?.clickUrl;
+    // Mirror iOS's greedy `pool.select([hero, .cardLogo])`: the hero claims first and a claimed
+    // asset is gone for later roles. Web's hero precedence (`createActiveAdFromVast`) is linear
+    // video → pair media companion (unreachable here: a `logo` short-circuits the whole selection)
+    // → NonLinear still → lone companion, so a companion is only unavailable to the logo slot when
+    // it IS the hero, i.e. when the tag ships neither. `selectCardLogo` already filters to companion
+    // origins, so the NonLinear never needs excluding.
+    //
+    // Excluding `companions[0]` (which is what `mediaCompanion` is when there is no `logo`) rather
+    // than the largest-area asset is a deliberate difference from iOS's `areaDominant` hero: web's
+    // content slot draws the FIRST companion in document order, so document order is the correct
+    // criterion for "what the hero already claimed" on this platform.
+    const companionIsHero = !mediaFileUrl && !nonLinear;
+    const cardLogoAsset = logo ? undefined : selectCardLogo(validAd, companionIsHero ? [mediaCompanion] : []);
+    // Share the selected resource wrapper so drawn-companion identity remains stable.
+    const cardLogo = cardLogoAsset
+        ? companions.find((item) => item.variation === cardLogoAsset.variation && item.imageUrl === cardLogoAsset.imageUrl)
+        : undefined;
+    // Same collected instance as `companion` (identity matters to `drawnCompanions`). A lone
+    // companion never satisfies the pair rule, so this can only fill a slot `logo` left empty.
+    const loneLogo = companions.length === 1 && !companionIsHero && isLogoSized(companions[0]) ? companions[0] : undefined;
     log.info({
         order,
         adId: validAd.id,
@@ -169,6 +179,8 @@ const buildAdData = (parsedVAST, order) => {
             media: mediaCompanion
                 ? { size: `${mediaCompanion.width}x${mediaCompanion.height}`, url: mediaCompanion.imageUrl }
                 : undefined,
+            cardLogo: cardLogo ? { size: `${cardLogo.width}x${cardLogo.height}`, url: cardLogo.imageUrl } : undefined,
+            loneLogo: loneLogo ? { size: `${loneLogo.width}x${loneLogo.height}`, url: loneLogo.imageUrl } : undefined,
             clickThrough: !!clickThrough,
         },
     }, 'vast ad parsed');
@@ -178,6 +190,8 @@ const buildAdData = (parsedVAST, order) => {
         mediaFileUrl,
         companion: companions[0],
         logo,
+        cardLogo,
+        loneLogo,
         mediaCompanion,
         nonLinear,
         clickThrough,
@@ -206,8 +220,12 @@ const createRequestId = () => `sl-web-${Date.now().toString(36)}-${Math.random()
  * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
  * - `test=1` → top-level `test` flag.
  * - `w` / `h` → video dimensions (default 1920×1080).
+ *
+ * The host's GDPR consent (`AdTagParams`) rides the OpenRTB 2.5 extension fields Prebid Server
+ * reads — `regs.ext.gdpr` and `user.ext.consent` — the same signal the `${GDPR}` /
+ * `${GDPR_CONSENT}` macros carry for a VAST tag. Each is sent only when the host passed it.
  */
-const buildAuctionRequest = (url) => {
+export const buildAuctionRequest = (url, adTagParams) => {
     const params = url.searchParams;
     const width = Number(params.get('w')) || 1920;
     const height = Number(params.get('h')) || 1080;
@@ -245,6 +263,12 @@ const buildAuctionRequest = (url) => {
     if (params.get('test') === '1') {
         request.test = 1;
     }
+    if (adTagParams?.gdprApplies !== undefined) {
+        request.regs = { ext: { gdpr: adTagParams.gdprApplies ? 1 : 0 } };
+    }
+    if (adTagParams?.tcString) {
+        request.user = { ext: { consent: adTagParams.tcString } };
+    }
     return request;
 };
 /**
@@ -252,11 +276,11 @@ const buildAuctionRequest = (url) => {
  * Every bid's `adm` is inline VAST XML (no URL to fetch); bids are ordered by price
  * so the winner plays first (RFC §2). A single bad bid must not drop the batch.
  */
-const fetchPrebidAds = async (prebidUrl) => {
+const fetchPrebidAds = async (prebidUrl, adTagParams) => {
     const response = await fetch(prebidUrl.toString(), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(buildAuctionRequest(prebidUrl)),
+        body: JSON.stringify(buildAuctionRequest(prebidUrl, adTagParams)),
     });
     if (!response.ok) {
         throw new Error(`prebid auction failed with status ${response.status}`);
@@ -309,13 +333,17 @@ export const externalAd = (instance) => {
                     return undefined;
                 }
             })();
+            // The host's CURRENT macro values, read per request rather than baked into the store: the
+            // store is cached by url for the session, and consent routinely arrives after the SDK
+            // starts (a CMP answers asynchronously) or changes mid-session.
+            const adTagParams = instance.sdk.options.get().adTagParams;
             // Prebid links hit our Prebid Server auction endpoint instead of a VAST tag.
             // Run the OpenRTB auction and parse the winning bid's inline VAST (`adm`) into
             // the same `AdStore` shape the GAM/VMAP path returns. See rfcs/prebid.
             if (parsedAdUrl && isPrebidUrl(parsedAdUrl)) {
-                return fetchPrebidAds(parsedAdUrl);
+                return fetchPrebidAds(parsedAdUrl, adTagParams);
             }
-            const generateUrl = gam(adUrl);
+            const generateUrl = gam(adUrl, undefined, adTagParams);
             const generatedUrl = await generateUrl();
             const noncedLink = generatedUrl?.url;
             if (!noncedLink) {

package/lib/units/external-pause-ad.js

@@ -7,6 +7,7 @@ import { eventBus } from '@streamlayer/sdk-web-interfaces';
 import { createLogger } from '@streamlayer/sdk-web-logger';
 import '@streamlayer/sdk-web-api';
 import { VASTClient } from '@dailymotion/vast-client';
+import { substituteAdTagMacros } from './ad-macros.js';
 const FULLBLEED_VIDEO_TEMPLATES = [
     'fullbleed-video',
     'fullbleed-video-center',
@@ -115,7 +116,12 @@ export const externalPauseAd = (instance) => {
             try {
                 // `resolveAll: true` follows every `VASTAdTagURI` wrapper chain and resolves all
                 // Ads (the default only resolves the first standalone Ad and stops at the wrapper).
-                const parsedVAST = await vastClient.get(adUrl, { resolveAll: true });
+                // Pause-ad tags do not go through `gam()`, so fill the macros here — with the host's values
+                // as they are NOW, since this fetcher re-runs on every pause. The store key stays the
+                // configured url: `ExposedPauseAd` compares against it.
+                const parsedVAST = await vastClient.get(substituteAdTagMacros(adUrl, instance.sdk.options.get().adTagParams), {
+                    resolveAll: true,
+                });
                 const template = options.template ?? 'default';
                 // `fullbleed-video` needs an ad that actually carries a usable linear MP4. With
                 // `resolveAll: true` the response can be a pod/wrapper chain, so prefer the first

package/lib/units/gam.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
+ *
+ * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
+ * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
+ * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
+ * `$store` bridge that is its only consumer — so the two feature packages share no code and
+ * neither depends on the other.
+ */
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
 export type PalNonceManager = {
     getNonce: () => string;
     sendAdClick: () => void;
@@ -8,7 +18,7 @@ export type GamNonceResult = {
     url: URL;
     manager?: PalNonceManager;
 };
-export declare const gam: (url: string, adContainer?: HTMLDivElement) => (() => Promise<{
+export declare const gam: (rawUrl: string, adContainer?: HTMLDivElement, adTagParams?: AdTagParams) => (() => Promise<{
     url: URL;
 }>) | (() => Promise<{
     url: URL;

package/lib/units/gam.js

@@ -1,18 +1,67 @@
-/**
- * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
- *
- * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
- * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
- * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
- * `$store` bridge that is its only consumer — so the two feature packages share no code and
- * neither depends on the other.
- */
 import { safeLocalStorage, safeSessionStorage } from '@streamlayer/sdk-web-storage';
 import { validate as uuidValidate, v5 as uuid5, v4 as uuid4 } from 'uuid';
+import { substituteAdTagMacros } from './ad-macros.js';
 const urlIsNotGam = (url) => {
     return url.origin !== 'https://pubads.g.doubleclick.net';
 };
-export const gam = (url, adContainer) => {
+const palScriptUrl = 'https://imasdk.googleapis.com/pal/sdkloader/pal.js';
+const getPal = () => {
+    // @ts-expect-error Google PAL is supplied by the host or the script loader below.
+    return typeof goog === 'undefined' ? undefined : goog.pal;
+};
+let palReady;
+const ensurePal = async () => {
+    if (getPal()) {
+        return;
+    }
+    if (!palReady) {
+        palReady = new Promise((resolve, reject) => {
+            if (typeof document === 'undefined') {
+                reject(new Error('Google PAL requires a browser document'));
+                return;
+            }
+            const existing = document.querySelector(`script[src="${palScriptUrl}"]`);
+            const script = existing || document.createElement('script');
+            const finish = (error) => {
+                clearTimeout(timeout);
+                script.removeEventListener('load', onLoad);
+                script.removeEventListener('error', onError);
+                if (error) {
+                    if (!existing) {
+                        script.remove();
+                    }
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            const onLoad = () => finish(getPal() ? undefined : new Error('Google PAL did not initialize'));
+            const onError = () => finish(new Error('Google PAL failed to load'));
+            const timeout = setTimeout(() => finish(new Error('Google PAL loading timed out')), 10000);
+            script.addEventListener('load', onLoad);
+            script.addEventListener('error', onError);
+            if (!existing) {
+                script.async = true;
+                script.src = palScriptUrl;
+                document.head.appendChild(script);
+            }
+        }).catch((error) => {
+            palReady = undefined;
+            throw error;
+        });
+    }
+    await palReady;
+    palReady = undefined;
+};
+export const gam = (rawUrl, adContainer, adTagParams) => {
+    // Every VAST/VMAP tag funnels through here, so this is where the macros get filled — for GAM and
+    // for any other vendor alike. Studio stores a programmatic tag verbatim, so an unexpanded
+    // `[timestamp]` / `[clickmacro]` / `${GDPR}` would otherwise reach the ad server literal, and a
+    // literal macro comes back copied into the vendor's click-through. `adTagParams` are the host's
+    // consent and click values, read by the caller at request time. The GAM `[placeholder]` tokens
+    // are left alone here and filled per parameter below.
+    const url = substituteAdTagMacros(rawUrl, adTagParams);
     const parsedUrl = (() => {
         try {
             const parsedUrl = new URL(url);
@@ -32,20 +81,19 @@ export const gam = (url, adContainer) => {
             return { url: parsedUrl };
         };
     }
-    // @ts-expect-error goog is injected by the externally-loaded Google PAL SDK
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const pal = (typeof goog === 'undefined' ? undefined : goog.pal);
-    if (!pal || !parsedUrl) {
+    if (!parsedUrl) {
         // eslint-disable-next-line require-await
         return async () => {
             return undefined;
         };
     }
-    const consentSettings = new pal.ConsentSettings();
-    consentSettings.allowStorage = false;
-    const nonceLoader = new pal.NonceLoader(consentSettings);
     const generateUrl = async () => {
         try {
+            await ensurePal();
+            const pal = getPal();
+            const consentSettings = new pal.ConsentSettings();
+            consentSettings.allowStorage = false;
+            const nonceLoader = new pal.NonceLoader(consentSettings);
             const parsedUrl = new URL(url);
             const request = new pal.NonceRequest();
             let deviceId = safeLocalStorage().getItem('sl-device-id') || uuid4();

package/lib/units/parse-vast-extensions.d.ts

@@ -1,7 +1,16 @@
 import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
 export interface VastCreative {
     adName: string;
-    adType: AdType;
+    /**
+     * The placement this extension NAMES, or `undefined` when its root element is not one we map.
+     *
+     * Deliberately not defaulted here. An unrecognised extension means "this tag says nothing about
+     * placement", which must not outrank a placement the promotion proto already stated — defaulting
+     * it to `SIDE_BY_SIDE` at this layer silently re-routed a configured Sidebar/L-Bar, because the
+     * consumers join with `extension?.adType ?? placement`. The default now lives in
+     * `resolveExternalAdType`, applied only after the proto placement has had its turn.
+     */
+    adType?: AdType;
     landscapeBackground?: string;
     portraitBackground?: string;
     sponsorLogo?: string;

package/lib/units/parse-vast-extensions.js

@@ -1,4 +1,8 @@
 import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+/**
+ * Extension root element name → the placement it names. Only `DoubleBox` is defined by the
+ * StreamLayer extension schema today; anything else is a vendor extension we do not interpret.
+ */
 const MAP_EXTENSION_NAME_AD_TYPE = {
     DoubleBox: AdType.SIDE_BY_SIDE,
 };
@@ -38,7 +42,7 @@ export function parseVastExtension(root) {
     };
     return {
         adName,
-        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name] || AdType.SIDE_BY_SIDE,
+        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name],
         landscapeBackground: backgrounds.find((b) => b.orientation === 'landscape')?.url,
         portraitBackground: backgrounds.find((b) => b.orientation === 'portrait')?.url,
         sponsorLogo: logos.find((l) => l.role === 'header')?.url,

package/lib/units/sponsor-logo.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Sponsor-logo slot selection for a **feature** ad unit (Insight, Prediction and Trivia today;
+ * Poll is the same shape and is a separate ticket).
+ *
+ * Deliberately NOT `selectCompanions` (`./external-ad.ts`). That rule is the *display*-unit rule:
+ * it promotes a companion to the logo slot only when the tag ships an exact 300x75 `<Companion>`
+ * next to at least one other. A feature ad-unit tag is typically a **single** creative — often a
+ * lone NonLinear `<StaticResource>` — where the ad IS the logo, which is exactly the shape that
+ * rule returns nothing for. `selectCompanions` stays untouched: SC-335's three shipped units
+ * depend on its exact behaviour and impression counts are billing-visible.
+ *
+ * Mirrors iOS `SLRVASTSlotRole.logo` + `SLRVASTAssetPool`
+ * (`StreamLayerSDK/Frameworks/SLRGAMFramework/Sources/VASTSlotFiller/`):
+ *
+ * - **Images only.** A video-only tag yields no logo. `<Icon>` is never projected — icons hang off
+ *   the `<Linear>` creative, which this selector does not look at. A `<StaticResource>` the tag
+ *   declares as a non-image `creativeType` is skipped too, so a companion that lists a script
+ *   before its image still resolves to the image (see `isImageResource`).
+ * - **Origin-agnostic.** A lone NonLinear `<StaticResource>` is as valid as a `<Companion>`.
+ * - **Aspect-dominant** toward 1:1: the smallest `|log(assetAspect) - log(1)|` wins, ties broken by
+ *   larger area, then by higher pixel density. Aspect is a *preference, never a filter* — the only
+ *   hard constraint is the asset kind, so a badly shaped asset still wins if it is the only one.
+ * - Assets whose intrinsic size the tag never declared rank last, but still beat nothing.
+ *
+ * The module also hosts iOS's second logo role, `SLRVASTSlotRole.cardLogo` (`selectCardLogo`) —
+ * the same ranking narrowed to `<Companion>` origins, for the hero-card display units.
+ */
+import { VastCompanionAd, VastCreativeCompanion, VastCreativeNonLinear, VastNonLinearAd } from '@dailymotion/vast-client';
+/**
+ * One image asset that may fill a sponsor-logo slot. Carries the creative + variation pair so the
+ * caller can build a `VASTTracker` for it through `createVastTracker` without re-deriving them.
+ */
+export type SponsorLogoAsset = {
+    imageUrl: string;
+    clickUrl?: string;
+    width?: number;
+    height?: number;
+    /** Which VAST element the image came from. The slot does not care; the beacons do. */
+    origin: 'companion' | 'nonlinear';
+    /** The `<CompanionAds>` / `<NonLinearAds>` creative — the `VASTTracker` 3rd argument. */
+    creative: VastCreativeCompanion | VastCreativeNonLinear;
+    /** The `<Companion>` / `<NonLinear>` variation — the 4th argument; owns `creativeView`. */
+    variation: VastCompanionAd | VastNonLinearAd;
+};
+/**
+ * What a caller hands the selector. A parsed `@dailymotion/vast-client` ad satisfies it.
+ * The published declarations must not name that package's types: its own `.d.ts` does not
+ * export them, and the local shim that does is not part of the tarball.
+ */
+export interface SponsorLogoSource {
+    creatives?: unknown;
+}
+/**
+ * Pick the image a parsed VAST ad offers for a sponsor-logo slot, or `undefined` when it offers
+ * none (a video-only tag, or an empty response). A caller that gets `undefined` must fall back to
+ * its own proto/Studio logo rather than suppressing the card.
+ */
+export declare const collectAssets: (ad: SponsorLogoSource) => SponsorLogoAsset[];
+export declare const selectSponsorLogo: (ad: SponsorLogoSource) => SponsorLogoAsset | undefined;
+/**
+ * iOS `SLRVASTSlotRole.cardLogo` — the sponsor logo of a **hero card** (1:1 / 2:1 / Picture in
+ * Picture / Side-by-Side / Sponsor Frame). Same 1:1 aspect-dominant ranking as `.logo`, plus the
+ * one constraint that distinguishes the two roles:
+ *
+ * - **`requiredOrigin: .companion`.** A NonLinear image is a hero creative, never a logo. iOS's
+ *   reason: a leftover hero-type asset — a second `<NonLinear>` overlay, or a stray image still in
+ *   the pool after the hero role claimed its own — must never leak into the card's logo slot,
+ *   where it would render at logo size as an unreadable smudge of the advertiser's key art.
+ *   `nonlinear_full` is the fixture that pins it: `.logo` takes the 500x500 NonLinear, `.cardLogo`
+ *   must take the 200x200 `<Companion>`.
+ * - **`exclude`** mirrors iOS's **greedy** `pool.select([hero, .cardLogo])`: roles resolve in array
+ *   order and an asset a role claims is removed from the pool for every later role. We have no
+ *   pool object, so the caller passes the assets the hero already claimed and they are filtered
+ *   out here by `imageUrl`.
+ */
+export declare const selectCardLogo: (ad: SponsorLogoSource, exclude?: ({
+    imageUrl?: string;
+} | undefined)[]) => SponsorLogoAsset | undefined;