@streamlayer/feature-advertisement 1.0.0 → 1.1.1-rc.10.p6eb7304a

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

@@ -0,0 +1,50 @@
+import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import '@streamlayer/sdk-web-api';
+export type GAMStaticCore = {
+    id: string;
+    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", { with: { "resolution-mode": "import" } }).FetcherStore<GAMStaticCore | undefined, any>;

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

@@ -0,0 +1,259 @@
+'use strict';
+
+var sdkWebInterfaces = require('@streamlayer/sdk-web-interfaces');
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+require('@streamlayer/sdk-web-api');
+var vastClient$1 = require('@dailymotion/vast-client');
+var adMacros = require('./ad-macros.js');
+
+// 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" />
+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.
+ */
+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$1.VASTClient();
+const log = sdkWebLogger.createLogger('ui:gam-static');
+const preloadImage = (src) => {
+    return new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve(src);
+        image.onerror = () => reject();
+        image.src = src;
+    });
+};
+const externalPauseAd = (instance) => {
+    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');
+            }
+            sdkWebInterfaces.eventBus.emit('exposedPauseAd', {
+                action: 'load',
+                payload: {},
+            });
+            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).
+                // 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(adMacros.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
+                // 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;
+                                sdkWebInterfaces.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;
+                        log.debug(nonlinear, 'nonlinear');
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        // @ts-ignore
+                        const variation = nonlinear.variations?.[0];
+                        const staticResource = variation?.staticResource;
+                        const adUrlTemplate = variation?.nonlinearClickThroughURLTemplate;
+                        if (staticResource) {
+                            await preloadImage(staticResource);
+                            sdkWebInterfaces.eventBus.emit('exposedPauseAd', {
+                                action: 'loaded',
+                                payload: {
+                                    id,
+                                    parentId,
+                                },
+                            });
+                            return {
+                                id,
+                                parentId,
+                                url: adUrl,
+                                imageSrc: staticResource,
+                                adUrl: adUrlTemplate,
+                                ad: validAd,
+                                creative: nonlinear,
+                                variation,
+                            };
+                        }
+                    }
+                    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 variation = companion?.variations?.[0];
+                    const staticResource = variation?.staticResources?.[0]?.url;
+                    const adUrlTemplate = variation?.companionClickThroughURLTemplate;
+                    // `&& companion` is for TS narrowing only (companion.adId access below);
+                    // it is runtime-redundant since staticResource derives from companion.
+                    if (staticResource && companion) {
+                        const id = companion.adId || companion.id || parentId;
+                        await preloadImage(staticResource);
+                        sdkWebInterfaces.eventBus.emit('exposedPauseAd', {
+                            action: 'loaded',
+                            payload: {
+                                id,
+                                parentId,
+                            },
+                        });
+                        return {
+                            id,
+                            parentId,
+                            url: adUrl,
+                            imageSrc: staticResource,
+                            adUrl: adUrlTemplate,
+                            ad: validAd,
+                            creative: companion,
+                            variation,
+                        };
+                    }
+                }
+                throw new Error('no_valid_ad');
+            }
+            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);
+                }
+                throw err;
+            }
+        },
+    });
+};
+
+exports.externalPauseAd = externalPauseAd;
+exports.isFullbleedVideoTemplate = isFullbleedVideoTemplate;

package/lib/cjs/units/gam.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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;
+    sendPlaybackStart: () => void;
+    sendPlaybackEnd: () => void;
+};
+export type GamNonceResult = {
+    url: URL;
+    manager?: PalNonceManager;
+};
+export declare const gam: (rawUrl: string, adContainer?: HTMLDivElement, adTagParams?: AdTagParams) => (() => Promise<{
+    url: URL;
+}>) | (() => Promise<{
+    url: URL;
+    manager: PalNonceManager;
+} | undefined>);

package/lib/cjs/units/gam.js

@@ -0,0 +1,152 @@
+'use strict';
+
+var sdkWebStorage = require('@streamlayer/sdk-web-storage');
+var uuid = require('uuid');
+var adMacros = require('./ad-macros.js');
+
+const urlIsNotGam = (url) => {
+    return url.origin !== 'https://pubads.g.doubleclick.net';
+};
+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;
+};
+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 = adMacros.substituteAdTagMacros(rawUrl, adTagParams);
+    const parsedUrl = (() => {
+        try {
+            const parsedUrl = new URL(url);
+            return parsedUrl;
+        }
+        catch (_err) {
+            return undefined;
+        }
+    })();
+    // Non-GAM VAST/VMAP URLs carry no GAM ad-request params and need no PAL nonce, so
+    // resolve them directly. PAL is only required for pubads.g.doubleclick.net requests —
+    // raw-VAST consumers (e.g. injected sidebar / l-bar) must not depend on the Google PAL
+    // SDK being loaded, so this must run before touching `goog`.
+    if (parsedUrl && urlIsNotGam(parsedUrl)) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return { url: parsedUrl };
+        };
+    }
+    if (!parsedUrl) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return undefined;
+        };
+    }
+    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 = sdkWebStorage.safeLocalStorage().getItem('sl-device-id') || uuid.v4();
+            let sessionId = sdkWebStorage.safeSessionStorage().getItem('sl-ad-session-id');
+            if (!sessionId) {
+                sessionId = uuid.v4();
+                sdkWebStorage.safeSessionStorage().setItem('sl-ad-session-id', sessionId);
+            }
+            if (!uuid.validate(deviceId)) {
+                deviceId = uuid.v5(`https://${deviceId}`, uuid.v5.URL);
+            }
+            if (!parsedUrl.searchParams.get('url')) {
+                parsedUrl.searchParams.set('url', 'https://streamlayer.io');
+            }
+            if (!parsedUrl.searchParams.get('description_url')) {
+                parsedUrl.searchParams.set('description_url', 'https://streamlayer.io');
+            }
+            request.adWillAutoPlay = parsedUrl.searchParams.get('vpa') === 'auto';
+            request.adWillPlayMuted = parsedUrl.searchParams.get('vpmute') === '1';
+            request.continuousPlayback = true;
+            request.descriptionUrl = parsedUrl.searchParams.get('description_url');
+            request.iconsSupported = true;
+            request.sessionId = deviceId;
+            // Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1
+            request.supportedApiFrameworks = '2,7,9';
+            request.videoHeight = adContainer?.clientHeight ?? 0;
+            request.videoWidth = adContainer?.clientWidth ?? 0;
+            const nonceManager = await nonceLoader.loadNonceManager(request);
+            if (parsedUrl.searchParams.get('is_lat') === '[placeholder]') {
+                parsedUrl.searchParams.set('is_lat', '1');
+            }
+            if (parsedUrl.searchParams.get('rdid') === '[placeholder]') {
+                parsedUrl.searchParams.set('rdid', deviceId);
+            }
+            if (parsedUrl.searchParams.get('correlator') === '[placeholder]') {
+                parsedUrl.searchParams.set('correlator', sessionId);
+            }
+            parsedUrl.searchParams.set('wta', '1');
+            parsedUrl.searchParams.set('givn', nonceManager.getNonce());
+            return {
+                url: parsedUrl,
+                manager: nonceManager,
+            };
+        }
+        catch (adError) {
+            console.log('AdsManager could not be started', adError);
+            return undefined;
+        }
+    };
+    return generateUrl;
+};
+
+exports.gam = gam;

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

@@ -0,0 +1,26 @@
+import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+export interface VastCreative {
+    adName: string;
+    /**
+     * 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;
+    ctaLabel?: string;
+}
+interface VastNode {
+    name: string;
+    value: string | null;
+    attributes: Record<string, string>;
+    children: VastNode[];
+}
+export declare function parseVastExtension(root: VastNode): VastCreative | undefined;
+export {};

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

@@ -0,0 +1,56 @@
+'use strict';
+
+var interactive_common_pb = require('@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: interactive_common_pb.AdType.SIDE_BY_SIDE,
+};
+function parseVastExtension(root) {
+    if (!root) {
+        return undefined;
+    }
+    const child = (node, name) => node.children.find((c) => c.name === name);
+    const childrenByName = (node, name) => node.children.filter((c) => c.name === name);
+    const urlOf = (node) => child(node, 'Url')?.value ?? '';
+    const num = (v) => (v == null ? NaN : Number(v));
+    const adName = child(root, 'AdName')?.value ?? '';
+    const backgroundsNode = child(root, 'Backgrounds');
+    const backgrounds = backgroundsNode
+        ? childrenByName(backgroundsNode, 'Background').map((bg) => ({
+            orientation: bg.attributes.orientation,
+            width: num(bg.attributes.width),
+            height: num(bg.attributes.height),
+            type: bg.attributes.type,
+            url: urlOf(bg),
+        }))
+        : [];
+    const logosNode = child(root, 'Logos');
+    const logos = logosNode
+        ? childrenByName(logosNode, 'Logo').map((logo) => ({
+            role: logo.attributes.role,
+            width: num(logo.attributes.width),
+            height: num(logo.attributes.height),
+            type: logo.attributes.type,
+            url: urlOf(logo),
+        }))
+        : [];
+    const ctaNode = child(root, 'CTA');
+    const cta = {
+        label: ctaNode ? (child(ctaNode, 'Label')?.value ?? '') : '',
+        type: ctaNode ? (child(ctaNode, 'Type')?.value ?? '') : '',
+    };
+    return {
+        adName,
+        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,
+        ctaLabel: cta.label,
+    };
+}
+
+exports.parseVastExtension = parseVastExtension;

package/lib/cjs/units/pause-ad-card.d.ts

@@ -0,0 +1,49 @@
+import { type Question } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+export type PauseAdLayout = 'left' | 'center' | 'image';
+/**
+ * Which full-bleed renderer draws the card. Absent === `'standard'`.
+ *
+ * - `'standard'` — the Standard/Image pause ad (promotion card).
+ * - `'insight'` — the Insight Pause Ad (factoid card): sponsor logo, heading and a
+ *   single-column body beside an optional media image (SC-353).
+ */
+export type PauseAdKind = 'standard' | 'insight';
+/** How the Insight media image is cropped — mirrors Studio's Media switcher. */
+export type PauseAdMediaMode = 'image' | 'circle' | 'none';
+/**
+ * Insight body cap (SC-353). Studio enforces it on the Additional Content field; the
+ * SDK clamps as well so a card authored before the limit landed cannot overflow the
+ * screen — the format is explicitly designed to fit without scrolling.
+ */
+export declare const INSIGHT_BODY_MAX_LENGTH = 600;
+export type PauseAdCard = {
+    id: string;
+    parentId: string;
+    /** Optional: a video-only card (programmatic VAST, SC-322) has no image. */
+    backgroundImageSrc?: string;
+    /** Linear MP4 from VAST → renders full-bleed `<video>` instead of the image (SC-322). */
+    backgroundVideoSrc?: string;
+    layout: PauseAdLayout;
+    isInteractive: boolean;
+    logoSrc?: string;
+    title?: string;
+    description?: string;
+    ctaLabel?: string;
+    ctaUrl?: string;
+    qrCodeUrl?: string;
+    qrCodeLabel?: string;
+    /** Absent === `'standard'`. */
+    kind?: PauseAdKind;
+    /** Insight only: the Media image (`FactoidOptions.image`). */
+    mediaSrc?: string;
+    /** Insight only: how `mediaSrc` is cropped. */
+    mediaMode?: PauseAdMediaMode;
+};
+/**
+ * The `pauseAdList` response, shaped for the renderers: keep the cards the SDK has chrome for,
+ * turn each into a `PauseAdCard`, drop the ones that cannot be drawn.
+ *
+ * Pure on purpose — `pause-ad.ts` owns the store and the transport, this owns the card shapes,
+ * and only this half needs unit tests.
+ */
+export declare const parsePauseAdCards: (questions: Question[]) => PauseAdCard[];