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

package/src/onsite/render.js

@@ -30,8 +30,12 @@ const CARD_PX = { sm: 380, md: 480, lg: 880 };
 const ALIGNS = ['left', 'center', 'right'];
 const VARIANTS = { secondary: ' b2', link: ' no' };
 const EXIT_MS = 220;
+/** The steps a submit or a spin can land on besides the next one (the creative's own, if it has them). */
+const OUTCOMES = ['verify', 'already', 'held', 'fallback', 'success'];
 /** Waits before a claim's retries, for an API that answers 503 while it warms up. */
 const CLAIM_RETRY_MS = [500, 1500];
+/** How long a sign-up's button stays busy for its claim, so a returning shopper is never moved on first. */
+const HELD_WAIT_MS = 600;
 /** How long a wheel's prize is shown where it stopped before the next step: long enough to read. */
 const WON_MS = 1800;
 const COPY = {
@@ -42,7 +46,12 @@ const COPY = {
 	failed: 'Something went wrong. Please try again.',
 	busy: 'Too many tries. Please wait a moment and try again.',
 	spin: 'Sign up first to spin.',
-	held: 'Your code',
+	yours: 'Your code',
+	held: 'You’re already on the list',
+	resent: 'We’ve sent your code to your inbox again.',
+	inbox: 'Your code is in the email we sent when you first signed up.',
+	shop: 'Continue shopping',
+	closeOffer: 'Close offer',
 	code: 'We’ll email your code to you.',
 	claimed: 'This email address has already claimed its code.',
 	copied: 'Copied',
@@ -87,6 +96,121 @@ export function layoutOf(step) {
 	};
 }
 
+/** The card's size: the theme's, else large for a split or an overlay. */
+const sizeOf = (t, l) =>
+	oneOf(['sm', 'md', 'lg', 'full'], t.size, null) ??
+	(l.template === 'split' || l.template === 'overlay' ? 'lg' : 'md');
+
+/**
+ * How wide an image shows, for the browser to pick from its srcset: the whole screen on a small
+ * one or a full-size form, else `part` of the card, a sheet or a teaser's tab.
+ */
+const across = (mode, size, part = 1) => {
+	if (mode === 'fullscreen' || size === 'full') return '100vw';
+	const px =
+		mode === 'teaser'
+			? 220
+			: mode === 'sheet'
+				? 400
+				: (CARD_PX[size] ?? CARD_PX.md);
+	return `(max-width: 639px) 100vw, ${Math.round(px * part)}px`;
+};
+
+/**
+ * The smaller copies the upload made of a WebP image (`widths`, any of them, each at `-<w>w.webp`)
+ * and the image itself at its width, as a srcset; null when there are none to offer.
+ */
+const srcset = (m, src, w) => {
+	if (!w || !Array.isArray(m.widths) || !src.endsWith('.webp')) return null;
+	const smaller = m.widths
+		.filter((x) => Number.isInteger(x) && x > 0 && x < w)
+		.sort((a, b) => a - b);
+	if (smaller.length === 0) return null;
+	return [
+		...smaller.map((x) => `${src.slice(0, -5)}-${x}w.webp ${x}w`),
+		`${src} ${w}w`,
+	].join(',');
+};
+
+/** The format a form shows in: an inline form's own, else its creative's, else the form's. */
+const formatOf = (form, creative) =>
+	form.format === 'inline'
+		? 'inline'
+		: creative.format && creative.format !== 'inline'
+			? creative.format
+			: form.format;
+
+const isVideo = (m) => m.kind === 'video' || m.t === 'video';
+
+const VIDEO_TYPES = {
+	webm: 'video/webm',
+	mp4: 'video/mp4',
+	m4v: 'video/mp4',
+	mov: 'video/quicktime',
+	ogv: 'video/ogg',
+};
+
+/** A video file's type by its path's extension, never its query or fragment; undefined when unknown. */
+const videoType = (href) =>
+	VIDEO_TYPES[href.split(/[?#]/)[0].split('.').pop().toLowerCase()];
+
+/** A video's files: its asset and any other encodings of it (`sources`), WebM first. */
+const videoFiles = (m, src) =>
+	[
+		...new Set([
+			src,
+			...(Array.isArray(m.sources) ? m.sources.map(assetHref) : []),
+		]),
+	]
+		.filter(Boolean)
+		.sort(
+			(a, b) =>
+				(videoType(b) === VIDEO_TYPES.webm) -
+				(videoType(a) === VIDEO_TYPES.webm),
+		);
+
+/**
+ * Fetch and decode the pictures step `id` will show (its media, its image blocks, a video's
+ * poster), asked for exactly as the renderer asks (the same `srcset` and `sizes`, so the browser
+ * picks the same file), into the browser's cache. Resolves once each is decoded or has failed:
+ * the runtime opens a form when its first step's pictures are ready, or after a short wait.
+ */
+export function warm(form, creative, id, seen = new Set()) {
+	const step = creative.steps.find((s) => s.id === id);
+	if (!step) return Promise.resolve();
+	const format = formatOf(form, creative);
+	const l = layoutOf(step);
+	const tab = format === 'teaser' && step === creative.steps[0];
+	const mode = format === 'teaser' && !tab ? 'popup' : format;
+	const size = sizeOf(creative.theme, l);
+	// A teaser's tab shows only its button, or its picture when that is all it is: the rest of the
+	// form opens as a popup, warmed with the popup's sizes once the tab is up (warmNext).
+	const wanted = tab
+		? []
+		: step.blocks
+				.filter((b) => isObject(b) && (b.t === 'image' || b.t === 'video'))
+				.map((b) => [b, 1]);
+	if (l.media && !(tab && l.template !== 'image-only'))
+		wanted.push([l.media, l.template === 'split' ? 0.46 : 1]);
+	return Promise.all(
+		wanted.map(([m, part]) => {
+			const src = assetHref(isVideo(m) ? m.poster : m.asset);
+			if (!src) return null;
+			const img = document.createElement('img');
+			const set = !isVideo(m) && srcset(m, src, num(m.width, 1, 8192));
+			if (set) {
+				img.sizes = across(mode, size, part);
+				img.srcset = set;
+			}
+			const key = `${img.sizes} ${set || src}`;
+			if (seen.has(key)) return null;
+			seen.add(key);
+			img.src = src;
+			return img.decode?.().catch(() => {});
+		}),
+	);
+}
+
 let ids = 0;
 const uid = (kind) => `hp-${kind}-${++ids}`;
 
@@ -210,12 +334,7 @@ export function mountForm(o) {
 			? form.sms_consent_text
 			: form.consent_text;
 	};
-	const format =
-		form.format === 'inline'
-			? 'inline'
-			: creative.format && creative.format !== 'inline'
-				? creative.format
-				: form.format;
+	const format = formatOf(form, creative);
 	const t = creative.theme;
 	const position = oneOf(
 		POSITIONS[format] ?? [],
@@ -254,10 +373,9 @@ export function mountForm(o) {
 	handle.setAttribute('aria-hidden', 'true');
 	wrap.append(handle, media, body);
 	shell.append(scrim, wrap);
-	if (format !== 'inline') {
-		const x = el('button', 'x');
+	const x = format !== 'inline' && el('button', 'x');
+	if (x) {
 		x.type = 'button';
-		x.setAttribute('aria-label', 'Close');
 		x.addEventListener('click', () => close('close'));
 		// After the form in the DOM, so the platform's first focus lands on the form itself.
 		wrap.append(x);
@@ -280,6 +398,11 @@ export function mountForm(o) {
 				? { code: 'WELCOME15' }
 				: null,
 		claiming: null,
+		touched: false,
+		toWarm: new Set(),
+		// The page view's pictures warmed so far (the runtime's), so none is fetched twice.
+		warmed: o.warmed ?? new Set(),
+		warming: false,
 		owed: false,
 		submitted: false,
 		pow: null,
@@ -307,10 +430,8 @@ export function mountForm(o) {
 	const small = preview ? null : globalThis.matchMedia?.('(max-width: 639px)');
 	const resize = () => {
 		state.mobile = small?.matches === true;
-		// A size kept from an earlier step is the old screen's.
-		wrap.classList.remove('lk');
-		wrap.style.removeProperty('min-width');
-		wrap.style.removeProperty('min-height');
+		// A size or a top kept from an earlier step is the old screen's.
+		unanchor();
 		classes();
 	};
 	if (small) {
@@ -375,43 +496,16 @@ export function mountForm(o) {
 	document.addEventListener('visibilitychange', visibility);
 
 	/**
-	 * How wide an image shows, for the browser to pick from its srcset: the whole screen on a small
-	 * one or a full-size form, else `part` of the card, a sheet or a teaser's tab.
+	 * An image or video for an asset, its box reserved by its size and cropped to its focal point.
+	 * `first`: on the form's first step, fetched at once and ahead of the page's other images; a
+	 * later step's waits until it shows (and was warmed while the step before it showed).
 	 */
-	const across = (part = 1) => {
-		if (state.mode === 'fullscreen' || state.size === 'full') return '100vw';
-		const px =
-			state.mode === 'teaser'
-				? 220
-				: state.mode === 'sheet'
-					? 400
-					: (CARD_PX[state.size] ?? CARD_PX.md);
-		return `(max-width: 639px) 100vw, ${Math.round(px * part)}px`;
-	};
-
-	/**
-	 * The smaller copies the upload made of a WebP image (`widths`, each at `-<w>w.webp`) and the
-	 * image itself at its width, as a srcset; null when there are none to offer.
-	 */
-	const srcset = (m, src, w) => {
-		if (!w || !Array.isArray(m.widths) || !src.endsWith('.webp')) return null;
-		const smaller = m.widths.filter(
-			(x) => Number.isInteger(x) && x > 0 && x < w,
-		);
-		if (smaller.length === 0) return null;
-		return [
-			...smaller.map((x) => `${src.slice(0, -5)}-${x}w.webp ${x}w`),
-			`${src} ${w}w`,
-		].join(',');
-	};
-
-	/** An image or video for an asset, its box reserved by its size and cropped to its focal point. */
-	function visual(m, className, eager, part) {
+	function visual(m, className, first, part) {
 		const src = assetHref(m.asset);
 		if (!src) return null;
 		const alt = typeof m.alt === 'string' ? m.alt : '';
 		let node;
-		if (m.kind === 'video' || m.t === 'video') {
+		if (isVideo(m)) {
 			node = el('video', className);
 			// The properties reflect to the attributes iOS needs before it plays inline.
 			node.muted = node.defaultMuted = node.loop = node.playsInline = true;
@@ -420,17 +514,31 @@ export function mountForm(o) {
 			if (alt) node.setAttribute('aria-label', alt);
 			else node.setAttribute('aria-hidden', 'true');
 			node.autoplay = !reducedMotion() && !preview;
-			node.src = src;
+			// Not playing (reduced motion, a preview): its poster, else its first frame, never a blank
+			// box; with a poster the video itself is never downloaded.
+			node.preload = node.autoplay ? 'auto' : poster ? 'none' : 'metadata';
+			// WebM first where the browser plays it, MP4 for the rest.
+			const files = videoFiles(m, src);
+			if (files.length > 1)
+				for (const file of files) {
+					const source = el('source');
+					source.src = file;
+					const type = videoType(file);
+					if (type) source.type = type;
+					node.append(source);
+				}
+			else node.src = src;
 			state.videos.push(node);
 		} else {
 			node = el('img', className);
 			node.alt = alt;
 			node.decoding = 'async';
-			node.loading = eager ? 'eager' : 'lazy';
+			node.loading = first ? 'eager' : 'lazy';
+			if (first) node.fetchPriority = 'high';
 			const set = srcset(m, src, num(m.width, 1, 8192));
 			// sizes before srcset before src, so the browser fetches one file, the right one.
 			if (set) {
-				node.sizes = across(part);
+				node.sizes = across(state.mode, state.size, part);
 				node.srcset = set;
 			}
 			node.src = src;
@@ -548,6 +656,9 @@ export function mountForm(o) {
 				box.append(el('p', '', state.claim.held ? COPY.claimed : COPY.code));
 				continue;
 			}
+			// The prize the code is for, beside it: "You won!" alone does not say what.
+			if (state.claim.prize?.label)
+				box.append(el('p', '', state.claim.prize.label));
 			const code = el('output');
 			code.textContent = state.claim.code;
 			const copy = el('button', 'btn cp');
@@ -617,7 +728,7 @@ export function mountForm(o) {
 
 	/** An image or video block: its box, fit, radius and tallest height. */
 	function picture(block) {
-		const node = visual(block, 'bi', false);
+		const node = visual(block, 'bi', state.step === creative.steps[0]);
 		if (!node) return null;
 		node.style.objectFit = block.fit === 'contain' ? 'contain' : 'cover';
 		const radius = num(block.radius, 0, 48);
@@ -746,17 +857,19 @@ export function mountForm(o) {
 	function layout(l, tab) {
 		media.replaceChildren();
 		const m = l.media;
-		const sized = oneOf(['sm', 'md', 'lg', 'full'], t.size, null);
-		const fallback =
-			l.template === 'split' || l.template === 'overlay' ? 'lg' : 'md';
 		const bare = !m || (tab && l.template !== 'image-only');
-		state.size = sized ?? fallback;
-		wrap.className = `w t-${l.template} z-${sized ?? fallback}${l.side === 'right' ? ' right' : ''}${t.text_align === 'center' ? ' ta-center' : ''}${bare ? ' nm' : ''}`;
+		state.size = sizeOf(t, l);
+		wrap.className = `w t-${l.template} z-${state.size}${l.side === 'right' ? ' right' : ''}${t.text_align === 'center' ? ' ta-center' : ''}${bare ? ' nm' : ''}`;
 		wrap.style.setProperty('--sc', String(l.scrim));
 		body.className = `f pd-${l.padding}`;
 		media.hidden = bare;
 		if (media.hidden) return;
-		const node = visual(m, '', true, l.template === 'split' ? 0.46 : 1);
+		const node = visual(
+			m,
+			'',
+			state.step === creative.steps[0],
+			l.template === 'split' ? 0.46 : 1,
+		);
 		if (!node) return;
 		if (node.width)
 			wrap.style.setProperty('--ar', `${node.width} / ${node.height}`);
@@ -814,9 +927,15 @@ export function mountForm(o) {
 		// entrance motion's transform is not in it.
 		const was =
 			moving && !preview
-				? { mode: state.mode, w: wrap.offsetWidth, h: wrap.offsetHeight }
+				? {
+						mode: state.mode,
+						w: wrap.offsetWidth,
+						h: wrap.offsetHeight,
+						top: wrap.offsetTop,
+					}
 				: null;
 		state.step = step;
+		state.touched = false;
 		for (const t of state.timers.splice(0)) clearInterval(t);
 		state.codes = [];
 		state.videos = [];
@@ -824,6 +943,7 @@ export function mountForm(o) {
 		const asTab = format === 'teaser' && step === creative.steps[0];
 		state.mode = format === 'teaser' && !asTab ? 'popup' : format;
 		if (format === 'teaser') counters.tab?.(form.slot, asTab);
+		if (x) x.setAttribute('aria-label', asTab ? COPY.closeOffer : 'Close');
 		classes();
 		shell.removeAttribute('aria-labelledby');
 		if (was) {
@@ -833,16 +953,15 @@ export function mountForm(o) {
 		}
 		const l = layoutOf(step);
 		layout(l, asTab);
-		// A step after another keeps at least the card's size, so a shorter one (the thanks after a
-		// sign-up) never pulls the centred card, or the page under an inline form, out from under the
-		// shopper: no layout shift, and no motion to reduce. A taller step still grows.
-		if (was?.mode === state.mode && was.h > 0) {
+		// A popup's step after another takes its own height, its top kept (settle, below). Any other
+		// form keeps at least its size, so a shorter step never pulls a bar's or sheet's top edge, or
+		// the page under an inline form, out from under the shopper. A taller step still grows.
+		const settles = was?.mode === 'popup' && state.mode === 'popup';
+		unanchor();
+		if (was?.mode === state.mode && was.h > 0 && !settles) {
+			wrap.style.setProperty('--lw', `${was.w}px`);
+			wrap.style.setProperty('--lh', `${was.h}px`);
 			wrap.classList.add('lk');
-			wrap.style.minWidth = `${was.w}px`;
-			wrap.style.minHeight = `${was.h}px`;
-		} else {
-			wrap.style.removeProperty('min-width');
-			wrap.style.removeProperty('min-height');
 		}
 		body.replaceChildren();
 		if (asTab && l.template !== 'image-only') body.append(tab(step));
@@ -868,12 +987,66 @@ export function mountForm(o) {
 		if (shell.hasAttribute('aria-labelledby'))
 			shell.removeAttribute('aria-label');
 		else shell.setAttribute('aria-label', l.media?.alt?.trim?.() || 'Sign up');
+		if (settles && was.h > 0) settle(was);
 		if (moving) present();
 		visibility();
+		if (!preview) warmNext(step);
 		// A screen reader hears the new step: focus moves to its heading when focus was in the form.
 		if (refocus) body.querySelector('h2')?.focus();
 	}
 
+	/** The card back to its own place and size: centred, its height its content's. */
+	function unanchor() {
+		wrap.classList.remove('lk', 'an');
+		wrap.style.removeProperty('--tp');
+	}
+
+	/**
+	 * A popup's new step at its own height with its top where the last one's was, so only the bottom
+	 * edge moves: the Layout Instability API counts a box whose top-left moves, not one that grows or
+	 * shrinks, so the step change shifts nothing, and the card never keeps a tall step's empty space.
+	 * A step too tall for the room below that top is centred again, as a first step is.
+	 */
+	function settle(was) {
+		const h = wrap.offsetHeight;
+		wrap.classList.add('an');
+		const pad = wrap.offsetTop;
+		const top = Math.max(0, was.top - pad);
+		if (top + h > shell.clientHeight - 2 * pad) return unanchor();
+		wrap.style.setProperty('--tp', `${top}px`);
+	}
+
+	/**
+	 * The steps `step` can lead to have their pictures warmed while it shows, once the page has
+	 * loaded and the browser is idle, so the next step never opens on an empty picture either.
+	 */
+	function warmNext(step) {
+		const next = step.next ?? {};
+		for (const id of [
+			next.default,
+			...Object.values(isObject(next.answers) ? next.answers : {}),
+			...step.blocks.map((b) => b?.next),
+			// Where a submit or a spin can land instead.
+			...OUTCOMES,
+		])
+			if (typeof id === 'string') state.toWarm.add(id);
+		if (state.warming) return;
+		state.warming = true;
+		const go = () => {
+			state.warming = false;
+			// A form closed, or taken off the page by the site, warms nothing more.
+			if (!state.closed && host.isConnected)
+				for (const id of state.toWarm) warm(form, creative, id, state.warmed);
+			state.toWarm.clear();
+		};
+		const idle = () =>
+			globalThis.requestIdleCallback
+				? requestIdleCallback(go, { timeout: 2000 })
+				: setTimeout(go, 200);
+		if (document.readyState === 'complete') idle();
+		else window.addEventListener('load', idle, { once: true });
+	}
+
 	/** Open the dialog as the step's mode needs: modal for a popup, non-modal for the rest. */
 	function present() {
 		if (!dialog) return;
@@ -1016,7 +1189,7 @@ export function mountForm(o) {
 			(res.status === 202 || res.status === 200) && OK.includes(status);
 		// Closed while it was sent: a sign-up taken still counts, but nothing more is shown.
 		if (state.closed && !taken) return;
-		busy(false);
+		if (!taken) busy(false);
 		// A contact the gateway refused is the shopper's to correct, in the SDK's own words for it.
 		const field = res.status === 400 ? res.body?.field : null;
 		if (field === 'email' || field === 'phone') return say(COPY[field], input);
@@ -1039,13 +1212,63 @@ export function mountForm(o) {
 		// email the sign-up starts can carry it; it tells the page once the claim settles, with the
 		// code or without.
 		state.owed = channel === 'email' && form.prizes.length > 0;
-		if (state.owed) claim();
-		else o.emit?.('submitted', { coupon: null });
+		// One attempt on the shopper's path (one that meets a warming API is retried behind it).
+		const claimed = state.owed ? claim([]) : null;
+		if (!claimed) o.emit?.('submitted', { coupon: null });
+		// A returning shopper whose address claimed its code with an earlier sign-up goes straight to
+		// the held step, not through the rest of the steps and a spin that cannot win: the button
+		// stays busy for the claim's answer, as long as HELD_WAIT_MS at most (Klaviyo and Privy wait
+		// on submit too). The gateway cannot say it in its own answer: claims are the public API's
+		// (ADR 0021).
+		const early =
+			claimed &&
+			(await Promise.race([
+				claimed,
+				new Promise((r) => setTimeout(r, HELD_WAIT_MS)),
+			]));
+		if (state.closed) return;
+		busy(false);
+		if (early?.held) return show(ownStep('held'));
 		// A step named for the outcome (`verify`, `already`) is shown for it; otherwise the next one.
 		const special =
 			status !== 'ok' && creative.steps.some((s) => s.id === status);
-		if (!state.closed)
-			show(special ? status : nextStep(step, state.answers, block.next));
+		show(special ? status : nextStep(step, state.answers, block.next));
+		// A held answer later than that moves the shopper only if they have not touched the step
+		// they were moved on to; a spin started answers it itself.
+		const next = state.step;
+		claimed?.then((won) => {
+			if (won?.held && !state.closed && state.step === next && !state.touched)
+				show(ownStep('held'));
+		});
+	}
+
+	/**
+	 * The creative's step `id`, else the SDK's own plain one: a thanks with no prize (`fallback`); a
+	 * code this browser claimed on another form, with that code (`held`); or, for an address another
+	 * sign-up claimed with (`held`, no code), a welcome back. That code is never shown here: the
+	 * sign-up hands it to the destinations again, so the inbox has it when one carries it.
+	 */
+	function ownStep(id) {
+		if (creative.steps.some((s) => s.id === id)) return id;
+		const blocks =
+			id === 'fallback' || state.claim?.code
+				? [
+						{
+							t: 'heading',
+							text: id === 'fallback' ? COPY.thanks : COPY.yours,
+						},
+						{ t: 'code' },
+					]
+				: [
+						{ t: 'heading', text: COPY.held },
+						{
+							t: 'text',
+							text: form.code_relayed === true ? COPY.resent : COPY.inbox,
+						},
+						{ t: 'button', label: COPY.shop, action: 'close' },
+					];
+		creative.steps.push({ id, blocks });
+		return id;
 	}
 
 	/** Tells the page, once, that the sign-up was taken: with the claim's code, or with none. */
@@ -1058,11 +1281,11 @@ export function mountForm(o) {
 	}
 
 	/** The form's claim, made once: a failed one is made again by the next spin. */
-	function claim() {
+	function claim(retries = CLAIM_RETRY_MS) {
 		const receipt = state.receipt;
 		state.claiming ??= (async () => {
 			let res;
-			for (const ms of [0, ...CLAIM_RETRY_MS]) {
+			for (const ms of [0, ...retries]) {
 				if (ms) await new Promise((r) => setTimeout(r, ms));
 				res = await api.claim({
 					slot: decision.slot,
@@ -1071,13 +1294,20 @@ export function mountForm(o) {
 				});
 				if (res.status !== 503) break;
 			}
-			const won = res.body;
+			let won = res.body;
 			const fallback = won?.fallback === true && !won.code;
 			if (res.status !== 200 || !(isObject(won?.prize) || fallback)) {
 				state.claiming = null;
+				// A single attempt that met a warming API is made again with its retries, which tell
+				// the page; any other failure is final until a spin asks again.
+				if (!retries.length && res.status === 503) return claim();
 				settled(null);
 				return null;
 			}
+			// The browser that claimed the code proved it is the shopper's when it won it: a held claim
+			// shows it the code it kept, as a reminder would, rather than a welcome back.
+			const kept = won.held && !won.code ? counters.code?.() : null;
+			if (kept) won = { ...won, code: kept };
 			state.claim = won;
 			if (typeof won.code === 'string') counters.code?.(won.code);
 			settled(won);
@@ -1119,15 +1349,9 @@ export function mountForm(o) {
 		// No code left: the creative's `fallback` step, else a plain thanks, never a prize "won". A
 		// prize held: its `held` step, else a plain one with the code block.
 		const special = fallback ? 'fallback' : index < 0 ? 'held' : null;
-		if (special && !creative.steps.some((s) => s.id === special))
-			creative.steps.push({
-				id: special,
-				blocks: [
-					{ t: 'heading', text: fallback ? COPY.thanks : COPY.held },
-					{ t: 'code' },
-				],
-			});
-		const to = special ?? nextStep(state.step, state.answers, block.next);
+		const to = special
+			? ownStep(special)
+			: nextStep(state.step, state.answers, block.next);
 		if (to) show(to);
 		else fillCodes();
 	}
@@ -1189,14 +1413,61 @@ export function mountForm(o) {
 		o.onClose?.(reason);
 	}
 
+	// Whether the shopper has done anything on the step on screen: a late claim never moves them.
+	for (const type of ['pointerdown', 'keydown', 'input'])
+		shell.addEventListener(type, () => {
+			state.touched = true;
+		});
 	shell.addEventListener('cancel', (e) => {
 		e.preventDefault();
 		close('esc');
 	});
 	shell.addEventListener('keydown', (e) => {
 		if (e.key === 'Escape' && !state.modal && format !== 'inline') close('esc');
+		if (e.key === 'Tab' && state.modal) trap(e);
 	});
 
+	/**
+	 * Tab and Shift-Tab cycle inside a modal form. showModal() makes the page inert, but the browser
+	 * still tabs out of the dialog to the document (and its own chrome) before coming back; the
+	 * APG's modal dialog pattern keeps focus in the dialog, so the last control leads to the first.
+	 * The stops are the ones Tab reaches now: shown and enabled, and of a radio group only its
+	 * checked button, or its first. From anything else (the heading a step focuses), Tab goes to the
+	 * first stop after it and Shift-Tab to the last before it.
+	 */
+	function trap(e) {
+		const checked = [...root.querySelectorAll('input[type=radio]:checked')];
+		const groups = new Set();
+		const stops = [
+			...root.querySelectorAll('a[href],button,input,select,textarea'),
+		].filter((n) => {
+			if (n.disabled || !n.getClientRects().length) return false;
+			if (n.type !== 'radio') return true;
+			const on = checked.find((r) => r.name === n.name);
+			if (on ? n !== on : groups.has(n.name)) return false;
+			groups.add(n.name);
+			return true;
+		});
+		if (!stops.length) return;
+		const back = e.shiftKey;
+		let at = root.activeElement;
+		if (at?.type === 'radio')
+			at = stops.find((n) => n.type === 'radio' && n.name === at.name) ?? at;
+		const i = stops.indexOf(at);
+		let to = null;
+		if (i < 0) {
+			const after = (n) => at && at.compareDocumentPosition(n) & 4; // DOCUMENT_POSITION_FOLLOWING
+			to = back
+				? (stops.findLast((n) => !after(n)) ?? stops.at(-1))
+				: (stops.find(after) ?? stops[0]);
+		} else if (back ? i === 0 : i === stops.length - 1)
+			to = stops.at(back ? -1 : 0);
+		if (to) {
+			e.preventDefault();
+			to.focus();
+		}
+	}
+
 	// Drag a bottom sheet down by its handle to close it.
 	handle.addEventListener('pointerdown', (e) => {
 		if (!state.mobile || state.mode !== 'sheet') return;
@@ -1229,6 +1500,8 @@ export function mountForm(o) {
 		host,
 		show,
 		step: () => state.step?.id ?? null,
+		/** Whether the form is a modal on screen now: a popup, or a teaser opened from its tab. */
+		modal: () => !state.closed && state.modal,
 		destroy: () => !state.closed && teardown(),
 	};
 }