@streamlayer/feature-advertisement 1.0.0 → 1.1.1-rc.1342

package/lib/classic/units/ssai-preload.js

@@ -0,0 +1,68 @@
+import 'core-js/modules/es.array.iterator.js';
+import 'core-js/modules/es.promise.js';
+import 'core-js/modules/esnext.iterator.constructor.js';
+import 'core-js/modules/esnext.iterator.filter.js';
+import 'core-js/modules/web.dom-collections.iterator.js';
+import { createLogger } from '@streamlayer/sdk-web-logger/classic';
+
+const log = createLogger('ssai:preload');
+/**
+ * How long the overlay is willing to wait for artwork. A slow or dead image host
+ * must never hold the bar back — the ad is already playing, and a bar that shows
+ * late is worse than one that shows without its logo (the logo is hidden on error
+ * anyway). Warming the browser cache is the goal; blocking is not.
+ */
+const DEFAULT_PRELOAD_TIMEOUT_MS = 2000;
+/**
+ * Fetch images into the browser cache and resolve once they are all settled, or
+ * once `timeoutMs` elapses — whichever comes first. Never rejects: a creative
+ * whose artwork fails is still a creative worth showing.
+ */
+const preloadImages = (urls, timeoutMs = DEFAULT_PRELOAD_TIMEOUT_MS) => {
+  const targets = urls.filter(url => !!url);
+  // `Image` is absent in SSR/worker contexts; there is nothing to warm there.
+  if (targets.length === 0 || typeof Image === 'undefined') {
+    return Promise.resolve();
+  }
+  return new Promise(resolve => {
+    let settled = false;
+    let remaining = targets.length;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      log.debug({
+        remaining
+      }, 'ssai preload timed out, showing anyway');
+      finish();
+    }, timeoutMs);
+    const one = () => {
+      remaining -= 1;
+      if (remaining <= 0) {
+        finish();
+      }
+    };
+    for (const url of targets) {
+      const image = new Image();
+      image.onload = one;
+      image.onerror = one;
+      image.src = url;
+    }
+  });
+};
+/**
+ * Warm every image the creative carries — the overlay's brand logo, and the
+ * companion banner for hosts that render one — so the bar fades in complete
+ * rather than popping its artwork in a beat later.
+ */
+const preloadCreativeAssets = (creative, timeoutMs) => {
+  var _creative$companion;
+  return preloadImages([creative.iconUrl, (_creative$companion = creative.companion) === null || _creative$companion === void 0 ? void 0 : _creative$companion.staticResource], timeoutMs);
+};
+
+export { DEFAULT_PRELOAD_TIMEOUT_MS, preloadCreativeAssets, preloadImages };

package/lib/classic/units/ssai-providers.js

@@ -0,0 +1,289 @@
+import { asyncToGenerator as _asyncToGenerator, objectSpread2 as _objectSpread2 } from '../_virtual/_rollupPluginBabelHelpers.js';
+import 'core-js/modules/es.error.cause.js';
+import 'core-js/modules/es.array.iterator.js';
+import 'core-js/modules/es.promise.js';
+import 'core-js/modules/esnext.iterator.constructor.js';
+import 'core-js/modules/esnext.iterator.filter.js';
+import 'core-js/modules/esnext.iterator.find.js';
+import 'core-js/modules/esnext.iterator.map.js';
+import 'core-js/modules/web.dom-collections.iterator.js';
+import 'core-js/modules/web.dom-exception.stack.js';
+import { createLogger } from '@streamlayer/sdk-web-logger/classic';
+import { VASTClient } from '@dailymotion/vast-client';
+
+const log = createLogger('ssai:provider');
+const DEFAULT_CREATIVE_API_BASE = 'https://hls.next.streamlayer.io/api/creatives/';
+/**
+ * Shared low-level beacon helper. Prefers `navigator.sendBeacon` and falls back
+ * to a no-cors `fetch`. Used by the default impression path and available to
+ * providers that fire URL-based tracking pixels.
+ */
+const fireBeacon = url => {
+  try {
+    if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+      navigator.sendBeacon(url);
+    } else {
+      void fetch(url, {
+        mode: 'no-cors'
+      }).catch(error => {
+        log.warn(error, 'ssai beacon failed');
+      });
+    }
+  } catch (error) {
+    log.warn(error, 'ssai beacon failed');
+  }
+};
+const resolveAdvertiser = (advertiser, title) => {
+  if (advertiser) {
+    return advertiser;
+  }
+  if (title) {
+    return title;
+  }
+  return 'Ad';
+};
+const buildCreativeUrl = (base, creativeId) => {
+  const normalizedBase = base.endsWith('/') ? base : `${base}/`;
+  return `${normalizedBase}${encodeURIComponent(creativeId)}`;
+};
+const mapApiResponse = raw => {
+  const trackingEvents = Array.isArray(raw.trackingEvents) ? raw.trackingEvents.filter(entry => Boolean((entry === null || entry === void 0 ? void 0 : entry.event) && (entry === null || entry === void 0 ? void 0 : entry.url))).map(entry => ({
+    event: entry.event,
+    url: entry.url
+  })) : [];
+  const rawCompanion = Array.isArray(raw.companions) ? raw.companions.find(entry => !!(entry !== null && entry !== void 0 && entry.staticResource)) : undefined;
+  const companion = rawCompanion !== null && rawCompanion !== void 0 && rawCompanion.staticResource ? {
+    staticResource: rawCompanion.staticResource,
+    width: Number(rawCompanion.width) || 0,
+    height: Number(rawCompanion.height) || 0,
+    clickThrough: rawCompanion.clickThrough,
+    clickTracking: Array.isArray(rawCompanion.clickTracking) ? rawCompanion.clickTracking.filter(url => typeof url === 'string' && !!url) : []
+  } : undefined;
+  return {
+    creativeId: raw.creativeId,
+    advertiser: resolveAdvertiser(raw.advertiser, raw.title),
+    title: raw.title || resolveAdvertiser(raw.advertiser, raw.title),
+    iconUrl: raw.iconUrl || undefined,
+    clickThroughUrl: raw.clickThroughUrl || undefined,
+    trackingEvents,
+    companion
+  };
+};
+/**
+ * Fire every tracking event with the given name, and report how many went out.
+ *
+ * ALL matches, not the first: the creative contract states that a creative may
+ * repeat an `event` value to carry several URLs, and that consumers must not
+ * assume uniqueness. Today's payloads carry one URL per event, so this is not a
+ * change in what goes on the wire — it just stops being wrong the day a server
+ * sends two.
+ */
+const fireTrackingEvents = (creative, event) => {
+  const matches = creative.trackingEvents.filter(entry => entry.event === event);
+  for (const match of matches) {
+    fireBeacon(match.url);
+  }
+  return matches.length;
+};
+/**
+ * Shared default impression behavior: fire the `impression` tracking events.
+ * Used by the StreamLayer provider and as the fallback in
+ * {@link SsaiCreativeCache} when a provider doesn't override `fireImpression`.
+ * Exported so both call sites share one definition.
+ */
+const fireDefaultImpression = creative => {
+  fireTrackingEvents(creative, 'impression');
+};
+/**
+ * StreamLayer's internal creative provider. Resolves creatives from the JSON
+ * creative API (`GET {creativeApiBase}{encodeURIComponent(creativeId)}`) and
+ * fires impressions from the `'impression'` tracking event via `sendBeacon`.
+ */
+const createStreamLayerProvider = (config = {}) => {
+  var _config$creativeApiBa;
+  const creativeApiBase = (_config$creativeApiBa = config.creativeApiBase) !== null && _config$creativeApiBa !== void 0 ? _config$creativeApiBa : DEFAULT_CREATIVE_API_BASE;
+  return {
+    id: 'streamlayer',
+    resolve: function () {
+      var _ref = _asyncToGenerator(function* (creativeId, signal) {
+        const url = buildCreativeUrl(creativeApiBase, creativeId);
+        const response = yield fetch(url, {
+          signal
+        });
+        if (!response.ok) {
+          throw new Error(`creative request failed: ${response.status}`);
+        }
+        const raw = yield response.json();
+        return mapApiResponse(_objectSpread2(_objectSpread2({}, raw), {}, {
+          creativeId: raw.creativeId || creativeId
+        }));
+      });
+      return function resolve(_x, _x2) {
+        return _ref.apply(this, arguments);
+      };
+    }(),
+    fireImpression: fireDefaultImpression
+  };
+};
+const buildQuortexUrl = (base, tenantName, adId) => {
+  // Deliberately string concatenation rather than `URL`/`URLSearchParams`: this
+  // package ships to 2016-era TV engines (see the chrome-32 classic build).
+  const separator = base.indexOf('?') === -1 ? '?' : '&';
+  const tenant = tenantName ? `TenantName=${encodeURIComponent(tenantName)}&` : '';
+  return `${base}${separator}${tenant}adID=${encodeURIComponent(adId)}&info=1`;
+};
+/**
+ * Quortex / Synamedia DAI ad metadata provider.
+ *
+ * `GET {adApiBase}?TenantName={tenantName}&adID={adId}&info=1` (the `TenantName`
+ * part omitted when `adApiBase` already carries it) — the ad id comes
+ * from the manifest's `X-AD-ID` DATERANGE attribute (see `ssai-detector.ts`, which
+ * reconstructs the ad window from the tracking-marker burst those tags form).
+ *
+ * The response is byte-compatible with the StreamLayer creative API, so the same
+ * `mapApiResponse` normalizes both.
+ *
+ * Known limitation: impressions fire the `impression` tracking event from the API
+ * response, not the per-session beacon the manifest carries in `X-AD-URL`. The two
+ * differ in `trackingid`/`USERID`, so Quortex-side attribution will see the
+ * generic id rather than the viewer's session until the manifest beacons are
+ * plumbed through to the provider.
+ */
+const createQuortexProvider = (config = {}) => {
+  const {
+    adApiBase,
+    tenantName
+  } = config;
+  if (!adApiBase) {
+    // Loud, but not thrown: this runs inside the host's render effect via
+    // `startSsaiMonitoring`, and taking the app down over a config typo is worse
+    // than an overlay that never appears and says why.
+    log.error({
+      adApiBase,
+      tenantName
+    }, 'quortex provider requires `adApiBase`');
+  }
+  return {
+    id: 'quortex',
+    resolve: function () {
+      var _ref2 = _asyncToGenerator(function* (adId, signal) {
+        if (!adApiBase) {
+          throw new Error('quortex provider is missing `adApiBase`');
+        }
+        const response = yield fetch(buildQuortexUrl(adApiBase, tenantName, adId), {
+          signal
+        });
+        if (!response.ok) {
+          throw new Error(`quortex creative request failed: ${response.status}`);
+        }
+        const raw = yield response.json();
+        return mapApiResponse(_objectSpread2(_objectSpread2({}, raw), {}, {
+          creativeId: raw.creativeId || adId
+        }));
+      });
+      return function resolve(_x3, _x4) {
+        return _ref2.apply(this, arguments);
+      };
+    }(),
+    fireImpression: fireDefaultImpression
+  };
+};
+// --- VAST provider ---------------------------------------------------------
+const mapVastResponse = /*#__PURE__*/function () {
+  var _ref3 = _asyncToGenerator(function* (creativeId, signal) {
+    var _validAd$advertiser$f;
+    const vastClient = new VASTClient();
+    const parsedVAST = yield vastClient.get(creativeId, {
+      timeout: 8000
+    });
+    if (signal.aborted) {
+      throw new DOMException('aborted', 'AbortError');
+    }
+    const validAd = parsedVAST.ads.find(ad => ad.creatives.length > 0);
+    if (!validAd) {
+      throw new Error('no_valid_ad');
+    }
+    const advertiserValue = Array.isArray(validAd.advertiser) ? (_validAd$advertiser$f = validAd.advertiser.find(entry => !!(entry !== null && entry !== void 0 && entry.value))) === null || _validAd$advertiser$f === void 0 ? void 0 : _validAd$advertiser$f.value : undefined;
+    const advertiser = resolveAdvertiser(advertiserValue, validAd.title || undefined);
+    let iconUrl;
+    let clickThroughUrl;
+    let companion;
+    for (const creative of validAd.creatives) {
+      if (creative.type === 'linear') {
+        var _linear$icons, _linear$videoClickThr;
+        const linear = creative;
+        iconUrl = iconUrl || ((_linear$icons = linear.icons) === null || _linear$icons === void 0 || (_linear$icons = _linear$icons.find(icon => !!(icon !== null && icon !== void 0 && icon.staticResource))) === null || _linear$icons === void 0 ? void 0 : _linear$icons.staticResource) || undefined;
+        clickThroughUrl = clickThroughUrl || ((_linear$videoClickThr = linear.videoClickThroughURLTemplate) === null || _linear$videoClickThr === void 0 ? void 0 : _linear$videoClickThr.url);
+      }
+      if (creative.type === 'companion') {
+        var _creative$variations, _variation$staticReso;
+        const variation = (_creative$variations = creative.variations) === null || _creative$variations === void 0 ? void 0 : _creative$variations[0];
+        const staticResource = variation === null || variation === void 0 || (_variation$staticReso = variation.staticResources) === null || _variation$staticReso === void 0 || (_variation$staticReso = _variation$staticReso[0]) === null || _variation$staticReso === void 0 ? void 0 : _variation$staticReso.url;
+        if (staticResource && !companion) {
+          var _variation$companionC, _variation$companionC2;
+          companion = {
+            staticResource,
+            width: Number(variation === null || variation === void 0 ? void 0 : variation.width) || 0,
+            height: Number(variation === null || variation === void 0 ? void 0 : variation.height) || 0,
+            clickThrough: variation === null || variation === void 0 || (_variation$companionC = variation.companionClickThroughURLTemplate) === null || _variation$companionC === void 0 ? void 0 : _variation$companionC.url,
+            clickTracking: ((_variation$companionC2 = variation === null || variation === void 0 ? void 0 : variation.companionClickTrackingURLTemplates) !== null && _variation$companionC2 !== void 0 ? _variation$companionC2 : []).map(entry => entry === null || entry === void 0 ? void 0 : entry.url).filter(url => !!url)
+          };
+        }
+      }
+    }
+    return {
+      creativeId,
+      advertiser,
+      title: validAd.title || advertiser,
+      iconUrl,
+      clickThroughUrl,
+      trackingEvents: [],
+      companion
+    };
+  });
+  return function mapVastResponse(_x5, _x6) {
+    return _ref3.apply(this, arguments);
+  };
+}();
+/**
+ * Maps a VAST tag into the normalized SsaiCreative shape.
+ *
+ * Note: `fireImpression` is intentionally left to the shared default for now.
+ * Proper VAST impression/tracking wiring through `VASTTracker` is a documented
+ * follow-up; it requires retaining the parsed ad/tracker per creative.
+ */
+const createVastProvider = (_config = {}) => {
+  return {
+    id: 'vast',
+    resolve: mapVastResponse
+  };
+};
+/** Built-in provider factories keyed by name. */
+const BUILTIN_PROVIDERS = {
+  streamlayer: config => createStreamLayerProvider(config),
+  quortex: config => createQuortexProvider(config),
+  vast: () => createVastProvider()
+};
+const isProviderInstance = option => {
+  return typeof option === 'object' && typeof option.resolve === 'function';
+};
+/**
+ * Resolve a {@link SsaiProviderOption} into a concrete {@link SsaiCreativeProvider}.
+ * Defaults to the StreamLayer provider (using `fallbackConfig`) when no option is
+ * supplied.
+ */
+const resolveProvider = (option, fallbackConfig) => {
+  var _option$config;
+  if (!option) {
+    return createStreamLayerProvider(fallbackConfig);
+  }
+  if (typeof option === 'string') {
+    return BUILTIN_PROVIDERS[option](fallbackConfig);
+  }
+  if (isProviderInstance(option)) {
+    return option;
+  }
+  return BUILTIN_PROVIDERS[option.name]((_option$config = option.config) !== null && _option$config !== void 0 ? _option$config : fallbackConfig);
+};
+
+export { BUILTIN_PROVIDERS, DEFAULT_CREATIVE_API_BASE, createQuortexProvider, createStreamLayerProvider, createVastProvider, fireBeacon, fireDefaultImpression, fireTrackingEvents, resolveProvider };

package/lib/classic/units/vast-tracker.js

@@ -0,0 +1,77 @@
+import { VASTTracker } from '@dailymotion/vast-client';
+
+/**
+ * One place that constructs a `VASTTracker`.
+ *
+ * Every StreamLayer surface that reports VAST beacons — the GAM video player, both pause-ad
+ * renderers and the Standard Ad sidebar — needs the same `(ad, creative, variation)` triple, and
+ * each was assembling it by hand behind its own `@ts-ignore`. The parsed shapes those triples
+ * come from (`AdData` / `AdCompanion` / `AdNonLinear`) are defined in this package, so the
+ * mapping belongs here too.
+ *
+ * Deliberately *only* construction: when a beacon may fire, and how a surface de-duplicates its
+ * impression, stays with that surface. Those policies differ on purpose (per-ad-id in module
+ * scope for the sidebar, per component instance for the pause ads, per tracker identity for the
+ * player) and they are billing-visible, so collapsing them here would silently change counts.
+ */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
+const createVastTracker = ({
+  ad,
+  creative,
+  variation
+}) =>
+// The first argument is the `VASTClient` the tracker may update; every surface here drives
+// playback itself and only wants the beacons, so it is always `null`.
+//
+// The type shim declares the 3rd argument as `VastCreativeLinear` and the 4th as another
+// *creative*. At runtime `vast-client` accepts any creative in the 3rd and expects the
+// `<Companion>` / `<NonLinear>` *variation* in the 4th. The casts encode that runtime contract
+// once here rather than at every call site.
+new VASTTracker(null, ad, creative, variation);
+/**
+ * A tracker for a single `<Companion>`. A `<CompanionAds>` creative has no creative-level
+ * `<TrackingEvents>` — each variation owns its own `creativeView` — so a companion is reported
+ * through its own tracker. `undefined` when the companion was parsed without them (nothing to
+ * report against).
+ */
+const createCompanionTracker = (ad, companion) => companion.creative && companion.variation ? createVastTracker({
+  ad,
+  creative: companion.creative,
+  variation: companion.variation
+}) : undefined;
+/**
+ * The creative a parsed ad reports its impression / playback beacons through, in the order the
+ * shells draw them: the `<Linear>` creative first, then the `<NonLinear>` still, then — for a tag
+ * whose only creative is `<CompanionAds>` — the companion that was actually drawn.
+ *
+ * `drawnCompanion` is a parameter rather than `adData.companion` because only the rendering shell
+ * knows which companion reached the screen, and reporting one that did not is a false view.
+ */
+const resolveVastTrackerTarget = (adData, drawnCompanion) => {
+  // `AdData.creative` is not optional in the type but `getCreative` can return nothing: a
+  // programmatic tag does not have to carry a `<Linear>` creative.
+  if (adData.creative) {
+    return {
+      ad: adData.ad,
+      creative: adData.creative
+    };
+  }
+  if (adData.nonLinear) {
+    return {
+      ad: adData.ad,
+      creative: adData.nonLinear.creative,
+      variation: adData.nonLinear.variation
+    };
+  }
+  if (drawnCompanion !== null && drawnCompanion !== void 0 && drawnCompanion.creative && drawnCompanion.variation) {
+    return {
+      ad: adData.ad,
+      creative: drawnCompanion.creative,
+      variation: drawnCompanion.variation
+    };
+  }
+  return undefined;
+};
+
+export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget };

package/lib/index.d.ts

@@ -6,7 +6,8 @@ declare module '@streamlayer/sdk-web-interfaces' {
 }
 export { type ExternalAdStore, type ExternalPauseAdStore, type SsaiMonitorOptions } from './advertisement';
 export { type GAMStaticCore, type PauseAdTemplate, isFullbleedVideoTemplate } from './units/external-pause-ad';
-export { type PauseAdCard, type PauseAdStore } from './units/pause-ad';
+export { INSIGHT_BODY_MAX_LENGTH, type PauseAdCard, type PauseAdKind, type PauseAdMediaMode, } from './units/pause-ad-card';
+export { type PauseAdStore } from './units/pause-ad';
 export { type AdStore, type AdData, type AdCompanion, type AdNonLinear } from './units/external-ad';
 export { gam, type GamNonceResult, type PalNonceManager } from './units/gam';
 export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, type VastTrackerTarget, } from './units/vast-tracker';

package/lib/index.js

@@ -1,5 +1,11 @@
 import { Advertisement } from './advertisement';
 export { isFullbleedVideoTemplate } from './units/external-pause-ad';
+// Card shapes come straight from the pure module rather than through `units/pause-ad`. NOT a bundle
+// guarantee for barrel consumers — this file value-imports `Advertisement` on line 3, which imports
+// the store module anyway, and the package declares no `sideEffects: false`. What it does buy: the
+// unit spec and any deep importer get the card shapes without the store, and dropping the
+// `export *` keeps `units/pause-ad` from silently re-exporting `parsePauseAdCards`.
+export { INSIGHT_BODY_MAX_LENGTH, } from './units/pause-ad-card';
 export { gam } from './units/gam';
 export { createCompanionTracker, createVastTracker, resolveVastTrackerTarget, } from './units/vast-tracker';
 export { DEFAULT_CREATIVE_API_BASE, } from './units/ssai-creative';

package/lib/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[];

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

@@ -0,0 +1,130 @@
+import { CardFormat, FactoidMediaMode, NotificationSponsorLogoMode, PauseAdLayout as PauseAdLayoutProto, PromotionButtonType, PromotionFormat, QRCode, UseGeneralLogo, UserAccountInfo, } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+/**
+ * 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 const INSIGHT_BODY_MAX_LENGTH = 600;
+/**
+ * Sponsor logo for a factoid card. Same General-tab opt-in as the promotion path below,
+ * but the logo lives on `question.promotion.sponsor` (a factoid card carries no
+ * `PromotionOptions`) and Studio writes the uploaded file to `logo`, not `centerLogo`.
+ *
+ * `logo` therefore WINS over `centerLogo`: the latter is an optional field carried over from the
+ * notification/header surfaces, so a card that kept a stale `centerLogo` from an earlier revision
+ * would otherwise render it instead of the Insight logo the author just uploaded.
+ */
+const resolveInsightSponsorLogo = (question) => {
+    const sponsor = question.promotion?.sponsor;
+    if (sponsor?.logoPosition === NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE) {
+        return undefined;
+    }
+    return sponsor?.useGeneralLogo === UseGeneralLogo.ENABLED
+        ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
+        : sponsor?.logo || sponsor?.centerLogo || undefined;
+};
+const MEDIA_MODE_BY_PROTO = {
+    [FactoidMediaMode.IMAGE]: 'image',
+    [FactoidMediaMode.CIRCLE]: 'circle',
+};
+/**
+ * Insight Pause Ad, Full Bleed (SC-353). A factoid card, so none of the promotion
+ * plumbing above applies: the heading is the question subject, the body is
+ * `FactoidOptions.body`, and the sponsor logo comes off `question.promotion.sponsor`.
+ *
+ * `FACTOID_MEDIA_MODE_VIDEO` is deliberately treated as "no media": the full-bleed
+ * format has no player chrome and no way to start playback, unlike the sidebar variant.
+ */
+const parseInsightPauseAdCard = (question) => {
+    const factoidOptions = question.options?.options.case === 'factoid' ? question.options.options.value : undefined;
+    if (!factoidOptions) {
+        return null;
+    }
+    const mediaMode = MEDIA_MODE_BY_PROTO[factoidOptions.mode] ?? 'none';
+    const body = factoidOptions.body.slice(0, INSIGHT_BODY_MAX_LENGTH);
+    return {
+        id: question.id,
+        parentId: question.eventId || question.id,
+        // `landscapeUrl` ONLY. `portraitUrl` keeps stale artwork from earlier revisions of the
+        // card that Studio no longer shows in its Background Image slot, so falling back to it
+        // paints a background the author has already removed. Unlike the standard card, an
+        // Insight one renders fine with no background at all — its copy is the ad.
+        backgroundImageSrc: question.backgroundImage?.landscapeUrl || undefined,
+        kind: 'insight',
+        layout: 'left',
+        isInteractive: false,
+        logoSrc: resolveInsightSponsorLogo(question),
+        title: question.subject || undefined,
+        description: body || undefined,
+        mediaSrc: mediaMode === 'none' ? undefined : factoidOptions.image || undefined,
+        mediaMode,
+    };
+};
+const parsePauseAdCard = (question) => {
+    if (question.options?.options.case === 'factoid') {
+        return parseInsightPauseAdCard(question);
+    }
+    const backgroundImageSrc = question.backgroundImage?.landscapeUrl;
+    if (!backgroundImageSrc) {
+        return null;
+    }
+    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
+    const pauseAdOptions = promotionOptions?.pauseAdOptions;
+    const optionsSponsor = promotionOptions?.sponsor;
+    const layoutProto = pauseAdOptions?.layout ?? PauseAdLayoutProto.UNSET;
+    const layout = layoutProto === PauseAdLayoutProto.CENTER ? 'center' : layoutProto === PauseAdLayoutProto.IMAGE ? 'image' : 'left';
+    const isInteractive = promotionOptions?.buttonType === PromotionButtonType.SEND_TO_USER;
+    const hasQr = pauseAdOptions?.qrCode === QRCode.QR_CODE_ENABLED && !!pauseAdOptions?.qrCodeUrl;
+    let ctaLabel;
+    let ctaUrl;
+    if (isInteractive && promotionOptions?.buttonOptions.case === 'sendToUserOptions') {
+        const accountInfo = promotionOptions.buttonOptions.value.userAccountInfo;
+        const isPhone = accountInfo === UserAccountInfo.PHONE;
+        ctaUrl = isPhone ? 'sendToPhone:' : 'sendToEmail:';
+        ctaLabel = isPhone ? 'Send info to account phone' : 'Send info to account email';
+    }
+    const logoSrc = optionsSponsor?.logoPosition === NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE
+        ? undefined
+        : optionsSponsor?.useGeneralLogo === UseGeneralLogo.ENABLED
+            ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
+            : optionsSponsor?.centerLogo || undefined;
+    return {
+        id: question.id,
+        parentId: question.eventId || question.id,
+        backgroundImageSrc,
+        layout,
+        logoSrc,
+        title: promotionOptions?.banner?.title || undefined,
+        description: promotionOptions?.banner?.body || undefined,
+        isInteractive,
+        ctaLabel: ctaLabel || undefined,
+        ctaUrl: ctaUrl || undefined,
+        qrCodeUrl: hasQr ? (pauseAdOptions?.qrCodeUrl ?? undefined) : undefined,
+        qrCodeLabel: hasQr ? (pauseAdOptions?.qrCodeLabel ?? undefined) : undefined,
+    };
+};
+/**
+ * Which cards from `pauseAdList` the SDK can actually draw. Both renderers are full bleed; a
+ * Sidebar-format pause ad has no chrome yet and is skipped.
+ */
+const isFullBleedPauseAd = (question) => {
+    if (question.options?.options.case === 'factoid') {
+        // Insight Pause Ad (SC-353). Studio does not write `CardFormat` on these cards yet
+        // (SLW-7062), so an UNSET format is taken as Full Bleed — the only Insight pause-ad chrome
+        // the SDK has. An explicit Sidebar stays out. Drop the UNSET arm once Studio sets the field.
+        return question.format === CardFormat.FULL_BLEED || question.format === CardFormat.UNSET;
+    }
+    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
+    return promotionOptions?.format === PromotionFormat.FULL_BLEED || question.format === CardFormat.FULL_BLEED;
+};
+/**
+ * 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 const parsePauseAdCards = (questions) => questions
+    .filter(isFullBleedPauseAd)
+    .map(parsePauseAdCard)
+    .filter((card) => card !== null);

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

@@ -1,24 +1,7 @@
 import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
 import '@streamlayer/sdk-web-api';
 import '@streamlayer/sdk-web-core/store';
-export type PauseAdLayout = 'left' | 'center' | 'image';
-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;
-};
+import { type PauseAdCard } from './pause-ad-card';
 export type PauseAdListOptions = {
     refetchInterval: number;
     $enabled: boolean;