@thg-agentic/hyper-personalisation-web 3.23.0 → 3.24.1

package/src/onsite/index.js

@@ -9,8 +9,9 @@
  * here, with its pages, devices, dates and caps. When one fires, `POST /v1/decisions` is asked for
  * that one slot: a held-out visitor, or no decision, shows nothing. One overlay per page view, the
  * highest priority among those that fire within 50 ms; one that cannot show passes to the next, but
- * a held-out visitor sees none; with the property's `overlay_gap_minutes`,
- * none until that long after the last one this session. `?hp_debug=onsite` logs why each form did
+ * a held-out visitor sees none, and once one has shown, closing it lets no other in; with the
+ * property's `overlay_gap_minutes`, none until that long after the last one this session. A form
+ * the site opens on the shopper's click (`manual`) is past the caps, the gap and the allowance. `?hp_debug=onsite` logs why each form did
  * or did not show; `hp.onsite.debug()` returns it. The renderer (./render.js, its own chunk) is
  * fetched only once a trigger fires, alongside the decision request; a page whose forms never fire
  * never downloads it.
@@ -21,6 +22,7 @@ import { createApi } from './api.js';
 import { createCounters } from './counters.js';
 import { loadRender } from './render-loader.js';
 import {
+	ASKED,
 	blockers,
 	byPriority,
 	deviceOf,
@@ -63,6 +65,8 @@ const INERT = {
 
 /** How long a fired trigger waits for others, so two forms entering together show the higher priority. */
 const FIRE_WINDOW_MS = 50;
+/** The longest a form waits for its first step's pictures before it opens without them. */
+const WARM_MS = 300;
 
 const debugParam = () => {
 	try {
@@ -127,7 +131,28 @@ export function startOnsite(client, options = {}) {
 				reasons: ['not a form this SDK can show'],
 			});
 	}
-	let overlay = null;
+	/**
+	 * The covering forms on screen or being opened, by slot (a bar and a popup the shopper asked for
+	 * can both be up), the slots being opened now, and the form that spent this page view's allowance.
+	 */
+	const covering = new Map();
+	const opening = new Map();
+	let spent = null;
+	/** The pictures warmed on this page view, by every form, so none is fetched twice. */
+	const warmed = new Set();
+	/**
+	 * The covering form that keeps `asked` (a form the shopper asked for, or not) off the screen. Any
+	 * covering form keeps one the page triggered away; one the shopper asked for waits only for a
+	 * form still being opened, or for a modal actually on screen (an expanded teaser is one), so it
+	 * opens over a bar or a teaser's tab.
+	 */
+	const blocker = (asked) => {
+		for (const slot of covering.keys()) {
+			const handle = mounted.get(slot);
+			if (!asked || !handle || handle.modal?.()) return slot;
+		}
+		return null;
+	};
 	let fired = [];
 	const gap = Number.isInteger(settings.overlay_gap_minutes)
 		? settings.overlay_gap_minutes
@@ -144,7 +169,7 @@ export function startOnsite(client, options = {}) {
 	/** Forms whose trigger fired on an empty basket: they try again when the basket changes. */
 	const awaitingBasket = new Set();
 	/** Covering forms whose trigger fired before the consent banner was answered. */
-	const awaitingConsent = new Set();
+	const awaitingConsent = new Map();
 
 	const note = (form, state, reasons = []) => {
 		trace.set(form.slot, {
@@ -187,35 +212,59 @@ export function startOnsite(client, options = {}) {
 		stops.delete(form.slot);
 	};
 
-	/** `kept`: a teaser's tab carried from an earlier page, shown again whatever its caps. */
-	/** Show `form` if its rules allow it; resolves to the state its trace records. */
-	async function show(form, reason, kept = false) {
+	/**
+	 * Show `form` if its rules allow it; resolves to the state its trace records. A form on screen is
+	 * not mounted again, and a second call while it is being opened (a double click during the
+	 * decision) shares the first one's answer.
+	 */
+	function show(form, reason, kept = false, asked = ASKED(form)) {
+		if (mounted.has(form.slot)) return Promise.resolve('shown');
+		if (!opening.has(form.slot))
+			opening.set(
+				form.slot,
+				attempt(form, reason, kept, asked).finally(() =>
+					opening.delete(form.slot),
+				),
+			);
+		return opening.get(form.slot);
+	}
+
+	/**
+	 * `kept`: a teaser's tab carried from an earlier page, shown again whatever its caps. `asked`: the
+	 * shopper asked for it (a `manual` form, or one opened by an alias), so its counters do not apply.
+	 */
+	async function attempt(form, reason, kept, asked) {
 		if (suppressed()) {
 			return note(form, 'not shown', [
 				`suppressed: ${[...window[SUPPRESSED]].join(', ')}`,
 			]);
 		}
-		const reasons = blockers(
-			form,
-			kept ? { ...env(form), seen: INERT.seen() } : env(form),
-		);
+		const reasons = blockers(form, {
+			...env(form),
+			...(kept ? { seen: INERT.seen() } : {}),
+			asked,
+		});
 		if (reasons.length) {
 			return note(form, 'not eligible', reasons);
 		}
 		// The gap first: it holds for the whole session, so it is the reason worth reading.
 		const interrupts = INTERRUPTS(form.format) && !kept;
-		const wait = interrupts && gapHolds();
+		const wait = interrupts && !asked && gapHolds();
 		if (wait) {
 			return note(form, 'not shown', [wait]);
 		}
 		// Never over an unanswered consent banner: the shopper answers it first, whatever the answer.
 		if (interrupts && !access.preview && access.consentAnswered?.() === false) {
-			awaitingConsent.add(form);
+			awaitingConsent.set(form, asked);
 			return note(form, 'not shown', ['waiting for the consent banner']);
 		}
 		const covers = OVERLAY(form.format);
-		if (covers && overlay) {
-			return note(form, 'not shown', [`${overlay} is showing`]);
+		const shown = covers && blocker(asked);
+		if (shown) return note(form, 'not shown', [`${shown} is showing`]);
+		if (covers && spent && !asked) {
+			return note(form, 'not shown', [
+				`${spent} already showed on this page view`,
+			]);
 		}
 		let container = null;
 		if (!covers) {
@@ -228,7 +277,7 @@ export function startOnsite(client, options = {}) {
 				return note(form, 'not shown', ['no element matches its selector']);
 			}
 		}
-		if (covers) overlay = form.slot;
+		if (covers) covering.set(form.slot, form);
 		unwatch(form);
 		note(form, 'asking for a decision', [reason]);
 		// The renderer is fetched while the decision is asked, so neither waits on the other.
@@ -265,16 +314,26 @@ export function startOnsite(client, options = {}) {
 				!(basket > 0) &&
 				'the basket is empty');
 		if (missing) {
-			if (covers) overlay = null;
+			covering.delete(form.slot);
 			if (missing === 'the basket is empty') awaitingBasket.add(form);
 			return note(form, 'not shown', [missing]);
 		}
 		awaitingBasket.delete(form);
 		if (!creative) {
-			// A held-out visitor whose trigger fired is exposed to the default, as a treated one is.
+			// A held-out visitor whose trigger fired is exposed to the default, as a treated one is,
+			// and its page stays one with no popup: the allowance is spent as a shown one spends it.
 			if (decision?.holdout === true && access.analytics())
 				client.recordExposure(res.body);
-			if (covers) overlay = null;
+			covering.delete(form.slot);
+			if (covers && decision?.holdout === true) spent ??= form.slot;
+			// The site shows a held-out visitor what it shows without HP, at the same moment; a form
+			// the site opened hears so from `open`, which resolves false.
+			if (decision?.holdout === true && !asked)
+				emit('held', {
+					slot: form.slot,
+					arm: decision.arm ?? null,
+					format: form.format,
+				});
 			return note(
 				form,
 				decision?.holdout === true ? 'held out' : 'no decision',
@@ -287,11 +346,22 @@ export function startOnsite(client, options = {}) {
 		}
 		const render = await renderer;
 		if (!render) {
-			if (covers) overlay = null;
+			covering.delete(form.slot);
 			return note(form, 'not shown', ['the renderer did not load']);
 		}
+		// Its first step's pictures fetched and decoded first, so it never opens on an empty one, and
+		// never waits for them longer than WARM_MS.
+		await Promise.race([
+			render.warm?.(form, creative, creative.steps[0].id, warmed),
+			new Promise((resolve) => setTimeout(resolve, WARM_MS)),
+		]);
+		if (suppressed()) {
+			covering.delete(form.slot);
+			return note(form, 'not shown', ['suppressed']);
+		}
 		if (!kept) counters.shown(form.slot);
 		if (interrupts) counters.covered();
+		if (covers) spent ??= form.slot;
 		const tell = (name, detail = {}) =>
 			emit(name, {
 				slot: form.slot,
@@ -310,12 +380,13 @@ export function startOnsite(client, options = {}) {
 			loadWheel,
 			loadAnswers,
 			container,
+			warmed,
 			coupon,
 			basket: () => access.basketValue?.() ?? null,
 			emit: tell,
 			onClose(why) {
 				mounted.delete(form.slot);
-				if (overlay === form.slot) overlay = null;
+				covering.delete(form.slot);
 				note(form, 'closed', [why]);
 				tell('closed', { reason: why });
 			},
@@ -331,15 +402,15 @@ export function startOnsite(client, options = {}) {
 	 * Triggers that fire within FIRE_WINDOW_MS of each other compete: only the highest priority shows.
 	 * One that cannot show passes to the next; a held-out visitor sees none, so the holdout stays clean.
 	 */
-	function fire(form, reason) {
-		if (!OVERLAY(form.format)) return show(form, reason);
-		fired.push([form, reason]);
+	function fire(form, reason, asked = ASKED(form)) {
+		if (!OVERLAY(form.format)) return show(form, reason, false, asked);
+		fired.push([form, reason, asked]);
 		if (fired.length > 1) return;
 		setTimeout(async () => {
 			const queue = fired.sort(([a], [b]) => byPriority(a, b));
 			fired = [];
-			for (const [i, [next, why]] of queue.entries()) {
-				const state = await show(next, why);
+			for (const [i, [next, why, ask]] of queue.entries()) {
+				const state = await show(next, why, false, ask);
 				if (state === 'shown' || state === 'held out') {
 					for (const [f] of queue.slice(i + 1))
 						note(f, 'not shown', [`${next.slot} has a higher priority`]);
@@ -390,9 +461,9 @@ export function startOnsite(client, options = {}) {
 	const stopConsent = access.onConsentAnswered?.(() => {
 		const waiting = [...awaitingConsent];
 		awaitingConsent.clear();
-		for (const form of waiting)
+		for (const [form, asked] of waiting)
 			if (!mounted.has(form.slot))
-				form.trigger.type === 'manual' ? fire(form, 'manual') : arm(form);
+				asked ? fire(form, 'manual', asked) : arm(form);
 	});
 
 	const stopBasket = access.onBasket?.(() => {
@@ -406,20 +477,28 @@ export function startOnsite(client, options = {}) {
 	});
 
 	const controller = Object.freeze({
-		/** Show the form on `slot` now, whatever its trigger, if its rules allow it. */
-		open(slot) {
-			const form = forms.find((f) => f.slot === slot);
-			// One already on screen (an inline form) is shown, not mounted twice.
-			return form && !mounted.has(slot)
-				? show(form, 'manual').then((state) => state === 'shown')
-				: Promise.resolve(mounted.has(slot));
+		/**
+		 * Show the form keyed `name`, else the first whose `aliases` has it (the site's own sign-up
+		 * button names one), now, whatever its trigger. From there it is that form, by its slot.
+		 */
+		open(name) {
+			const keyed = forms.find((f) => f.slot === name);
+			const form = keyed ?? forms.find((f) => f.aliases.includes(name));
+			if (!form) return Promise.resolve(false);
+			// One already on screen (an inline form) is shown, not mounted twice. A form opened by an
+			// alias is the shopper asking, as a `manual` one is.
+			return mounted.has(form.slot)
+				? Promise.resolve(true)
+				: show(form, 'manual', false, ASKED(form) || !keyed).then(
+						(state) => state === 'shown',
+					);
 		},
 		/** `hp.onsite.suppress`: take every form off the screen, quietly; none shows until unsuppressed. */
 		suppress() {
 			for (const [slot, handle] of mounted) {
 				handle.destroy();
 				mounted.delete(slot);
-				if (overlay === slot) overlay = null;
+				covering.delete(slot);
 				const form = forms.find((f) => f.slot === slot);
 				if (form) note(form, 'closed', ['suppressed']);
 			}