@streamlayer/feature-advertisement 1.2.0 → 1.2.1-rc.11.pd437c711

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

@@ -0,0 +1,136 @@
+'use strict';
+
+var interactive_common_pb = require('@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.
+ */
+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 === interactive_common_pb.NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE) {
+        return undefined;
+    }
+    return sponsor?.useGeneralLogo === interactive_common_pb.UseGeneralLogo.ENABLED
+        ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
+        : sponsor?.logo || sponsor?.centerLogo || undefined;
+};
+const MEDIA_MODE_BY_PROTO = {
+    [interactive_common_pb.FactoidMediaMode.IMAGE]: 'image',
+    [interactive_common_pb.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 ?? interactive_common_pb.PauseAdLayout.UNSET;
+    const layout = layoutProto === interactive_common_pb.PauseAdLayout.CENTER ? 'center' : layoutProto === interactive_common_pb.PauseAdLayout.IMAGE ? 'image' : 'left';
+    const isInteractive = promotionOptions?.buttonType === interactive_common_pb.PromotionButtonType.SEND_TO_USER;
+    const hasQr = pauseAdOptions?.qrCode === interactive_common_pb.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 === interactive_common_pb.UserAccountInfo.PHONE;
+        ctaUrl = isPhone ? 'sendToPhone:' : 'sendToEmail:';
+        ctaLabel = isPhone ? 'Send info to account phone' : 'Send info to account email';
+    }
+    const logoSrc = optionsSponsor?.logoPosition === interactive_common_pb.NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE
+        ? undefined
+        : optionsSponsor?.useGeneralLogo === interactive_common_pb.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 === interactive_common_pb.CardFormat.FULL_BLEED || question.format === interactive_common_pb.CardFormat.UNSET;
+    }
+    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
+    return promotionOptions?.format === interactive_common_pb.PromotionFormat.FULL_BLEED || question.format === interactive_common_pb.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.
+ */
+const parsePauseAdCards = (questions) => questions
+    .filter(isFullBleedPauseAd)
+    .map(parsePauseAdCard)
+    .filter((card) => card !== null);
+
+exports.INSIGHT_BODY_MAX_LENGTH = INSIGHT_BODY_MAX_LENGTH;
+exports.parsePauseAdCards = parsePauseAdCards;

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

@@ -0,0 +1,16 @@
+import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import '@streamlayer/sdk-web-api';
+import '@streamlayer/sdk-web-core/store';
+import { type PauseAdCard } from './pause-ad-card.js';
+export type PauseAdListOptions = {
+    refetchInterval: number;
+    $enabled: boolean;
+};
+export declare const pauseAdListStore: (instance: StreamLayerContext) => ($enabled: ReturnType<typeof createSingleStore<boolean>>, options: PauseAdListOptions) => {
+    $list: import("@nanostores/query", { with: { "resolution-mode": "import" } }).FetcherStore<PauseAdCard[], any>;
+    $index: import("nanostores", { with: { "resolution-mode": "import" } }).PreinitializedWritableAtom<number> & object;
+    next: () => void;
+    reset: () => void;
+    getCurrent: () => PauseAdCard | undefined;
+};
+export type PauseAdStore = ReturnType<ReturnType<typeof pauseAdListStore>>;

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

@@ -0,0 +1,52 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+var nanostores = require('nanostores');
+require('@streamlayer/sdk-web-api');
+require('@streamlayer/sdk-web-core/store');
+var interactive_feed_pb = require('@streamlayer/sl-eslib/interactive/feed/interactive.feed_pb');
+var pauseAdCard = require('./pause-ad-card.js');
+
+const log = sdkWebLogger.createLogger('advertisement:pause-ad');
+const pauseAdListStore = (instance) => {
+    const $slStreamId = instance.stores.slStreamId.getAtomStore();
+    return ($enabled, options) => {
+        const { client, queryKey } = instance.transport.createPromiseClient(interactive_feed_pb.Feed, {
+            method: 'pauseAdList',
+            params: [$slStreamId, $enabled],
+        });
+        const $list = instance.transport.nanoquery.createFetcherStore(queryKey, {
+            dedupeTime: 0,
+            revalidateInterval: options.refetchInterval > 0 ? options.refetchInterval : 0,
+            fetcher: async (_, __, eventId, isEnabled) => {
+                if (!eventId || typeof eventId !== 'string' || !isEnabled) {
+                    return [];
+                }
+                log.debug({ eventId }, 'fetching pause ad list');
+                const res = await client.pauseAdList({ eventId });
+                const cards = pauseAdCard.parsePauseAdCards(res.data ?? []);
+                log.debug({ count: cards.length }, 'parsed %d fullbleed pause ad cards');
+                return cards;
+            },
+        });
+        const $index = nanostores.atom(0);
+        const next = () => {
+            const list = $list.get().data;
+            if (!list?.length)
+                return;
+            $index.set(($index.get() + 1) % list.length);
+        };
+        const reset = () => {
+            $index.set(0);
+        };
+        const getCurrent = () => {
+            const list = $list.get().data;
+            if (!list?.length)
+                return undefined;
+            return list[$index.get()];
+        };
+        return { $list, $index, next, reset, getCurrent };
+    };
+};
+
+exports.pauseAdListStore = pauseAdListStore;

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

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

package/lib/cjs/units/sponsor-logo.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * Sponsor-logo slot selection for a **feature** ad unit (Insight, Prediction and Trivia today;
+ * Poll is the same shape and is a separate ticket).
+ *
+ * Deliberately NOT `selectCompanions` (`./external-ad.ts`). That rule is the *display*-unit rule:
+ * it promotes a companion to the logo slot only when the tag ships an exact 300x75 `<Companion>`
+ * next to at least one other. A feature ad-unit tag is typically a **single** creative — often a
+ * lone NonLinear `<StaticResource>` — where the ad IS the logo, which is exactly the shape that
+ * rule returns nothing for. `selectCompanions` stays untouched: SC-335's three shipped units
+ * depend on its exact behaviour and impression counts are billing-visible.
+ *
+ * Mirrors iOS `SLRVASTSlotRole.logo` + `SLRVASTAssetPool`
+ * (`StreamLayerSDK/Frameworks/SLRGAMFramework/Sources/VASTSlotFiller/`):
+ *
+ * - **Images only.** A video-only tag yields no logo. `<Icon>` is never projected — icons hang off
+ *   the `<Linear>` creative, which this selector does not look at. A `<StaticResource>` the tag
+ *   declares as a non-image `creativeType` is skipped too, so a companion that lists a script
+ *   before its image still resolves to the image (see `isImageResource`).
+ * - **Origin-agnostic.** A lone NonLinear `<StaticResource>` is as valid as a `<Companion>`.
+ * - **Aspect-dominant** toward 1:1: the smallest `|log(assetAspect) - log(1)|` wins, ties broken by
+ *   larger area, then by higher pixel density. Aspect is a *preference, never a filter* — the only
+ *   hard constraint is the asset kind, so a badly shaped asset still wins if it is the only one.
+ * - Assets whose intrinsic size the tag never declared rank last, but still beat nothing.
+ *
+ * The module also hosts iOS's second logo role, `SLRVASTSlotRole.cardLogo` (`selectCardLogo`) —
+ * the same ranking narrowed to `<Companion>` origins, for the hero-card display units.
+ */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
+/** `width`/`height` are XML attributes (strings at runtime); 0 and NaN both mean "not declared". */
+const toSize = (value) => {
+    const size = Number(value);
+    return size > 0 ? size : undefined;
+};
+/**
+ * VAST 4 `<CompanionAds pxratio>`; `@dailymotion/vast-client` defaults it to `'1'` and the
+ * `@types/vast-client` shim does not declare it, hence the loose read.
+ */
+const toPxRatio = (variation) => {
+    return Number(variation.pxratio) || 1;
+};
+/**
+ * `<StaticResource creativeType>`. The slot draws an `<img>`, so a resource the tag declares as
+ * anything else — the `application/x-shockwave-flash` or `application/javascript` creative a
+ * companion may list beside its image — must never fill it: it would swap the proto logo for a
+ * broken image AND still fire an impression for something nobody ever saw.
+ *
+ * An ABSENT type is not a rejection. VAST requires the attribute but real GAM image companions
+ * routinely omit it, and this module's only hard constraint is the asset kind, so an undeclared
+ * type stays a candidate. `@dailymotion/vast-client` writes `0` for a missing NonLinear
+ * `creativeType` and `null` for a missing companion one; both are falsy, hence the single guard.
+ */
+const isImageResource = (creativeType) => {
+    if (!creativeType) {
+        return true;
+    }
+    return String(creativeType).toLowerCase().indexOf('image/') === 0;
+};
+/**
+ * The first resource a `<Companion>` declares as an image (or leaves undeclared). NOT
+ * `staticResources[0]`: the order in the tag is the advertiser's, and a non-image resource listed
+ * first must not hide a usable image behind it.
+ */
+const pickCompanionImage = (variation) => {
+    const resources = variation.staticResources || [];
+    for (let i = 0; i < resources.length; i++) {
+        const resource = resources[i];
+        if (resource && resource.url && isImageResource(resource.creativeType)) {
+            return resource.url;
+        }
+    }
+    return undefined;
+};
+/** Distance from square on a log scale, so 2:1 and 1:2 are equally far from 1:1. */
+const aspectDistance = (asset) => {
+    if (!asset.width || !asset.height) {
+        // Unknown intrinsic size — rank last, but still a candidate.
+        return Infinity;
+    }
+    return Math.abs(Math.log(asset.width / asset.height));
+};
+const collectAssetsFrom = (ad) => {
+    const assets = [];
+    for (let i = 0; i < ad.creatives.length; i++) {
+        const creative = ad.creatives[i];
+        if (creative.type === 'companion') {
+            const companionCreative = creative;
+            const variations = companionCreative.variations || [];
+            for (let j = 0; j < variations.length; j++) {
+                const variation = variations[j];
+                const imageUrl = variation && pickCompanionImage(variation);
+                if (imageUrl) {
+                    assets.push({
+                        imageUrl,
+                        clickUrl: variation.companionClickThroughURLTemplate ?? undefined,
+                        width: toSize(variation.width),
+                        height: toSize(variation.height),
+                        origin: 'companion',
+                        creative: companionCreative,
+                        variation,
+                    });
+                }
+            }
+            continue;
+        }
+        if (creative.type === 'nonlinear') {
+            const nonLinearCreative = creative;
+            const variations = nonLinearCreative.variations || [];
+            for (let j = 0; j < variations.length; j++) {
+                const variation = variations[j];
+                // `type` is where the parser puts a `<NonLinear>`'s `creativeType`, and it is written last
+                // from the `<StaticResource>` element, so it describes `staticResource` whenever that is
+                // set. An HTML- or iframe-typed variation carries no `staticResource` and drops out here.
+                const imageUrl = variation && isImageResource(variation.type) ? variation.staticResource : undefined;
+                if (imageUrl) {
+                    assets.push({
+                        imageUrl,
+                        // 6.4.2 emits `nonlinearClickThroughURLTemplate` (lower-case `l`); the shim declares
+                        // the upper-case spelling. The runtime one is authoritative — see `getNonLinear`.
+                        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                        // @ts-ignore
+                        clickUrl: variation.nonlinearClickThroughURLTemplate ?? undefined,
+                        width: toSize(variation.width),
+                        height: toSize(variation.height),
+                        origin: 'nonlinear',
+                        creative: nonLinearCreative,
+                        variation,
+                    });
+                }
+            }
+        }
+    }
+    return assets;
+};
+/**
+ * The shared ranking both roles use: aspect distance from 1:1, ties broken by larger area, then by
+ * higher pixel density. Aspect is a preference, never a filter — the best of a bad set still wins.
+ */
+const rankBest = (assets) => {
+    if (!assets.length) {
+        return undefined;
+    }
+    let best = assets[0];
+    let bestDistance = aspectDistance(best);
+    let bestArea = (best.width || 0) * (best.height || 0);
+    let bestPxRatio = toPxRatio(best.variation);
+    for (let i = 1; i < assets.length; i++) {
+        const asset = assets[i];
+        const distance = aspectDistance(asset);
+        const area = (asset.width || 0) * (asset.height || 0);
+        const pxRatio = toPxRatio(asset.variation);
+        const wins = distance !== bestDistance ? distance < bestDistance : area !== bestArea ? area > bestArea : pxRatio > bestPxRatio;
+        if (wins) {
+            best = asset;
+            bestDistance = distance;
+            bestArea = area;
+            bestPxRatio = pxRatio;
+        }
+    }
+    return best;
+};
+/**
+ * Pick the image a parsed VAST ad offers for a sponsor-logo slot, or `undefined` when it offers
+ * none (a video-only tag, or an empty response). A caller that gets `undefined` must fall back to
+ * its own proto/Studio logo rather than suppressing the card.
+ */
+const collectAssets = (ad) => collectAssetsFrom(ad);
+const selectSponsorLogo = (ad) => rankBest(collectAssetsFrom(ad));
+/**
+ * iOS `SLRVASTSlotRole.cardLogo` — the sponsor logo of a **hero card** (1:1 / 2:1 / Picture in
+ * Picture / Side-by-Side / Sponsor Frame). Same 1:1 aspect-dominant ranking as `.logo`, plus the
+ * one constraint that distinguishes the two roles:
+ *
+ * - **`requiredOrigin: .companion`.** A NonLinear image is a hero creative, never a logo. iOS's
+ *   reason: a leftover hero-type asset — a second `<NonLinear>` overlay, or a stray image still in
+ *   the pool after the hero role claimed its own — must never leak into the card's logo slot,
+ *   where it would render at logo size as an unreadable smudge of the advertiser's key art.
+ *   `nonlinear_full` is the fixture that pins it: `.logo` takes the 500x500 NonLinear, `.cardLogo`
+ *   must take the 200x200 `<Companion>`.
+ * - **`exclude`** mirrors iOS's **greedy** `pool.select([hero, .cardLogo])`: roles resolve in array
+ *   order and an asset a role claims is removed from the pool for every later role. We have no
+ *   pool object, so the caller passes the assets the hero already claimed and they are filtered
+ *   out here by `imageUrl`.
+ */
+const selectCardLogo = (ad, exclude) => {
+    const claimed = (exclude || []).map((item) => item?.imageUrl).filter((url) => !!url);
+    return rankBest(collectAssetsFrom(ad).filter((asset) => asset.origin === 'companion' && claimed.indexOf(asset.imageUrl) === -1));
+};
+
+exports.collectAssets = collectAssets;
+exports.selectCardLogo = selectCardLogo;
+exports.selectSponsorLogo = selectSponsorLogo;

package/lib/cjs/units/ssai-ad-break.d.ts

@@ -0,0 +1,21 @@
+import { createSingleStore } from '@streamlayer/sdk-web-interfaces';
+import type { SsaiCreative } from './ssai-creative.js';
+/**
+ * 'ending' = the ad's window closes within the detector's lead (~0.5s): the
+ * overlay's cue to play its closing animation so it completes AT the boundary
+ * rather than after it. Beacons are unaffected — playback still owns those.
+ */
+export type SsaiAdBreakStatus = 'detecting' | 'ready' | 'ending' | 'ended';
+export type SsaiAdBreakState = {
+    creativeId: string;
+    creative?: SsaiCreative;
+    status: SsaiAdBreakStatus;
+    startMs: number;
+    durationSec: number;
+};
+export type SsaiAdBreakStore = ReturnType<typeof createSingleStore<SsaiAdBreakState | null>>;
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+export declare const createSsaiAdBreakStore: () => SsaiAdBreakStore;

package/lib/cjs/units/ssai-ad-break.js

@@ -0,0 +1,11 @@
+'use strict';
+
+var sdkWebInterfaces = require('@streamlayer/sdk-web-interfaces');
+
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+const createSsaiAdBreakStore = () => sdkWebInterfaces.createSingleStore(null);
+
+exports.createSsaiAdBreakStore = createSsaiAdBreakStore;

package/lib/cjs/units/ssai-creative.d.ts

@@ -0,0 +1,89 @@
+import { DEFAULT_CREATIVE_API_BASE, type SsaiCreativeProvider } from './ssai-providers.js';
+export { DEFAULT_CREATIVE_API_BASE };
+export type SsaiTrackingEvent = {
+    event: string;
+    url: string;
+};
+export type SsaiCompanion = {
+    staticResource: string;
+    width: number;
+    height: number;
+    clickThrough?: string;
+    /** Beacons fired when the companion is clicked. May be empty. */
+    clickTracking: string[];
+};
+/**
+ * Lifecycle events the SDK fires beacons for, in the order they occur.
+ * `impression` is separate: it is tied to the overlay actually being rendered,
+ * not to playback position — see `SsaiCreativeCache.fireImpression`.
+ */
+export type SsaiProgressEvent = 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete';
+export type SsaiCreative = {
+    creativeId: string;
+    advertiser: string;
+    title: string;
+    iconUrl?: string;
+    clickThroughUrl?: string;
+    trackingEvents: SsaiTrackingEvent[];
+    companion?: SsaiCompanion;
+};
+/**
+ * Per-instance cache + impression-firing wrapper around a SsaiCreativeProvider.
+ * Caches resolved creatives by creativeId so repeated active-ad polls and pod
+ * repeats don't refetch. In-flight fetches are cancellable via AbortController.
+ */
+export declare class SsaiCreativeCache {
+    private provider;
+    private cache;
+    private inflight;
+    constructor(provider: SsaiCreativeProvider);
+    /**
+     * The already-resolved creative, or undefined — synchronous on purpose: a
+     * prefetched creative lets the ad break flip straight to 'ready' with no
+     * async gap (which the UI would render as a blink between two ads of a pod).
+     */
+    peek: (creativeId: string) => SsaiCreative | undefined;
+    resolve: (creativeId: string) => Promise<SsaiCreative>;
+    /**
+     * Cancel an in-flight fetch (e.g. the break ended before it resolved).
+     */
+    cancel: (creativeId: string) => void;
+    /**
+     * Fire the impression for a creative. Delegates to the provider's
+     * `fireImpression` when present, otherwise the shared default (first
+     * trackingEvent named 'impression' via sendBeacon/fetch). Called once per
+     * visible appearance of the bar (the UI dedupes the ~250ms active-poll so a
+     * single continuous appearance fires exactly one impression). Each genuine pod
+     * insertion of the same creative is a distinct impression and re-fires.
+     */
+    fireImpression: (creative: SsaiCreative) => void;
+    /**
+     * Fire the impression for an already-resolved creativeId. No-op if the
+     * creative isn't cached yet (the bar only renders once resolved, so by the
+     * time the UI calls this the creative is present).
+     */
+    fireImpressionById: (creativeId: string) => void;
+    /**
+     * Fire a lifecycle / click beacon. Delegates to the provider's `fireTracking`
+     * when it defines one, otherwise fires every matching `trackingEvents` URL.
+     */
+    fireTracking: (creative: SsaiCreative, event: string) => void;
+    /**
+     * Fire a beacon for a creativeId that may still be resolving.
+     *
+     * `start` in particular lands the instant the break opens, which is usually
+     * BEFORE the metadata request has come back — dropping it would silently lose
+     * the first beacon of every ad. Resolution is already in flight by then and
+     * `resolve` returns that same promise, so this attaches to it rather than
+     * issuing a second request. A creative that never resolves fires nothing,
+     * which is the correct outcome: there are no URLs to fire.
+     */
+    fireTrackingById: (creativeId: string, event: string) => void;
+    /**
+     * Fire the companion's `clickTracking` beacons. Separate from
+     * {@link fireTracking} because these live on the companion, not in
+     * `trackingEvents` — a provider's `fireTracking` override has no say over them.
+     */
+    fireCompanionClickById: (creativeId: string) => void;
+    destroy: () => void;
+}