@streamlayer/feature-advertisement 0.4.3 → 1.0.0

package/lib/units/external-ad.js

@@ -1,83 +1,381 @@
+// Pins the `@dailymotion/vast-client` → `@types/vast-client` shim: TypeDoc
+// compiles this file through dependent packages' programs, whose tsconfig
+// `include` does not cover this package's ambient declarations.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
 import { createLogger } from '@streamlayer/sdk-web-logger';
+import { VASTClient, VASTParser, } from '@dailymotion/vast-client';
 import '@streamlayer/sdk-web-api';
-import { VASTClient } from '@dailymotion/vast-client';
-const vastClient = new VASTClient();
-const log = createLogger('ui:gam-static-ad');
-const preloadImage = (src) => {
-    return new Promise((resolve, reject) => {
-        const image = new Image();
-        image.onload = () => resolve(src);
-        image.onerror = () => reject();
-        image.src = src;
+import VMAP from 'vmap';
+import { gam } from './gam';
+import { parseVastExtension } from './parse-vast-extensions';
+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;
+/**
+ * Resolve `promise`, but fall back to `undefined` if it doesn't settle within `ms`.
+ * A slow/unreachable VAST endpoint must degrade to "no ad" instead of leaving the
+ * fetcher (and the sidebar) stuck waiting. Uses a timer rather than `AbortController`
+ * so it stays safe on the ES5/Chrome-32 target.
+ */
+const withTimeout = (promise, ms) => {
+    return Promise.race([
+        promise,
+        new Promise((resolve) => {
+            setTimeout(() => resolve(undefined), ms);
+        }),
+    ]);
+};
+// const preloadImage = (src: string) => {
+//   return new Promise((resolve, reject) => {
+//     const image = new Image()
+//     image.onload = () => resolve(src)
+//     image.onerror = () => reject()
+//     image.src = src
+//   })
+// }
+/**
+ * Get the first valid creative from an ad
+ */
+const getCreative = (ad) => {
+    return ad.creatives.find((creative) => creative.mediaFiles);
+};
+/**
+ * Get the URL of the first media file in the creative
+ */
+const getMediaFileUrl = (creative) => {
+    const mediaFiles = creative?.mediaFiles;
+    if (!mediaFiles?.length) {
+        return '';
+    }
+    return mediaFiles.find((mediaFile) => mediaFile.fileURL)?.fileURL || '';
+};
+/**
+ * Extract the linear creative's `<ClickThrough>` URL. Sources the sidebar CTA (QR code
+ * + click-through). `videoClickThroughURLTemplate` isn't strongly typed in the client lib.
+ */
+const getClickThrough = (creative) => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @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 companionArea = (companion) => (companion.width || 0) * (companion.height || 0);
+/**
+ * Split a `<CompanionAds>` creative's variations into the logo and media slots.
+ *
+ * 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.
+ */
+const selectCompanions = (companions) => {
+    const logo = companions.length > 1
+        ? companions.find((companion) => companion.width === LOGO_COMPANION_WIDTH && companion.height === LOGO_COMPANION_HEIGHT)
+        : undefined;
+    if (!logo) {
+        return { logo: undefined, media: companions[0] };
+    }
+    const media = companions
+        .filter((companion) => companion !== logo)
+        .sort((a, b) => companionArea(a) - companionArea(b))
+        .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.
+ */
+const buildAdData = (parsedVAST, order) => {
+    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');
+        return undefined;
+    }
+    const extension = validAd.extensions.find((ext) => ext.attributes.type.startsWith('streamlayer'))?.children[0];
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error
+    const parsedExtension = parseVastExtension(extension);
+    const creative = getCreative(validAd);
+    const mediaFileUrl = getMediaFileUrl(creative);
+    const companions = getCompanions(validAd);
+    const { logo, media: mediaCompanion } = selectCompanions(companions);
+    const nonLinear = getNonLinear(validAd);
+    const clickThrough = getClickThrough(creative) || nonLinear?.clickUrl || mediaCompanion?.clickUrl;
+    log.info({
+        order,
+        adId: validAd.id,
+        title: validAd.title || undefined,
+        found: {
+            linear: !!creative,
+            mediaFile: mediaFileUrl || undefined,
+            nonLinear: nonLinear ? `${nonLinear.width}x${nonLinear.height}` : undefined,
+            companions: companions.map((item) => `${item.width}x${item.height}`),
+        },
+        selected: {
+            logo: logo ? { size: `${logo.width}x${logo.height}`, url: logo.imageUrl } : undefined,
+            media: mediaCompanion
+                ? { size: `${mediaCompanion.width}x${mediaCompanion.height}`, url: mediaCompanion.imageUrl }
+                : undefined,
+            clickThrough: !!clickThrough,
+        },
+    }, 'vast ad parsed');
+    return {
+        creative,
+        order,
+        mediaFileUrl,
+        companion: companions[0],
+        logo,
+        mediaCompanion,
+        nonLinear,
+        clickThrough,
+        title: validAd.title || undefined,
+        description: validAd.description || undefined,
+        ad: validAd,
+        extension: parsedExtension,
+        raw: parsedVAST,
+    };
+};
+/** Path of the self-hosted Prebid Server OpenRTB auction endpoint. */
+const PREBID_AUCTION_PATH = '/openrtb2/auction';
+/**
+ * A Prebid link points at our Prebid Server auction endpoint (staging:
+ * `https://prebid.next.streamlayer.io/openrtb2/auction`) rather than at a VAST tag.
+ * Detected by path so both staging and production hosts match.
+ */
+const isPrebidUrl = (url) => url.pathname.endsWith(PREBID_AUCTION_PATH);
+/** Unique per-auction request id — Prebid responses are never cached/reused (RFC §5). */
+const createRequestId = () => `sl-web-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+/**
+ * Build the OpenRTB request body for a single video auction. Placement config is
+ * carried on the Prebid link's query string so the consumer-facing interface stays a
+ * single URL string:
+ * - `configId` → `imp.ext.prebid.storedrequest.id` (production stored request).
+ * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
+ * - `test=1` → top-level `test` flag.
+ * - `w` / `h` → video dimensions (default 1920×1080).
+ */
+const buildAuctionRequest = (url) => {
+    const params = url.searchParams;
+    const width = Number(params.get('w')) || 1920;
+    const height = Number(params.get('h')) || 1080;
+    const configId = params.get('configId') ?? params.get('config_id') ?? undefined;
+    const storedAuctionResponse = params.get('storedauctionresponse') ?? undefined;
+    const prebid = {};
+    if (storedAuctionResponse) {
+        prebid.storedauctionresponse = { id: storedAuctionResponse };
+    }
+    if (configId) {
+        prebid.storedrequest = { id: configId };
+    }
+    prebid.bidder = {
+        appnexus: { placementId: 13144370 },
+    };
+    const request = {
+        id: createRequestId(),
+        imp: [
+            {
+                id: '1',
+                video: {
+                    mimes: ['video/mp4'],
+                    protocols: [2, 3, 5, 6],
+                    w: width,
+                    h: height,
+                    placement: 1,
+                    linearity: 1,
+                },
+                ext: { prebid },
+            },
+        ],
+        site: { page: typeof location !== 'undefined' ? location.href : url.origin },
+        tmax: 500,
+    };
+    if (params.get('test') === '1') {
+        request.test = 1;
+    }
+    return request;
+};
+/**
+ * Run one Prebid Server auction and turn the winning inline VAST into an `AdStore`.
+ * 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 response = await fetch(prebidUrl.toString(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(buildAuctionRequest(prebidUrl)),
     });
+    if (!response.ok) {
+        throw new Error(`prebid auction failed with status ${response.status}`);
+    }
+    const auction = (await response.json());
+    const bids = (auction.seatbid ?? [])
+        .reduce((acc, seat) => acc.concat(seat.bid ?? []), [])
+        .filter((bid) => !!bid.adm)
+        // Highest price wins — the winner is order 0 (RFC §2).
+        .sort((a, b) => (b.price ?? 0) - (a.price ?? 0));
+    const parser = new DOMParser();
+    const loadedAds = await Promise.all(bids.map((bid, i) => {
+        const xmlDoc = parser.parseFromString(bid.adm, 'text/xml');
+        // A fresh `VASTParser` per bid isolates parser state, mirroring the fresh
+        // `VASTClient` per link in the tag flow. `resolveAll: true` follows any
+        // `VASTAdTagURI` wrapper chain the bid's inline VAST may still contain.
+        return (new VASTParser()
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            .parseVAST(xmlDoc, { resolveAll: true, wrapperLimit: 10, allowMultipleAds: true })
+            .then((parsedVAST) => buildAdData(parsedVAST, i))
+            .catch((err) => {
+            // A single failing bid must not drop the whole batch.
+            log.error(err, 'failed to parse prebid VAST');
+            return undefined;
+        }));
+    }));
+    const params = prebidUrl.searchParams;
+    const autoplay = params.get('vpa')?.replaceAll('?', '') !== 'click';
+    const muted = params.get('vpmute')?.replaceAll('?', '') === '1';
+    return {
+        ads: loadedAds.filter((d) => !!d),
+        autoplay,
+        muted,
+    };
 };
 export const externalAd = (instance) => {
-    return (gamUrl, $enabled, options) => instance.transport.nanoquery.createFetcherStore([gamUrl, $enabled], {
-        dedupeTime: options.prefetch ? options.refetchInterval : Infinity,
-        revalidateInterval: options.refetchInterval > 0 ? options.refetchInterval : 0,
+    return (gamUrl) => instance.transport.nanoquery.createFetcherStore([gamUrl], {
+        dedupeTime: Infinity,
+        revalidateInterval: 0,
         fetcher: async (adUrl) => {
             if (!adUrl || typeof adUrl !== 'string') {
                 throw new Error('ad url is empty');
             }
-            try {
-                const parsedVAST = await vastClient.get(adUrl);
-                const validAd = parsedVAST.ads.find((ads) => ads.creatives.length > 0);
-                if (validAd) {
-                    const parentId = validAd.id || '';
-                    const store = {
-                        id: '',
-                        parentId,
-                        url: adUrl,
-                        title: validAd.title || '',
-                        description: validAd.description || '',
-                    };
-                    log.debug(validAd, 'validAd');
-                    const linear = validAd.creatives.find((creative) => creative.type === 'linear');
-                    if (linear) {
-                        store.id = linear.adId || linear.id || parentId;
-                        log.debug(linear, 'linear');
-                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                        // @ts-ignore
-                        store.videoSrc = linear.mediaFiles?.find((mediaFile) => !!mediaFile.fileURL)?.fileURL;
-                    }
-                    const nonlinear = validAd.creatives.find((creative) => creative.type === 'nonlinear');
-                    if (nonlinear) {
-                        store.id = nonlinear.adId || nonlinear.id || parentId;
-                        log.debug(nonlinear, 'nonlinear');
-                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                        // @ts-ignore
-                        const staticResource = nonlinear.variations?.[0]?.staticResource;
-                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                        // @ts-ignore
-                        store.adUrl = nonlinear.variations?.[0]?.nonlinearClickThroughURLTemplate;
-                        if (staticResource) {
-                            await preloadImage(staticResource);
-                            store.imageSrc = staticResource;
-                        }
-                    }
-                    const companion = validAd.creatives.find((creative) => creative.type === 'companion');
-                    log.debug(companion, 'companion');
-                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                    // @ts-ignore
-                    const staticResource = companion?.variations?.[0]?.staticResources?.[0]?.url;
-                    if (staticResource) {
-                        await preloadImage(staticResource);
-                        store.sponsorSrc = staticResource;
-                    }
-                    if (store.imageSrc || store.videoSrc) {
-                        return store;
-                    }
+            const parsedAdUrl = (() => {
+                try {
+                    return new URL(adUrl);
+                }
+                catch {
+                    return undefined;
                 }
-                throw new Error('no_valid_ad');
+            })();
+            // 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);
             }
-            catch (err) {
-                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-                // @ts-expect-error
-                if (err.message !== 'no_valid_ad' && err.message !== 'ad url is empty') {
-                    console.error(err);
+            const generateUrl = gam(adUrl);
+            const generatedUrl = await generateUrl();
+            const noncedLink = generatedUrl?.url;
+            if (!noncedLink) {
+                throw new Error('ad url is not generated');
+            }
+            let links;
+            if (noncedLink.searchParams.get('output')?.replaceAll('?', '') === 'vmap') {
+                const response = await withTimeout(fetch(noncedLink.toString()), VAST_FETCH_TIMEOUT_MS);
+                if (!response) {
+                    throw new Error('vmap fetch timed out');
                 }
-                throw err;
+                const parser = new DOMParser();
+                const xmlStr = await response.text();
+                const xmlDoc = parser.parseFromString(xmlStr, 'text/xml');
+                const vmap = new VMAP(xmlDoc);
+                links = vmap.adBreaks.map((ad) => {
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-expect-error
+                    return ad.adSource.adTagURI.uri;
+                });
+            }
+            else {
+                links = [noncedLink.toString()];
             }
+            const loadedAds = await Promise.all(links.map((link, i) => {
+                // `resolveAll: true` makes the client follow every `VASTAdTagURI` wrapper chain
+                // (up to the default depth of 10) and resolve all Ads, merging wrapper-level
+                // Impression/tracking URLs into the inline Ad. The default (`resolveAll: false`)
+                // only resolves the first standalone Ad and defers wrappers/remaining Ads to
+                // `getNextAds()`, which this fetcher never calls. A fresh `VASTClient` per link
+                // isolates parser state so concurrent (VMAP) resolutions don't clobber each other.
+                return withTimeout(new VASTClient()
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-ignore
+                    .get(link, { resolveAll: true, wrapperLimit: 10, allowMultipleAds: true }), VAST_FETCH_TIMEOUT_MS)
+                    .then((parsedVAST) => {
+                    // `parsedVAST` is `undefined` when the resolution timed out (see `withTimeout`).
+                    if (!parsedVAST) {
+                        log.warn({ link, timeoutMs: VAST_FETCH_TIMEOUT_MS }, 'vast resolution timed out — treated as no-ad');
+                        return undefined;
+                    }
+                    return buildAdData(parsedVAST, i);
+                })
+                    .catch((err) => {
+                    // A single failing wrapper chain must not drop the whole batch.
+                    log.error(err, 'failed to resolve VAST');
+                    return undefined;
+                });
+            }));
+            const autoplay = noncedLink.searchParams.get('vpa')?.replaceAll('?', '') !== 'click';
+            const muted = noncedLink.searchParams.get('vpmute')?.replaceAll('?', '') === '1';
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-expect-error
+            const nonceManager = generatedUrl.manager;
+            return {
+                ads: loadedAds.filter((d) => !!d),
+                autoplay,
+                muted,
+                nonceManager,
+            };
         },
     });
 };

package/lib/units/external-pause-ad.d.ts

@@ -5,14 +5,46 @@ export type GAMStaticCore = {
     parentId: string;
     url: string;
     imageSrc?: string;
+    /**
+     * Linear MP4 from the VAST response → renders full-bleed `<video>` (SC-322).
+     * Only produced when the host asked for it via one of the `fullbleed-video*`
+     * values of `ExternalPauseAdOptions.template`; a `'default'` ad can never carry
+     * this field.
+     */
+    backgroundVideoSrc?: string;
     adUrl?: string;
     ad?: any;
     creative?: any;
     variation?: any;
 };
+/**
+ * Which VAST creative this request resolves, set by the host on
+ * `pauseAdExternalUrls[].template`:
+ * - `'default'` — static image (nonlinear → companion) → sidebar overlay.
+ * - `'fullbleed-video*'` — the **linear** creative's MP4 → full-screen video (SC-322).
+ *
+ * This is a resolution STRATEGY, not a renderer hint the fetcher may ignore. The
+ * `fullbleed-video` variants differ ONLY in the chrome the renderer draws around
+ * the video, so creative resolution treats them identically.
+ */
+export type PauseAdTemplate = 'default' | 'fullbleed-video' | 'fullbleed-video-center' | 'fullbleed-video-left';
+/**
+ * `indexOf` rather than `Array.prototype.includes`: this package ships to Chrome 32
+ * TV webviews and must stay ES5-compatible without a polyfill.
+ */
+export declare const isFullbleedVideoTemplate: (template?: PauseAdTemplate) => boolean;
 export type ExternalPauseAdOptions = {
     refetchInterval: number;
     prefetch: boolean;
     $enabled: boolean;
+    /**
+     * Creative-resolution strategy. Defaults to `'default'`.
+     *
+     * NOT reactive — it is part of the store's IDENTITY (see the composite Map key
+     * in `Advertisement.getExternalPauseAd`), not of its state. `$enabled` is the
+     * only reactive option here; `refetchInterval`/`prefetch` are read once at
+     * store-creation time.
+     */
+    template?: PauseAdTemplate;
 };
 export declare const externalPauseAd: (instance: StreamLayerContext) => (gamUrl: string, $enabled: ReturnType<typeof createSingleStore<boolean>>, options: ExternalPauseAdOptions) => import("@nanostores/query").FetcherStore<GAMStaticCore | undefined, any>;

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

@@ -1,7 +1,62 @@
+// Pins the `@dailymotion/vast-client` → `@types/vast-client` shim: TypeDoc
+// compiles this file through dependent packages' programs, whose tsconfig
+// `include` does not cover this package's ambient declarations.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
 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';
+const FULLBLEED_VIDEO_TEMPLATES = [
+    'fullbleed-video',
+    'fullbleed-video-center',
+    'fullbleed-video-left',
+];
+/**
+ * `indexOf` rather than `Array.prototype.includes`: this package ships to Chrome 32
+ * TV webviews and must stay ES5-compatible without a polyfill.
+ */
+export const isFullbleedVideoTemplate = (template) => !!template && FULLBLEED_VIDEO_TEMPLATES.indexOf(template) !== -1;
+const MP4_MIME = 'video/mp4';
+// Programmatic spec (Index Exchange): bitrate window for a linear pause-ad MP4.
+const MIN_BITRATE = 5000;
+const MAX_BITRATE = 40000;
+const TARGET_WIDTH = 1920;
+const TARGET_HEIGHT = 1080;
+const bitrateDistanceToWindow = (bitrate) => {
+    if (bitrate < MIN_BITRATE)
+        return MIN_BITRATE - bitrate;
+    if (bitrate > MAX_BITRATE)
+        return bitrate - MAX_BITRATE;
+    return 0;
+};
+const resolutionDistanceToTarget = (file) => Math.abs((file.width ?? 0) - TARGET_WIDTH) + Math.abs((file.height ?? 0) - TARGET_HEIGHT);
+/**
+ * Pick the best linear MP4 from a VAST creative's media files: prefer the
+ * highest bitrate inside the 5000–40000 kbps window; if none qualify, pick the
+ * one closest to the window. Ties break toward 1920×1080. Returns `undefined`
+ * when no MP4 is present so image-only VAST keeps working.
+ */
+const selectMp4MediaFile = (mediaFiles = []) => {
+    const mp4s = (mediaFiles ?? []).filter((file) => !!file?.fileURL && file.mimeType === MP4_MIME);
+    if (mp4s.length === 0) {
+        return undefined;
+    }
+    const inWindow = mp4s.filter((file) => {
+        const bitrate = file.bitrate ?? 0;
+        return bitrate >= MIN_BITRATE && bitrate <= MAX_BITRATE;
+    });
+    if (inWindow.length > 0) {
+        return [...inWindow].sort((a, b) => {
+            const byBitrate = (b.bitrate ?? 0) - (a.bitrate ?? 0);
+            return byBitrate !== 0 ? byBitrate : resolutionDistanceToTarget(a) - resolutionDistanceToTarget(b);
+        })[0];
+    }
+    return [...mp4s].sort((a, b) => {
+        const byWindow = bitrateDistanceToWindow(a.bitrate ?? 0) - bitrateDistanceToWindow(b.bitrate ?? 0);
+        return byWindow !== 0 ? byWindow : resolutionDistanceToTarget(a) - resolutionDistanceToTarget(b);
+    })[0];
+};
 const vastClient = new VASTClient();
 const log = createLogger('ui:gam-static');
 const preloadImage = (src) => {
@@ -13,9 +68,42 @@ const preloadImage = (src) => {
     });
 };
 export const externalPauseAd = (instance) => {
-    return (gamUrl, $enabled, options) => instance.transport.nanoquery.createFetcherStore([gamUrl, $enabled], {
+    return (gamUrl, $enabled, options) => 
+    // `template` MUST be a key part: nanoquery joins parts with `''` (no separator)
+    // and its `cache` Map is global per transport, so two stores that produce the
+    // same joined key share data AND cross-trigger each other's `revalidate()`.
+    // The `tpl:` prefix keeps the url/template boundary unambiguous. Never let this
+    // part be `undefined` — an undefined part nulls the WHOLE key and permanently
+    // suspends fetching (that is exactly how `$enabled: false` works).
+    instance.transport.nanoquery.createFetcherStore([gamUrl, $enabled, `tpl:${options.template ?? 'default'}`], {
         dedupeTime: options.prefetch ? options.refetchInterval : Infinity,
         revalidateInterval: options.refetchInterval > 0 ? options.refetchInterval : 0,
+        // A creative-type mismatch is DETERMINISTIC: this tag returned no usable linear
+        // MP4 and retrying it can never change that, so cancel nanoquery's BACKOFF RETRY
+        // LOOP (any falsy return does) instead of re-hitting the ad server for the rest of
+        // the session — with the default `pauseAdDelay: 0` the store is enabled from mount.
+        // This only cancels the retry loop: `revalidateInterval` still re-runs the fetcher
+        // on its timer, and `Advertisement.getExternalPauseAd` forces a `revalidate()` on
+        // every `$enabled` false → true edge, so with `pauseAdDelay > 0` the tag is still
+        // re-requested on every pause.
+        // Transient failures (network, CORS, malformed XML, 5xx) still retry; the backoff
+        // below mirrors nanoquery's `defaultOnErrorRetry` so the two templates stay on the
+        // same curve. The jitter is not decorative — it spreads out retries that would
+        // otherwise fire in lockstep when the failure is correlated across stores/clients
+        // (ad-server 5xx, CORS), which the `pauseAdDelay: 0` prefetch-at-mount makes more
+        // likely.
+        // On `default` this is `undefined`, i.e. exactly as if the option were not passed —
+        // true as long as the shared nanoquery instance sets no global `onErrorRetry` (an
+        // explicit `undefined` DOES shadow a global one, and only then does nanoquery's
+        // destructuring default restore `defaultOnErrorRetry`).
+        onErrorRetry: isFullbleedVideoTemplate(options.template)
+            ? ({ error, retryCount }) => {
+                if (error instanceof Error && error.message === 'no_valid_ad') {
+                    return false;
+                }
+                return ~~((Math.random() + 0.5) * (1 << Math.min(retryCount, 8))) * 2000;
+            }
+            : undefined,
         fetcher: async (adUrl) => {
             if (!adUrl || typeof adUrl !== 'string') {
                 throw new Error('ad url is empty');
@@ -25,11 +113,64 @@ export const externalPauseAd = (instance) => {
                 payload: {},
             });
             try {
-                const parsedVAST = await vastClient.get(adUrl);
-                const validAd = parsedVAST.ads.find((ads) => ads.creatives.length > 0);
+                // `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 });
+                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
+                // ad that satisfies the template and fall back to the first ad with any creative
+                // (which preserves the existing `no_valid_ad` error and event sequencing).
+                const validAd = isFullbleedVideoTemplate(template)
+                    ? (parsedVAST.ads.find((ad) => ad.creatives.some((creative) => creative.type === 'linear' &&
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        // @ts-ignore vast-client linear creative carries mediaFiles
+                        selectMp4MediaFile(creative.mediaFiles)?.fileURL)) ?? parsedVAST.ads.find((ads) => ads.creatives.length > 0))
+                    : parsedVAST.ads.find((ads) => ads.creatives.length > 0);
                 if (validAd) {
                     const parentId = validAd.id || '';
                     log.debug(validAd, 'validAd');
+                    // The HOST decides which creative wins (SC-322-2). `fullbleed-video` asks
+                    // for the linear MP4 explicitly, so it is resolved FIRST and never falls
+                    // back to a static image — the nonlinear/companion branches below `return`
+                    // early, so without this a VAST carrying BOTH an image and a linear MP4
+                    // (e.g. Google `single_ad_samples`) would never reach the linear creative.
+                    // `default` keeps the pre-SC-322 nonlinear → companion order below and can
+                    // never produce a video.
+                    if (isFullbleedVideoTemplate(template)) {
+                        const linear = validAd.creatives.find((creative) => creative.type === 'linear' &&
+                            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                            // @ts-ignore vast-client linear creative carries mediaFiles
+                            selectMp4MediaFile(creative.mediaFiles)?.fileURL);
+                        if (linear) {
+                            log.debug(linear, 'linear');
+                            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                            // @ts-ignore vast-client linear creative carries mediaFiles
+                            const mediaFile = selectMp4MediaFile(linear.mediaFiles);
+                            if (mediaFile?.fileURL) {
+                                const id = linear.adId || linear.id || parentId;
+                                eventBus.emit('exposedPauseAd', {
+                                    action: 'loaded',
+                                    payload: {
+                                        id,
+                                        parentId,
+                                    },
+                                });
+                                return {
+                                    id,
+                                    parentId,
+                                    url: adUrl,
+                                    backgroundVideoSrc: mediaFile.fileURL,
+                                    ad: validAd,
+                                    creative: linear,
+                                };
+                            }
+                        }
+                        // Host asked for full-bleed video and this VAST carries no usable linear
+                        // MP4 → fail closed so `ExposedPauseAd`'s error effect auto-closes the ad,
+                        // exactly like any other unusable VAST. See §5 of the brief.
+                        throw new Error('no_valid_ad');
+                    }
                     const nonlinear = validAd.creatives.find((creative) => creative.type === 'nonlinear');
                     if (nonlinear) {
                         const id = nonlinear.adId || nonlinear.id || parentId;