@thg-agentic/hyper-personalisation-web 3.30.0 → 3.32.0

package/src/onsite/api.js

@@ -61,6 +61,19 @@ export function createApi(access, options = {}) {
 		}
 	}
 
+	/**
+	 * A sign-up or its later answers, to the gateway. Once it takes them (2xx), the answers are kept
+	 * on the device under personalisation consent, as a quiz's are (ADR 0064).
+	 */
+	const taken = (path, body) =>
+		call(`${gateway}/v1/capture${path}`, { method: 'POST', body }).then(
+			(res) => {
+				if (res.status >= 200 && res.status < 300)
+					access.answered?.(body.answers, body.slot);
+				return res;
+			},
+		);
+
 	return {
 		/**
 		 * The decision for one slot, as the page's other serving calls ask for it, with its pin and
@@ -100,7 +113,12 @@ export function createApi(access, options = {}) {
 					// What a promo reminder's code is answered for under a publishable key (ADR 0067).
 					identity_token: access.identityToken?.() ?? undefined,
 					...(access.preview ? { preview: access.preview } : {}),
-					...(visitAudiences ? { visit_audiences: visitAudiences } : {}),
+					...(visitAudiences && {
+						visit_audiences: visitAudiences.claims,
+						...(visitAudiences.answered?.length && {
+							answered_audiences: visitAudiences.answered,
+						}),
+					}),
 					...(visitCampaign ? { visit_campaign: visitCampaign } : {}),
 					...(visitContext ? { visit_context: visitContext } : {}),
 				},
@@ -111,10 +129,9 @@ export function createApi(access, options = {}) {
 				timeoutMs: DATAFILE_TIMEOUT_MS,
 			}),
 		challenge: () => call(`${gateway}${challengePath(options.challenge)}`),
-		capture: (body) => call(`${gateway}/v1/capture`, { method: 'POST', body }),
+		capture: (body) => taken('', body),
 		// Answers given after the email step, with its address and receipt.
-		answers: (body) =>
-			call(`${gateway}/v1/capture/answers`, { method: 'POST', body }),
+		answers: (body) => taken('/answers', body),
 		// Bounded, so the page's `submitted`, which waits for the claim, always comes.
 		claim: (body) =>
 			call(`${serving}/v1/offers/claim`, {

package/src/onsite/index.js

@@ -23,6 +23,7 @@ import { loadAudiences } from './audiences-loader.js';
 import { createCounters } from './counters.js';
 import { loadProducts } from './products-loader.js';
 import { loadRender } from './render-loader.js';
+import { holdsValue } from './rich-text.js';
 import {
 	ASKED,
 	blockers,
@@ -34,6 +35,7 @@ import {
 	readForm,
 } from './rules.js';
 import { watch } from './triggers.js';
+import { loadValues } from './values-loader.js';
 import { loadWheel } from './wheel-loader.js';
 
 const ACCESS = Symbol.for(
@@ -75,6 +77,7 @@ const NOTHING = new Set([
 	'no-code',
 	'renderer-failed',
 	'products-failed',
+	'values-failed',
 	'error',
 ]);
 
@@ -102,14 +105,9 @@ const debugParam = () => {
 	}
 };
 
-/** Whether a creative shows a products block on any step. */
-const showsProducts = (creative) =>
-	Array.isArray(creative?.steps) &&
-	creative.steps.some(
-		(step) =>
-			Array.isArray(step?.blocks) &&
-			step.blocks.some((block) => block?.t === 'products'),
-	);
+/** Whether any block of any of the creative's steps meets `uses`. */
+const stepsUse = (creative, uses) =>
+	creative.steps.some((step) => step.blocks.some(uses));
 
 /**
  * Start onsite forms for `client`, once per page. Returns the controller, or null without a
@@ -131,6 +129,7 @@ export function startOnsite(client, options = {}) {
 		return null;
 	}
 	const settings = options.settings ?? access.settings ?? {};
+	access.started?.(settings);
 	const api = createApi(access, {
 		...options,
 		challenge: settings.capture?.challenge,
@@ -414,9 +413,11 @@ export function startOnsite(client, options = {}) {
 		// The evaluator orders the page's own with the visit's (targets and what they require first);
 		// a fallback sends the page's alone, the form's targets first and capped at the server's 100.
 		const page = sessionAudiences() ?? [];
-		const given = [...new Set([...form.audiences, ...page])]
-			.filter((slug) => page.includes(slug))
-			.slice(0, 100);
+		const given = {
+			claims: [...new Set([...form.audiences, ...page])]
+				.filter((slug) => page.includes(slug))
+				.slice(0, 100),
+		};
 		const claimed =
 			form.audiences.length > 0 && !access.preview && access.personalisation()
 				? await within(
@@ -518,20 +519,36 @@ export function startOnsite(client, options = {}) {
 			return drop(form, 'not shown', 'renderer-failed', [
 				'the renderer did not load',
 			]);
-		// Its products are drawn by their own chunk: without it the form would open on an empty block.
-		if (showsProducts(creative)) {
-			cards ??= loadProducts().catch(() => null);
-			if (!(await within(cards, deadline, null)))
-				return drop(form, 'not shown', 'products-failed', [
-					'its products 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 or past its deadline.
-		await within(
+		// Its products and its text's values are drawn by chunks of their own, fetched together while
+		// its first step's pictures warm: without them the form would open on an empty block, or on
+		// text with a gap. The pictures are waited for no longer than WARM_MS or past its deadline.
+		const products = stepsUse(creative, (b) => b?.t === 'products');
+		if (products) cards ??= loadProducts().catch(() => null);
+		const warming = within(
 			render.warm?.(form, creative, creative.steps[0].id, warmed),
 			Math.min(deadline, Date.now() + WARM_MS),
 		);
+		const [drawn, values] = await Promise.all([
+			!products || within(cards, deadline, null),
+			stepsUse(
+				creative,
+				(b) => (b?.t === 'heading' || b?.t === 'text') && holdsValue(b.text),
+			) &&
+				within(
+					loadValues().catch(() => null),
+					deadline,
+					null,
+				),
+		]);
+		if (!drawn)
+			return drop(form, 'not shown', 'products-failed', [
+				'its products did not load',
+			]);
+		if (values === null)
+			return drop(form, 'not shown', 'values-failed', [
+				'its values did not load',
+			]);
+		await warming;
 		if (suppressed())
 			return drop(form, 'not shown', 'suppressed', ['suppressed']);
 		const tell = (name, detail = {}) =>
@@ -556,6 +573,7 @@ export function startOnsite(client, options = {}) {
 			warmed,
 			coupon,
 			basket: () => access.basketValue?.() ?? null,
+			fill: values ? values.fillFor(form, access, options.values) : undefined,
 			emit: tell,
 			onClose(why) {
 				mounted.delete(form.slot);

package/src/onsite/money.js

@@ -0,0 +1,11 @@
+/** Money in `currency` for the language `lang` (else the browser's); null for a currency `Intl` does not know. */
+export function money(lang, currency) {
+	try {
+		return new Intl.NumberFormat(lang || undefined, {
+			style: 'currency',
+			currency,
+		});
+	} catch {
+		return null;
+	}
+}

package/src/onsite/preview.js

@@ -10,9 +10,12 @@ import { answerCards, answerFields, answerOf, countdown } from './answers.js';
 import { mountProducts } from './products.js';
 import { mountForm } from './render.js';
 import { readCreative } from './rules.js';
+import { fillFor } from './values.js';
 import { mountWheel } from './wheel.js';
 
 export { CALLING_CODES } from './rules.js';
+/** A shopper value as the SDK shows it, so the console's examples read as shoppers see them. */
+export { formatValue } from './values.js';
 
 const SAMPLE_CONSENT = 'Your consent text appears here.';
 const SAMPLE_SMS_CONSENT = 'Your SMS consent text appears here.';
@@ -35,7 +38,10 @@ const SAMPLE_BASKET = 32;
  * @param {unknown} creative The arm's payload.
  * @param {{ step?: string, device?: 'desktop'|'mobile', consentText?: string, smsConsentText?: string, locale?: string,
  *   questions?: Array<{ key: string, type?: 'one'|'many'|'date'|'number', label?: string, options?: Array<{ value: string, label?: string }>, format?: object }>,
- *   prizes?: Array<{ key: string, label: string }>, basketValue?: number }} [options]
+ *   prizes?: Array<{ key: string, label: string }>, basketValue?: number,
+ *   values?: { first_name?: string, basket_value?: number, basket_items?: number, currency?: string, answers?: Record<string, string[]> } | null }} [options]
+ *   `values`: a returning shopper's, for the text's shopper values; without them every value shows
+ *   its fallback, as for a new visitor, but for an answer given in the form itself.
  * @returns {{ update(creative: unknown, options?: object): void, destroy(): void, step(): string|null }}
  */
 export function mountPreview(host, creative, options = {}) {
@@ -48,19 +54,25 @@ export function mountPreview(host, creative, options = {}) {
 		mounted = null;
 		if (!read) return;
 		const format = read.format ?? 'popup';
+		const form = {
+			slot: 'preview',
+			format,
+			// The settings' `locale`, so the preview orders a birthday and picks a phone's
+			// country as shoppers see them, not by the console's own language.
+			...(opts.locale ? { locale: opts.locale } : {}),
+			consent_text: { text: opts.consentText ?? SAMPLE_CONSENT },
+			sms_consent_text: { text: opts.smsConsentText ?? SAMPLE_SMS_CONSENT },
+			questions: Array.isArray(opts.questions) ? opts.questions : [],
+			prizes: Array.isArray(opts.prizes) ? opts.prizes : [],
+		};
+		const values = opts.values ?? null;
 		mounted = mountForm({
-			form: {
-				slot: 'preview',
-				format,
-				// The settings' `locale`, so the preview orders a birthday and picks a phone's
-				// country as shoppers see them, not by the console's own language.
-				...(opts.locale ? { locale: opts.locale } : {}),
-				consent_text: { text: opts.consentText ?? SAMPLE_CONSENT },
-				sms_consent_text: { text: opts.smsConsentText ?? SAMPLE_SMS_CONSENT },
-				questions: Array.isArray(opts.questions) ? opts.questions : [],
-				prizes: Array.isArray(opts.prizes) ? opts.prizes : [],
-			},
+			form,
 			creative: read,
+			fill: fillFor(form, {
+				// A new visitor: nothing known yet, though the answers they give in the form show.
+				values: () => values ?? { answers: {} },
+			}),
 			decision: { slot: 'preview' },
 			access: silent,
 			client: null,

package/src/onsite/products.js

@@ -10,6 +10,7 @@
  */
 
 import { watchViewability } from '../auto/viewability.js';
+import { money } from './money.js';
 import { httpsHref } from './rich-text.js';
 import { isObject } from './rules.js';
 
@@ -42,15 +43,8 @@ const ALIGNS = ['left', 'center', 'right'];
 
 /** Money in the form's language; the bare amount for a currency the browser does not know. */
 function moneyIn(lang, currency) {
-	try {
-		const format = new Intl.NumberFormat(lang || undefined, {
-			style: 'currency',
-			currency,
-		});
-		return (n) => format.format(n);
-	} catch {
-		return (n) => n.toFixed(2);
-	}
+	const format = money(lang, currency);
+	return format ? (n) => format.format(n) : (n) => n.toFixed(2);
 }
 
 /**

package/src/onsite/render.js

@@ -352,6 +352,8 @@ function styles(root) {
  * @param {(name: 'submitted'|'apply', detail: object) => void} [o.emit] To `hp.onsite.on` listeners.
  * @param {string|null} [o.coupon] A code the form starts with: an unused one to remind of.
  * @param {() => number|null} [o.basket] The basket's value, for a progress block.
+ * @param {(block: object, answers: object) => object|false} [o.fill] A form whose text has shopper
+ *   values: each block as it shows (./values.js `fillFor`), `false` for one hidden.
  * @param {{ device: 'desktop'|'mobile', step?: string }} [o.preview] Render inside `container`,
  *   inert but for moving between steps: no network, no events, no counters.
  */
@@ -1002,11 +1004,9 @@ export function mountForm(o) {
 	}
 
 	/** A teaser's first step: a tab that opens the rest of the form. */
-	function tab(step) {
-		const heading = step.blocks.find((b) => b?.t === 'heading');
-		const open = step.blocks.find(
-			(b) => b?.t === 'button' && b.action === 'next',
-		);
+	function tab(blocks) {
+		const heading = blocks.find((b) => b?.t === 'heading');
+		const open = blocks.find((b) => b?.t === 'button' && b.action === 'next');
 		// The heading's words without its marks: a button holds no link.
 		const b = el('button', 'tb');
 		b.textContent = heading
@@ -1075,9 +1075,11 @@ export function mountForm(o) {
 			wrap.classList.add('lk');
 		}
 		body.replaceChildren();
-		if (asTab && l.template !== 'image-only') body.append(tab(step));
+		// Shopper values filled in as text (./values.js), from this form's answers too; false: hidden.
+		const blocks = step.blocks.map((b) => o.fill?.(b, state.answers) ?? b);
+		if (asTab && l.template !== 'image-only') body.append(tab(blocks));
 		else
-			for (const [index, block] of step.blocks.entries()) {
+			for (const [index, block] of blocks.entries()) {
 				const node =
 					isObject(block) && Object.hasOwn(BLOCKS, block.t)
 						? BLOCKS[block.t](block)

package/src/onsite/rich-text.js

@@ -5,7 +5,18 @@
  *   RichText = string | Array<string | { b: RichText } | { i: RichText } | { a: RichText, href }>
  */
 
-const MAX_DEPTH = 6;
+/** How deep marks nest before the rest is dropped. */
+export const MAX_DEPTH = 6;
+
+/** Whether a rich text holds a shopper value node (one with a `v`), to the depth it is drawn. */
+export const holdsValue = (text, depth = 0) =>
+	depth <= MAX_DEPTH &&
+	typeof text === 'object' &&
+	!!text &&
+	(Array.isArray(text)
+		? text.some((run) => holdsValue(run, depth + 1))
+		: typeof text.v === 'string' ||
+			holdsValue(text.b ?? text.i ?? text.a, depth + 1));
 
 /** The href as an https URL, or null. */
 export function httpsHref(href) {

package/src/onsite/values-loader.js

@@ -0,0 +1,6 @@
+/**
+ * Shopper values in a form's text, only for a form whose text has one: a bundler splits this import
+ * out of ./onsite, and the CDN build swaps this module for cdn/values-loader.js, which loads
+ * dist/onsite-values.min.js.
+ */
+export const loadValues = () => import('./values.js');

package/src/onsite/values.js

@@ -0,0 +1,218 @@
+/**
+ * Shopper values in a form's text (ADR 0064 as amended 2026-11-03): a heading's or a paragraph's
+ * value nodes, `{ v, fallback, format? }`, filled in the browser from what this page already
+ * knows: the basket in this visit, the name the page gave (`hp.onsite.values`), and the shopper's
+ * own answers. Each is drawn as text, never markup; a value this page does not know shows its
+ * fallback, or with the block's `missing: "hide"` the block is not shown. Its own chunk, loaded
+ * only for a form whose text has a value.
+ */
+
+import { money } from './money.js';
+import { holdsValue, MAX_DEPTH } from './rich-text.js';
+
+const VALUES = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-values',
+);
+/** The longest a value shows, its ellipsis included. */
+const MAX = 60;
+// Built from a string so the bundle stays ASCII whatever charset a CDN serves it with: esbuild
+// writes a literal's characters as they are.
+// biome-ignore lint/complexity/useRegexLiterals: a literal is bundled as non-ASCII characters.
+const UNSEEN = new RegExp(
+	'[\\u0000-\\u001f\\u007f-\\u009f\\u200b-\\u200f\\u202a-\\u202e\\u2060-\\u206f\\ufeff]',
+	'g',
+);
+/**
+ * How a value shows when its node names no format: the first of its catalogue `formats` and its
+ * `plural` (spec/onsite/values.json; a test holds the two the same). Text otherwise.
+ */
+export const DEFAULTS = {
+	basket_value: { style: 'money' },
+	basket_items: { style: 'number', plural: { one: 'item', other: 'items' } },
+};
+/** The prefix of an answer's key (the catalogue's `answers.prefix`). */
+export const ANSWER_PREFIX = 'answer.';
+/** The values only the page knows, given to `hp.onsite.values` or `startOnsite`. */
+export const PAGE = ['first_name'];
+const UNITS = [
+	['year', 31536e6],
+	['month', 2592e6],
+	['week', 6048e5],
+	['day', 864e5],
+	['hour', 36e5],
+	['minute', 6e4],
+];
+
+/** A value as the text it shows: one line, without controls, at most MAX characters. */
+export function clean(value) {
+	const chars = [
+		...String(value).replace(UNSEEN, '').replace(/\s+/g, ' ').trim(),
+	];
+	return chars.length > MAX
+		? `${chars
+				.slice(0, MAX - 1)
+				.join('')
+				.trimEnd()}…`
+		: chars.join('');
+}
+
+/** `lang` when the browser takes it as a locale, else the browser's own. */
+function localeOf(lang) {
+	try {
+		return Intl.getCanonicalLocales(lang || [])[0];
+	} catch {
+		return undefined;
+	}
+}
+
+/** The `Intl` formatters made so far, by kind, language and options: one each for a page. */
+const formatters = new Map();
+const formatter = (key, make) => {
+	if (!formatters.has(key)) formatters.set(key, make());
+	return formatters.get(key);
+};
+
+/**
+ * `raw` as text in `style`: a number, money in `currency`, a date, a time from now, or text; with
+ * `plural` (`{ one, other }`) a number is followed by the word for it. Null when it cannot be.
+ */
+export function formatValue(raw, style, { lang, currency, plural, now } = {}) {
+	if (raw === null || raw === undefined || raw === '') return null;
+	try {
+		if (style === 'date' || style === 'relative') {
+			const at = typeof raw === 'number' ? raw : Date.parse(raw);
+			if (!Number.isFinite(at)) return null;
+			if (style === 'date')
+				return formatter(
+					`date ${lang}`,
+					() => new Intl.DateTimeFormat(lang, { dateStyle: 'medium' }),
+				).format(at);
+			const gap = at - (now ?? Date.now());
+			const [unit, ms] = UNITS.find(([, ms]) => Math.abs(gap) >= ms) ?? [
+				'minute',
+				6e4,
+			];
+			return formatter(
+				`relative ${lang}`,
+				() => new Intl.RelativeTimeFormat(lang, { numeric: 'auto' }),
+			).format(Math.round(gap / ms), unit);
+		}
+		if (style !== 'number' && style !== 'money') return clean(raw) || null;
+		if (typeof raw !== 'number' || !Number.isFinite(raw)) return null;
+		const numbers =
+			style === 'money'
+				? formatter(`money ${lang} ${currency}`, () => money(lang, currency))
+				: formatter(`number ${lang}`, () => new Intl.NumberFormat(lang));
+		// An unknown currency: the value is not known, so its fallback shows.
+		if (!numbers) return null;
+		const text = numbers.format(raw);
+		if (!plural) return text;
+		const one =
+			formatter(`plural ${lang}`, () => new Intl.PluralRules(lang)).select(
+				raw,
+			) === 'one';
+		return clean(`${text} ${(one ? plural.one : plural.other) ?? ''}`);
+	} catch {
+		// An unknown locale: the value is not known.
+		return null;
+	}
+}
+
+/**
+ * The fill the renderer runs on each block it draws: a heading or paragraph with its values as
+ * text, or `false` when one is not known and the block says `missing: "hide"`; any other block,
+ * and one without values, as it was. `access.values()` is what the client knows of this visit;
+ * `given` the page's own values from `startOnsite`, which `hp.onsite.values` replaces.
+ *
+ * @param {{ locale?: string, questions?: Array<{ key: string, options?: Array<{ value: string, label: string }> }> }} form
+ * @param {{ values?: () => { basket_value?: number|null, basket_items?: number|null, currency?: string|null, answers?: Record<string, string[]>|null } }} access
+ * @param {Record<string, unknown>} [given]
+ */
+export function fillFor(form, access, given) {
+	const lang = localeOf(
+		form.locale || globalThis.document?.documentElement.lang,
+	);
+	const questions = new Map(
+		(Array.isArray(form.questions) ? form.questions : []).map((q) => [
+			q?.key,
+			q,
+		]),
+	);
+	// What the page knows, read once for the blocks of a step: they are filled together.
+	let known = null;
+	const read = () => {
+		if (!known) {
+			const page = globalThis.window?.[VALUES] ?? given ?? {};
+			known = { ...access.values?.() };
+			for (const key of PAGE)
+				if (typeof page[key] === 'string') known[key] = page[key];
+			queueMicrotask(() => {
+				known = null;
+			});
+		}
+		return known;
+	};
+
+	/** A choice question's answer as its options' labels: this form's, else the ones kept. */
+	const answer = (key, asked) => {
+		const q = questions.get(key);
+		const { answers } = read();
+		// Answers are shown back only where they may be kept: under personalisation consent.
+		if (!q || !answers) return null;
+		const chosen = asked?.[key] ?? answers[key];
+		const labels = (Array.isArray(chosen) ? chosen : []).flatMap((value) => {
+			const label = q.options?.find((o) => o?.value === value)?.label;
+			return typeof label === 'string' && label ? [clean(label)] : [];
+		});
+		if (!labels.length) return null;
+		try {
+			return formatter(
+				`list ${lang}`,
+				() => new Intl.ListFormat(lang, { type: 'conjunction' }),
+			).format(labels);
+		} catch {
+			// A browser without Intl.ListFormat (Safari before 14.1).
+			return labels.join(', ');
+		}
+	};
+
+	const resolve = (node, asked) => {
+		const key = node.v;
+		const set =
+			node.format && typeof node.format === 'object'
+				? node.format
+				: DEFAULTS[key];
+		const raw = key.startsWith(ANSWER_PREFIX)
+			? answer(key.slice(ANSWER_PREFIX.length), asked)
+			: read()[key];
+		return formatValue(raw, set?.style ?? 'text', {
+			lang,
+			currency: read().currency,
+			plural: set?.plural,
+		});
+	};
+
+	return (block, asked) => {
+		if (
+			(block?.t !== 'heading' && block?.t !== 'text') ||
+			!holdsValue(block.text)
+		)
+			return block;
+		let missed = false;
+		const walk = (text, depth) => {
+			if (typeof text === 'string' || depth > MAX_DEPTH) return text;
+			if (Array.isArray(text)) return text.map((t) => walk(t, depth + 1));
+			if (!text || typeof text !== 'object') return text;
+			if (typeof text.v === 'string') {
+				const value = resolve(text, asked);
+				if (value === null) missed = true;
+				return value ?? clean(text.fallback ?? '');
+			}
+			const tag =
+				'b' in text ? 'b' : 'i' in text ? 'i' : 'a' in text ? 'a' : null;
+			return tag ? { ...text, [tag]: walk(text[tag], depth + 1) } : text;
+		};
+		const text = walk(block.text, 0);
+		return missed && block.missing === 'hide' ? false : { ...block, text };
+	};
+}

package/src/onsite/visit-audiences.js

@@ -7,7 +7,11 @@
  * limited and the visitor allowed personalisation.
  */
 
-import { catalogueBrowse, sessionRulesHold } from '../session/rules.js';
+import {
+	answeredRulesHold,
+	catalogueBrowse,
+	sessionRulesHold,
+} from '../session/rules.js';
 
 /** What the decide request accepts: more, or a longer slug, and it ignores the lot. */
 const MAX_AUDIENCES = 100;
@@ -45,7 +49,9 @@ export function prefetch(api) {
  *   personalisation consent.
  * @param {string[]} [targets] The audiences the form is limited to.
  * @param {string[]} [given] The session audiences the page gave (`startOnsite`'s `audiences()`).
- * @returns {Promise<string[]>}
+ * @returns {Promise<{ claims: string[], answered: string[] }>} `claims`, the slugs to send as
+ *   `visit_audiences`; `answered`, the early audiences that hold on the answers this device keeps,
+ *   as `answered_audiences`.
  */
 export async function visitAudiences(api, signals, targets = [], given = []) {
 	const datafile = await prefetch(api);
@@ -54,7 +60,12 @@ export async function visitAudiences(api, signals, targets = [], given = []) {
 		? datafile.session_audiences
 		: [];
 	const held = datafile && visit ? holdingAudiences(datafile, visit) : [];
-	return firstWanted([...held, ...given], targets, session);
+	const claims = firstWanted([...held, ...given], targets, session);
+	const answered =
+		datafile && visit
+			? holdingAudiences(datafile, visit, answeredRulesHold)
+			: [];
+	return { claims, answered: firstWanted(answered, targets, session) };
 }
 
 /** `slugs`, once each, `targets` and their transitive `requires` first, capped. */
@@ -79,16 +90,15 @@ export function firstWanted(slugs, targets, session) {
 /**
  * @param {{ session_audiences?: unknown, browse_categories?: unknown }} datafile `GET /v1/audiences/datafile`.
  * @param {object} signals This visit's session signals.
+ * @param {(audience: object, signals: object) => boolean} [holds]
  * @returns {string[]}
  */
-export function holdingAudiences(datafile, signals) {
+export function holdingAudiences(datafile, signals, holds = sessionRulesHold) {
 	const audiences = Array.isArray(datafile?.session_audiences)
 		? datafile.session_audiences
 		: [];
 	const visit = catalogueBrowse(signals, datafile.browse_categories ?? null);
 	return audiences
-		.filter(
-			(audience) => isSlug(audience?.slug) && sessionRulesHold(audience, visit),
-		)
+		.filter((audience) => isSlug(audience?.slug) && holds(audience, visit))
 		.map((audience) => audience.slug);
 }

package/src/onsite-facade.js

@@ -1,6 +1,7 @@
 /**
- * `hp.onsite`: open (`show`) a form by hand, listen to the forms, keep the screen clear, or read why
- * each form did or did not show, all callable before the onsite runtime has loaded. Listeners and
+ * `hp.onsite`: open (`show`) a form by hand, listen to the forms, keep the screen clear, give a form's
+ * text what the page knows of the shopper, or read why each form did or did not show, all callable
+ * before the onsite runtime has loaded. Listeners and
  * suppressions wait on the page for the runtime. An `open` made before it started waits for it, and resolves with what
  * the runtime did, or `false` once the page knows no runtime will start; nothing here throws.
  */
@@ -15,6 +16,9 @@ const LISTENERS = Symbol.for(
 const SUPPRESSED = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite.suppressed',
 );
+const PAGE_VALUES = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-values',
+);
 const EVENTS = ['shown', 'submitted', 'apply', 'closed', 'held', 'nothing'];
 const MAX_PENDING = 10;
 
@@ -93,6 +97,20 @@ export const onsite = Object.freeze({
 			/* never into the page */
 		}
 	},
+	/**
+	 * What the page knows of the shopper for a form's text: `{ first_name }`. Kept in this page's
+	 * memory only and drawn as text in a form that shows it; never sent, stored or logged. Each call
+	 * replaces the last, and `values({})` forgets it (a sign-out).
+	 */
+	values(given) {
+		try {
+			const w = page();
+			if (w)
+				w[PAGE_VALUES] = given && typeof given === 'object' ? { ...given } : {};
+		} catch {
+			/* never into the page */
+		}
+	},
 	/**
 	 * Each form's state, as `debug`, once the page knows whether onsite forms run on it: when the
 	 * runtime has started, or `[]` once none will (not opted in, no live form, the chunk failed).