@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.18.0

package/src/settings.js

@@ -0,0 +1,230 @@
+/**
+ * Remote settings: everything tenant-level, fetched from the API rather than configured in code.
+ *
+ *   GET {apiHost}/v1/projects/{writeKey}/settings
+ *
+ * The path analytics-next already uses for cdn.segment.com, so the same response also drives the
+ * Segment path when its `cdnURL` points at the apiHost. An unknown or disabled key answers
+ * `{ hp: { enabled: false } }`, never 404.
+ *
+ * The last good answer is cached, only under an analytics grant (it is a device write), and a page
+ * with a cache starts from it and revalidates in the background. Until the grant the HTTP cache
+ * (`max-age=10` and an `ETag`) saves the round trip or answers a `304`.
+ */
+
+import { storageKey, storageName } from './storage-scope.js';
+
+const isObject = (v) =>
+	v !== null && typeof v === 'object' && !Array.isArray(v);
+const isStringArray = (v) =>
+	Array.isArray(v) && v.every((s) => typeof s === 'string');
+
+export const DISABLED = Object.freeze({ enabled: false });
+
+/**
+ * Whether a tracking plan lets the track event `name` through. Segment's `plan.track` semantics: an
+ * event marked `enabled: false` is dropped at the source, and `__default` covers events the plan
+ * does not list.
+ */
+export function planAllows(plan, name) {
+	const track = plan?.track;
+	if (!isObject(track)) return true;
+	const rule = Object.hasOwn(track, name) ? track[name] : track.__default;
+	return rule?.enabled !== false;
+}
+
+export function settingsUrl(apiHost, writeKey) {
+	return `${resolveApiHost(apiHost)}/v1/projects/${encodeURIComponent(writeKey)}/settings`;
+}
+
+/**
+ * Where the SDK talks to when the integrator names no host: the one host every client uses, for
+ * test and live keys alike. The key alone selects the tenant, the property and test or live, as
+ * with Stripe and LaunchDarkly; a host is only for a first-party proxy or our own nonprod testing.
+ */
+export const DEFAULT_API_HOST = 'https://hp.thgingenuity.com';
+
+/** The integrator's `apiHost` as an origin, DEFAULT_API_HOST when none is given, null when invalid. */
+export function resolveApiHost(host) {
+	return host === undefined || host === null || host === ''
+		? DEFAULT_API_HOST
+		: apiOrigin(host);
+}
+
+/**
+ * An API host as an origin. The settings give a bare host (`api.example.com`, the OpenAPI server
+ * variable); an integrator may write either. Anything else is not a host.
+ */
+export function apiOrigin(host) {
+	if (typeof host !== 'string') return null;
+	const value = host.trim().replace(/\/+$/, '');
+	if (/^https?:\/\/[^/\s]+$/i.test(value)) return value;
+	if (/^[a-z0-9.-]+(:\d+)?$/i.test(value)) return `https://${value}`;
+	return null;
+}
+
+/** The purposes the property asks for, or null when the settings do not say (report them all). */
+function readPurposes(raw) {
+	if (!isObject(raw)) return null;
+	const asked = Object.fromEntries(
+		Object.entries(raw).filter(([, value]) => typeof value === 'boolean'),
+	);
+	return Object.keys(asked).length ? asked : null;
+}
+
+const isFraction = (value) =>
+	typeof value === 'number' && value >= 0 && value <= 1;
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Console logging (3.18): on for everyone, or for a session opened with `?hp_debug=<token>`, checked
+ * against the token's hash. Off when the settings do not say.
+ */
+function readDebug(raw) {
+	if (!isObject(raw)) return { enabled: false, tokenSha256: null };
+	return {
+		enabled: raw.enabled === true,
+		tokenSha256:
+			typeof raw.tokenSha256 === 'string' && SHA256_HEX.test(raw.tokenSha256)
+				? raw.tokenSha256
+				: null,
+	};
+}
+
+/**
+ * The personalisation holdout per property, `{ share, ramp, salt, readoutSlots }`, or null when the settings carry
+ * none. An entry that is not a share in [0, 1] with a non-empty salt, or whose ramp is neither null
+ * nor in [0, 1], is dropped rather than guessed at: a wrong salt or ramp would assign different
+ * shoppers here than at the edge. A ramp absent from older settings is null: no ramp.
+ */
+function readHoldouts(raw) {
+	if (!isObject(raw)) return null;
+	const holdouts = Object.fromEntries(
+		Object.entries(raw)
+			.filter(
+				([, h]) =>
+					isObject(h) &&
+					isFraction(h.share) &&
+					(h.ramp == null || isFraction(h.ramp)) &&
+					typeof h.salt === 'string' &&
+					h.salt !== '',
+			)
+			.map(([propertyId, h]) => [
+				propertyId,
+				{
+					share: h.share,
+					ramp: h.ramp ?? null,
+					salt: h.salt,
+					// The slots split 50/50 between the bandit and their default; none when absent or malformed.
+					...(isStringArray(h.readoutSlots) &&
+						h.readoutSlots.length > 0 && { readoutSlots: h.readoutSlots }),
+				},
+			]),
+	);
+	return Object.keys(holdouts).length ? holdouts : null;
+}
+
+/** An RFC 6265 cookie name, as the control plane validates it. */
+const COOKIE_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,128}$/;
+
+/**
+ * Where device ids come from (3.6): `{ source: 'site_cookie', cookie }` or `{ source: 'hp_cookie' }`.
+ * Null when the settings do not say, which is what every source meant before 3.6 (the cookie named
+ * in the integration's code), and for anything malformed rather than a guess at what was meant.
+ */
+function readAnonymousId(raw) {
+	if (!isObject(raw)) return null;
+	if (raw.source === 'hp_cookie') return { source: 'hp_cookie' };
+	if (raw.source !== 'site_cookie') return null;
+	if (raw.cookie == null) return { source: 'site_cookie', cookie: null };
+	return typeof raw.cookie === 'string' && COOKIE_NAME.test(raw.cookie)
+		? { source: 'site_cookie', cookie: raw.cookie }
+		: null;
+}
+
+/**
+ * The settings response as the SDK uses it, or DISABLED for anything that does not switch it on.
+ * Unknown fields are ignored, so the API can add to the response without breaking a deployed SDK.
+ * `propertyId` is null for a source scoped to several properties: the page then names its own.
+ */
+export function readSettings(body) {
+	const hp = isObject(body) ? body.hp : null;
+	if (!isObject(hp) || hp.enabled !== true) return DISABLED;
+	return {
+		enabled: true,
+		propertyId:
+			typeof hp.propertyId === 'string' && hp.propertyId !== ''
+				? hp.propertyId
+				: null,
+		environment: typeof hp.environment === 'string' ? hp.environment : null,
+		// Strict is the only mode, so only which purposes are reported can vary.
+		consentPurposes: readPurposes(hp.consent?.purposes),
+		queryParamAllowlist: isStringArray(hp.queryParamAllowlist)
+			? hp.queryParamAllowlist
+			: null,
+		anonymousId: readAnonymousId(hp.anonymousId),
+		apiHost: apiOrigin(hp.apiHost),
+		holdouts: readHoldouts(hp.holdouts),
+		// The share of visitors sent for (3.18). Anything that is not a share sends for everyone.
+		sampleRate: isFraction(hp.sampleRate) ? hp.sampleRate : 1,
+		debug: readDebug(hp.debug),
+		plan:
+			isObject(body.plan) && isObject(body.plan.track)
+				? { track: body.plan.track }
+				: null,
+	};
+}
+
+/**
+ * The settings for `writeKey`: DISABLED when the API says so, null when it could not be asked (an
+ * outage keeps whatever the cache last held rather than switching a working site off).
+ */
+export async function fetchSettings(
+	apiHost,
+	writeKey,
+	fetchImpl = globalThis.fetch,
+) {
+	try {
+		const res = await fetchImpl(settingsUrl(apiHost, writeKey), {
+			credentials: 'omit',
+			headers: { accept: 'application/json' },
+		});
+		if (!res.ok) return null;
+		return readSettings(await res.json());
+	} catch {
+		return null;
+	}
+}
+
+const cacheKey = (writeKey) => storageKey(storageName('settings'), writeKey);
+
+/** The last good settings this browser kept for `writeKey`, or null. */
+export function cachedSettings(writeKey) {
+	try {
+		const raw = localStorage.getItem(cacheKey(writeKey));
+		if (!raw) return null;
+		const settings = JSON.parse(raw);
+		return settings?.enabled === true ? settings : null;
+	} catch {
+		return null;
+	}
+}
+
+export function cacheSettings(writeKey, settings) {
+	try {
+		if (settings?.enabled === true)
+			localStorage.setItem(cacheKey(writeKey), JSON.stringify(settings));
+		else localStorage.removeItem(cacheKey(writeKey));
+	} catch {
+		/* no storage: the next page fetches again */
+	}
+}
+
+export function forgetSettings(writeKey) {
+	try {
+		localStorage.removeItem(cacheKey(writeKey));
+	} catch {
+		/* nothing was kept */
+	}
+}

package/src/shape.js

@@ -0,0 +1,120 @@
+/**
+ * Event shaping shared by both delivery paths (the built-in transport and analytics-next).
+ */
+
+/**
+ * The normalised page taxonomy, mirroring the enum in schemas/common/context.json.
+ *
+ * Duplicated here rather than imported because the SDK ships without the schema package and
+ * must stay dependency-free in a browser. assert_page_types_match keeps the two in step.
+ */
+export const PAGE_TYPES = new Set([
+	'home',
+	'list',
+	'product',
+	'search',
+	'basket',
+	'checkout',
+	'order_confirmation',
+	'login',
+	'register',
+	'account',
+	'info',
+	'blog',
+	'other',
+]);
+
+/**
+ * Drop keys whose value is null or undefined, recursively: absent means "does not apply", which
+ * is what almost every storefront null means.
+ *
+ * For `properties` only. Context nulls are load-bearing (`consent.analytics: null` means the CMP
+ * has not answered). `products: null` is kept, so a failed product mapping still fails validation
+ * rather than looking like an empty result.
+ */
+const NEVER_PRUNE = new Set(['products']);
+
+/** Restore an exempt key only when it was null; an array stays pruned. */
+const isNullish = (v) => v === null || v === undefined;
+
+/**
+ * A Date becomes the ISO string JSON would make of it. A cycle is left in place, not followed: the
+ * transport drops an event it cannot serialise, where following it would overflow the stack.
+ */
+function pruneNulls(value, ancestors = new WeakSet()) {
+	if (value instanceof Date) return value.toJSON();
+	if (value === null || typeof value !== 'object') return value;
+	if (ancestors.has(value)) return value;
+	ancestors.add(value);
+	const out = Array.isArray(value)
+		? value.map((v) => pruneNulls(v, ancestors))
+		: Object.fromEntries(
+				Object.entries(value)
+					.filter(([, v]) => !isNullish(v))
+					.map(([k, v]) => [k, pruneNulls(v, ancestors)]),
+			);
+	ancestors.delete(value);
+	return out;
+}
+
+/** Properties as they go on the wire: nulls pruned, `products: null` kept visible. */
+export function pruneProperties(properties) {
+	if (!properties) return properties;
+	const pruned = pruneNulls(properties);
+	for (const key of NEVER_PRUNE) {
+		if (key in properties && isNullish(properties[key]))
+			pruned[key] = properties[key];
+	}
+	return pruned;
+}
+
+export function detectNavigationTrigger() {
+	try {
+		const nav = performance.getEntriesByType('navigation')[0];
+		if (!nav) return null;
+		return ['navigate', 'reload', 'back_forward', 'prerender'].includes(
+			nav.type,
+		)
+			? nav.type
+			: 'navigate';
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Values platforms put in an id field to mean "no id". Kept as an id, one shared by every visitor
+ * would merge them all into one person in the identity graph; the gateway strips them too.
+ */
+const PLACEHOLDER_IDS = new Set([
+	'',
+	'unknown',
+	'undefined',
+	'null',
+	'none',
+	'nil',
+	'nan',
+	'anonymous',
+	'guest',
+	'0',
+	'-1',
+]);
+
+/** An id, or null when the value identifies nobody. */
+export function realId(value) {
+	if (value == null) return null;
+	const text = String(value).trim();
+	return PLACEHOLDER_IDS.has(text.toLowerCase()) ? null : text;
+}
+
+/** A random UUID: event messageIds and the SDK's own device id. */
+export function uuid() {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID)
+		return crypto.randomUUID();
+	// Fallback for older Safari. Uniqueness matters (it is the idempotency key); cryptographic
+	// quality does not.
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+		const r = (Math.random() * 16) | 0;
+		return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+	});
+}

package/src/social-proof.js

@@ -0,0 +1,139 @@
+/**
+ * Social proof for the storefront: how many other shoppers touched a product recently.
+ *
+ * The one part of this package that reads rather than writes. Failure is silence everywhere: a
+ * badge is decoration, so every path resolves to "no badge" rather than rejecting.
+ */
+
+import { parseConsentCookie, servingHeaders } from './consent.js';
+import { getCookie } from './context.js';
+import { resolveApiHost } from './settings.js';
+import { storageName } from './storage-scope.js';
+
+const DEFAULT_TTL_MS = 60_000;
+
+/**
+ * The cap the API enforces, restated so the SDK chunks: a truncated answer would be
+ * indistinguishable from "not enough shoppers to say".
+ */
+const MAX_PER_REQUEST = 50;
+
+const chunk = (items, size) => {
+	const out = [];
+	for (let i = 0; i < items.length; i += size)
+		out.push(items.slice(i, i + size));
+	return out;
+};
+
+/**
+ * A social proof client for one storefront: `GET {apiHost}/v1/social-proof` on the public API,
+ * authenticated with the page's publishable key like every serving read.
+ *
+ * @param {object} options
+ * @param {string} [options.apiHost] As for bootstrap(): optional, for a first-party proxy.
+ * @param {string} options.writeKey  The page's publishable key. It names the organisation and the
+ *                                   properties it may read, so the property is not a parameter.
+ * @param {string} [options.propertyId] Only for a key scoped to several properties: which one.
+ * @param {number} [options.ttlMs]   How long to reuse an answer. The numbers move on a pipeline
+ *                                   schedule of tens of minutes.
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {() => object|null} [options.getConsent] The visitor's consent state, sent as `hp-consent`
+ *   like every serving request. Default: read back from the consent cookie the SDK writes; pass
+ *   `() => analytics.consent` to use the live state instead.
+ */
+export function createSocialProof({
+	apiHost,
+	writeKey,
+	propertyId,
+	ttlMs = DEFAULT_TTL_MS,
+	fetchImpl,
+	getConsent,
+}) {
+	const base = resolveApiHost(apiHost);
+	if (!base)
+		throw new Error(
+			'createSocialProof: apiHost, when given, must be a host or an http(s) origin',
+		);
+	if (!writeKey) throw new Error('createSocialProof: writeKey is required');
+
+	const doFetch = fetchImpl ?? globalThis.fetch?.bind(globalThis);
+	const scope = propertyId
+		? `&property_id=${encodeURIComponent(propertyId)}`
+		: '';
+	/** productId -> { at, value }. Per-page, deliberately: this is not worth a storage quota. */
+	const cache = new Map();
+
+	const fresh = (entry) => entry && Date.now() - entry.at < ttlMs;
+	const consent =
+		getConsent ?? (() => parseConsentCookie(getCookie(storageName('consent'))));
+
+	async function request(query) {
+		if (!doFetch) return null;
+		try {
+			const res = await doFetch(`${base}/v1/social-proof?${query}${scope}`, {
+				// No credentials: the answer is the same for every visitor, and a cookie would make it
+				// uncacheable.
+				credentials: 'omit',
+				headers: {
+					accept: 'application/json',
+					authorization: `Bearer ${writeKey}`,
+					...servingHeaders(consent()),
+				},
+			});
+			if (!res.ok) return null;
+			return await res.json();
+		} catch {
+			return null;
+		}
+	}
+
+	return {
+		/**
+		 * Counts and a resolved badge for each product, keyed by product id. Products below the
+		 * warehouse's visitor floor are absent.
+		 */
+		async forProducts(productIds, { keyType = 'product' } = {}) {
+			const wanted = [
+				...new Set((productIds ?? []).map(String).filter(Boolean)),
+			];
+			const result = new Map();
+			const missing = [];
+
+			for (const id of wanted) {
+				const hit = cache.get(id);
+				if (fresh(hit)) {
+					if (hit.value) result.set(id, hit.value);
+				} else missing.push(id);
+			}
+
+			await Promise.all(
+				chunk(missing, MAX_PER_REQUEST).map(async (batch) => {
+					const body = await request(
+						`key_type=${encodeURIComponent(keyType)}&products=${batch.map(encodeURIComponent).join(',')}`,
+					);
+					const found = new Set();
+					for (const product of body?.products ?? []) {
+						found.add(product.productId);
+						cache.set(product.productId, { at: Date.now(), value: product });
+						result.set(product.productId, product);
+					}
+					// Cache the absences too. Without this, every product below the floor is re-requested
+					// on every render — which on a listing page is most of the long tail, every time.
+					for (const id of batch) {
+						if (!found.has(id)) cache.set(id, { at: Date.now(), value: null });
+					}
+				}),
+			);
+
+			return result;
+		},
+
+		/** The catalogue's trending head, for a "Trending now" rail. Empty array on any failure. */
+		async trending(limit = 24, { keyType = 'product' } = {}) {
+			const body = await request(
+				`key_type=${encodeURIComponent(keyType)}&trending=${Number(limit) || 24}`,
+			);
+			return body?.products ?? [];
+		},
+	};
+}

package/src/spec-version.js

@@ -0,0 +1,4 @@
+// Generated from the spec by scripts/build-types.mjs. DO NOT EDIT: run `pnpm run build:types`.
+
+/** The event specification this SDK emits, stamped on every event as context.spec.version. */
+export const SPEC_VERSION = '1.10';

package/src/storage-scope.js

@@ -0,0 +1,164 @@
+/**
+ * Browser storage: one prefix, configurable names, and keys scoped to the tenant that owns them.
+ *
+ * Every key starts `thg_hp_` so a storage audit can name the SDK's footprint in one line; names are
+ * configurable for integrators with their own rules. Web storage is keyed by origin and one origin
+ * can serve several tenants, so every key is built here with the tenant in it: unscoped, one
+ * tenant's retry buffer would be replayed into another's ingest.
+ */
+
+/** Every name the SDK stores anything under, by what it holds. */
+export const DEFAULT_STORAGE_NAMES = Object.freeze({
+	/** Cookie: the visitor's consent decision, for the site's own servers to forward. */
+	consent: 'thg_hp_consent',
+	/** localStorage, per property: batches waiting for the ingest to answer. */
+	retry: 'thg_hp_retry',
+	/** localStorage per property and session (sessionStorage until a session is bound). */
+	sessionSignals: 'thg_hp_session_signals',
+	/** sessionStorage, per property: the identify already sent this session. */
+	identified: 'thg_hp_identified',
+	/** sessionStorage, per property: the previous page view's messageId. */
+	previousPage: 'thg_hp_prev_page',
+	/** sessionStorage, per property: the decisions in force, latest per slot (3.7). */
+	decisions: 'thg_hp_decisions',
+	/** localStorage, per write key: the last good remote settings. */
+	settings: 'thg_hp_settings',
+	/**
+	 * sessionStorage, per property: events held for an unanswered CMP, carried to the next page.
+	 * Only with `holdAcrossPages` (3.5).
+	 */
+	held: 'thg_hp_held',
+	/**
+	 * sessionStorage, per write key: calls made through `hp` before the SDK started, carried to the
+	 * next page when the page navigates first (3.9).
+	 */
+	carried: 'thg_hp_carried',
+	/**
+	 * localStorage, per origin: the visit as the recommendations API takes it, kept for 30 minutes
+	 * after the last event, so `hp.recommendationContext()` answers on the next page before the SDK
+	 * has started there (3.11). Only while personalisation is granted.
+	 */
+	recommendationContext: 'thg_hp_recommendation_context',
+	/**
+	 * Cookie, one per browser: Hyper-Personalisation's device id, for a source set to `hp_cookie`
+	 * (3.6). 3.5's localStorage id under `<name>:<property>` is adopted into it and removed.
+	 */
+	anonymousId: 'thg_hp_anonymous_id',
+	/**
+	 * Cookie, one per browser: the session id the SDK keeps when the host has none, expiring 30
+	 * minutes after the last event (3.15). Only under a grant.
+	 */
+	session: 'thg_hp_session',
+	/**
+	 * Cookie, for the browser session: the preview token a trader opened the site with
+	 * (`?hp_preview=`), for the site's server to forward to `/v1/assignments` (3.15).
+	 */
+	preview: 'thg_hp_preview',
+	/**
+	 * sessionStorage, for the browser session: the debug token a developer opened the site with
+	 * (`?hp_debug=`), checked against the settings on every page (3.18).
+	 */
+	debug: 'thg_hp_debug',
+});
+
+/**
+ * The names the SDK used before the prefix, read once, moved and deleted. Only web storage: the
+ * consent cookie was already `thg_hp_consent`.
+ */
+const LEGACY_NAMES = {
+	retry: 'cdp.retry',
+	sessionSignals: 'cdp_session_signals',
+	identified: 'cdp_identified',
+	previousPage: 'cdp_prev_page_message_id',
+};
+
+let names = { ...DEFAULT_STORAGE_NAMES };
+let migrated = false;
+
+/**
+ * Rename what the SDK stores. Unnamed kinds keep their default, and calling with nothing restores
+ * every default. One SDK per page: the names are page-wide.
+ *
+ * @param {Partial<Record<keyof typeof DEFAULT_STORAGE_NAMES, string>>} [overrides]
+ */
+export function configureStorageNames(overrides) {
+	const next = { ...DEFAULT_STORAGE_NAMES };
+	for (const [kind, name] of Object.entries(overrides ?? {})) {
+		if (!(kind in DEFAULT_STORAGE_NAMES))
+			throw new Error(`storageNames: unknown kind "${kind}"`);
+		if (typeof name !== 'string' || !/^[\w.-]+$/.test(name)) {
+			throw new Error(
+				`storageNames.${kind} must be a non-empty cookie-safe name`,
+			);
+		}
+		next[kind] = name;
+	}
+	names = next;
+}
+
+/** @param {keyof typeof DEFAULT_STORAGE_NAMES} kind */
+export function storageName(kind) {
+	return names[kind];
+}
+
+/** "No tenant supplied": a literal segment, so no unscoped key is a prefix of a scoped one. */
+const NO_TENANT = '_';
+
+const segment = (tenant) =>
+	tenant == null || tenant === '' ? NO_TENANT : String(tenant);
+
+/**
+ * A storage key for `name`, owned by `tenant` and optionally further scoped by `suffix`.
+ *
+ * @param {string} name    The base key, e.g. storageName('retry').
+ * @param {string|null} [tenant]  The property/tenant id. Absent means a single-tenant host.
+ * @param {string|null} [suffix]  A further scope within the tenant, e.g. a session id.
+ */
+export function storageKey(name, tenant, suffix) {
+	const base = `${name}:${segment(tenant)}`;
+	return suffix == null || suffix === '' ? base : `${base}:${suffix}`;
+}
+
+/**
+ * The prefix matching every key `name` owns for `tenant`, for sweeping old scopes. The tenant
+ * comes first in a key so a sweep can never reach another tenant's.
+ */
+export function storagePrefix(name, tenant) {
+	return `${name}:${segment(tenant)}:`;
+}
+
+/**
+ * Move every legacy `cdp*` key to its current name, once per page, in both stores.
+ *
+ * The scope suffix (`:<tenant>[:<session>]`) is kept, so each tenant's data lands under its own new
+ * key. A value already under the new name wins: it is newer than anything the old SDK left.
+ * A rename writes nothing the visitor has not already allowed to be stored, and a refusal still
+ * clears the renamed keys exactly as it would have cleared the old ones.
+ */
+export function migrateLegacyStorage() {
+	if (migrated) return;
+	migrated = true;
+	for (const get of [() => localStorage, () => sessionStorage]) {
+		let store;
+		try {
+			store = get();
+			if (!store) continue;
+			for (const key of Object.keys(store)) {
+				for (const [kind, legacy] of Object.entries(LEGACY_NAMES)) {
+					if (key !== legacy && !key.startsWith(`${legacy}:`)) continue;
+					const renamed = names[kind] + key.slice(legacy.length);
+					if (store.getItem(renamed) === null)
+						store.setItem(renamed, store.getItem(key));
+					store.removeItem(key);
+				}
+			}
+		} catch {
+			/* no storage, or a quota: the old keys are simply left where they were */
+		}
+	}
+}
+
+/** Test seam: let the next migrateLegacyStorage() run again. */
+export function resetStorageMigration() {
+	migrated = false;
+}