@streamlayer/feature-advertisement 1.1.1-rc.1350 → 1.1.1-rc.3.pda7fd93b

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

@@ -4,6 +4,7 @@ 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
@@ -118,7 +119,12 @@ const externalPauseAd = (instance) => {
             try {
                 // `resolveAll: true` follows every `VASTAdTagURI` wrapper chain and resolves all
                 // Ads (the default only resolves the first standalone Ad and stops at the wrapper).
-                const parsedVAST = await vastClient.get(adUrl, { resolveAll: true });
+                // Pause-ad tags do not go through `gam()`, so fill the macros here — with the host's values
+                // as they are NOW, since this fetcher re-runs on every pause. The store key stays the
+                // configured url: `ExposedPauseAd` compares against it.
+                const parsedVAST = await vastClient.get(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

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

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

package/lib/cjs/units/gam.js

@@ -2,20 +2,69 @@
 
 var sdkWebStorage = require('@streamlayer/sdk-web-storage');
 var uuid = require('uuid');
+var adMacros = require('./ad-macros.js');
 
-/**
- * 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.
- */
 const urlIsNotGam = (url) => {
     return url.origin !== 'https://pubads.g.doubleclick.net';
 };
-const gam = (url, adContainer) => {
+const palScriptUrl = 'https://imasdk.googleapis.com/pal/sdkloader/pal.js';
+const getPal = () => {
+    // @ts-expect-error Google PAL is supplied by the host or the script loader below.
+    return typeof goog === 'undefined' ? undefined : goog.pal;
+};
+let palReady;
+const ensurePal = async () => {
+    if (getPal()) {
+        return;
+    }
+    if (!palReady) {
+        palReady = new Promise((resolve, reject) => {
+            if (typeof document === 'undefined') {
+                reject(new Error('Google PAL requires a browser document'));
+                return;
+            }
+            const existing = document.querySelector(`script[src="${palScriptUrl}"]`);
+            const script = existing || document.createElement('script');
+            const finish = (error) => {
+                clearTimeout(timeout);
+                script.removeEventListener('load', onLoad);
+                script.removeEventListener('error', onError);
+                if (error) {
+                    if (!existing) {
+                        script.remove();
+                    }
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            const onLoad = () => finish(getPal() ? undefined : new Error('Google PAL did not initialize'));
+            const onError = () => finish(new Error('Google PAL failed to load'));
+            const timeout = setTimeout(() => finish(new Error('Google PAL loading timed out')), 10000);
+            script.addEventListener('load', onLoad);
+            script.addEventListener('error', onError);
+            if (!existing) {
+                script.async = true;
+                script.src = palScriptUrl;
+                document.head.appendChild(script);
+            }
+        }).catch((error) => {
+            palReady = undefined;
+            throw error;
+        });
+    }
+    await palReady;
+    palReady = undefined;
+};
+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);
@@ -35,20 +84,19 @@ const gam = (url, adContainer) => {
             return { url: parsedUrl };
         };
     }
-    // @ts-expect-error goog is injected by the externally-loaded Google PAL SDK
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const pal = (typeof goog === 'undefined' ? undefined : goog.pal);
-    if (!pal || !parsedUrl) {
+    if (!parsedUrl) {
         // eslint-disable-next-line require-await
         return async () => {
             return undefined;
         };
     }
-    const consentSettings = new pal.ConsentSettings();
-    consentSettings.allowStorage = false;
-    const nonceLoader = new pal.NonceLoader(consentSettings);
     const generateUrl = async () => {
         try {
+            await ensurePal();
+            const pal = getPal();
+            const consentSettings = new pal.ConsentSettings();
+            consentSettings.allowStorage = false;
+            const nonceLoader = new pal.NonceLoader(consentSettings);
             const parsedUrl = new URL(url);
             const request = new pal.NonceRequest();
             let deviceId = sdkWebStorage.safeLocalStorage().getItem('sl-device-id') || uuid.v4();

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

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

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

@@ -2,6 +2,10 @@
 
 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,
 };
@@ -41,7 +45,7 @@ function parseVastExtension(root) {
     };
     return {
         adName,
-        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name] || interactive_common_pb.AdType.SIDE_BY_SIDE,
+        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name],
         landscapeBackground: backgrounds.find((b) => b.orientation === 'landscape')?.url,
         portraitBackground: backgrounds.find((b) => b.orientation === 'portrait')?.url,
         sponsorLogo: logos.find((l) => l.role === 'header')?.url,

package/lib/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-detector.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+var ssaiLog = require('./ssai-log.js');
 
 const log = sdkWebLogger.createLogger('ssai:detector');
 const RANGE_EXPIRY_MS = 10 * 60 * 1000;
@@ -491,16 +492,32 @@ const createSsaiDetector = (options) => {
         : videoRef && manifestUrl
             ? 'manifest-poll'
             : 'none';
-    const recordDebugEvent = (type, detail, programMs) => {
-        debugEvents.push({
-            wallMs: Date.now(),
-            programMs: programMs !== undefined ? programMs : currentProgramTimeMs(),
-            type,
-            detail,
-        });
+    /**
+     * The `[label]` a detector event's log line opens with — what KIND of thing
+     * happened, for a reader scanning a window: a manifest tag came in (`hls`), a
+     * break edge fired (`break`), or playback crossed a tracking marker (`beacon`).
+     */
+    const eventLabel = (type) => {
+        if (type.indexOf('progress:') === 0)
+            return 'beacon';
+        if (type.indexOf('discovered') !== -1 || type === 'range-dropped')
+            return 'hls';
+        return 'break';
+    };
+    /**
+     * One call per detector event, feeding both consumers at once: the capped
+     * ring buffer behind `getDebugSnapshot()` and the `ssaiq` narrative logger.
+     * `data` is whatever the detector already holds for the event — the parsed
+     * range, marker or break window — so a log reader sees exactly what the
+     * detector acted on, with no second parse of the manifest for its benefit.
+     */
+    const recordDebugEvent = (type, detail, programMs, data) => {
+        const at = programMs !== undefined ? programMs : currentProgramTimeMs();
+        debugEvents.push({ wallMs: Date.now(), programMs: at, type, detail });
         if (debugEvents.length > DEBUG_EVENTS_MAX) {
             debugEvents.splice(0, debugEvents.length - DEBUG_EVENTS_MAX);
         }
+        ssaiLog.ssaiq.info({ ...data, programMs: at }, `[${eventLabel(type)}] ${type}${detail ? ` ${detail}` : ''}`);
     };
     const getVideo = () => player?.media ?? video ?? null;
     // Memoized view over the three marker maps. `updateActiveAd` polls 4×/s and
@@ -550,7 +567,6 @@ const createSsaiDetector = (options) => {
                     }
                     seenDroppedKeys.add(entry.key);
                     recordDebugEvent('range-dropped', entry.detail);
-                    log.warn({ detail: entry.detail }, 'ssai DATERANGE dropped');
                 }
                 continue;
             }
@@ -558,7 +574,7 @@ const createSsaiDetector = (options) => {
                 const existing = rangesById.get(entry.range.id);
                 if (!existing) {
                     changed = true;
-                    recordDebugEvent('range-discovered', `${entry.range.creativeId} ${debugClock(entry.range.startMs)}+${entry.range.durationSec}s`);
+                    recordDebugEvent('range-discovered', `${entry.range.creativeId} ${debugClock(entry.range.startMs)}+${entry.range.durationSec}s`, undefined, { range: entry.range });
                     notifyAdDiscovered(entry.range.creativeId);
                 }
                 else if (existing.startMs !== entry.range.startMs || existing.endMs !== entry.range.endMs) {
@@ -569,7 +585,7 @@ const createSsaiDetector = (options) => {
             else if (entry.kind === 'marker') {
                 if (!seenMarkerAdIds.has(entry.marker.adId)) {
                     seenMarkerAdIds.add(entry.marker.adId);
-                    recordDebugEvent('marker-ad-discovered', `${entry.marker.adId} ${entry.marker.event}@${debugClock(entry.marker.timeMs)}`);
+                    recordDebugEvent('marker-ad-discovered', `${entry.marker.adId} ${entry.marker.event}@${debugClock(entry.marker.timeMs)}`, undefined, { marker: entry.marker });
                     notifyAdDiscovered(entry.marker.adId);
                 }
                 const existing = markersById.get(entry.marker.id);
@@ -582,7 +598,7 @@ const createSsaiDetector = (options) => {
                 const existing = adBreaksById.get(entry.window.id);
                 if (!existing) {
                     changed = true;
-                    recordDebugEvent('adbreak-discovered', `${debugClock(entry.window.startMs)}-${debugClock(entry.window.endMs)}`);
+                    recordDebugEvent('adbreak-discovered', `${debugClock(entry.window.startMs)}-${debugClock(entry.window.endMs)}`, undefined, { window: entry.window });
                 }
                 else if (existing.startMs !== entry.window.startMs || existing.endMs !== entry.window.endMs) {
                     changed = true;

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

@@ -0,0 +1,16 @@
+import { type Logger } from '@streamlayer/sdk-web-logger';
+/**
+ * `ssaiq` — the SSAI ad NARRATIVE log: one line per thing that happens to a
+ * server-stitched ad, in the order it happens. The manifest tag the playout
+ * published, the metadata round trip it triggers, the break the SDK opens from
+ * it, and every beacon fired against it.
+ *
+ * Named for the Quortex/Synamedia DAI integration it was built for, but it is
+ * the path itself that is logged, so a StreamLayer-dialect stream tells the same
+ * story. Detector internals — clock sources, poll ticks, fold bookkeeping — stay
+ * on `ssai:*`, where `SL_DEBUG` can reach them without filling a demo window.
+ *
+ * A host publishes it to the page with `SL_LOG_EVENTS=ssaiq` (see
+ * `sdk-web-logger`); the demo's log window renders exactly that.
+ */
+export declare const ssaiq: Logger;

package/lib/cjs/units/ssai-log.js

@@ -0,0 +1,23 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+
+/**
+ * `ssaiq` — the SSAI ad NARRATIVE log: one line per thing that happens to a
+ * server-stitched ad, in the order it happens. The manifest tag the playout
+ * published, the metadata round trip it triggers, the break the SDK opens from
+ * it, and every beacon fired against it.
+ *
+ * Named for the Quortex/Synamedia DAI integration it was built for, but it is
+ * the path itself that is logged, so a StreamLayer-dialect stream tells the same
+ * story. Detector internals — clock sources, poll ticks, fold bookkeeping — stay
+ * on `ssai:*`, where `SL_DEBUG` can reach them without filling a demo window.
+ *
+ * A host publishes it to the page with `SL_LOG_EVENTS=ssaiq` (see
+ * `sdk-web-logger`); the demo's log window renders exactly that.
+ */
+// Explicit type: the inferred pino type is not nameable across package
+// boundaries (TS2742) when this file is compiled on its own.
+const ssaiq = sdkWebLogger.createLogger('ssaiq');
+
+exports.ssaiq = ssaiq;