@lifeaz/lors-helper 1.0.26 → 1.1.0

package/src/main.ts

@@ -50,8 +50,14 @@ export const PaymentProviderSchema = z.union([z.literal('_Mollie_'), z.literal('
 export type DeliveryMethod = '_Standard_' | '_Express_';
 export const DeliveryMethodSchema = z.union([z.literal('_Standard_'), z.literal('_Express_')]);
 
-export type DiscountValueType = '_Percentage_' | '_Fixed_Amount_' | '_Fixed_Total_' | '_Item_';
-export const DiscountValueTypeSchema = z.union([z.literal('_Percentage_'), z.literal('_Fixed_Amount_'), z.literal('_Fixed_Total_'), z.literal('_Item_')]);
+export type DiscountValueType = '_Percentage_' | '_Fixed_Amount_' | '_Fixed_Total_' | '_Item_' | '_Composite_';
+export const DiscountValueTypeSchema = z.union([z.literal('_Percentage_'), z.literal('_Fixed_Amount_'), z.literal('_Fixed_Total_'), z.literal('_Item_'), z.literal('_Composite_')]);
+
+export type DiscountEffectType = '_Gift_Item_' | '_Amount_Monthly_' | '_Amount_One_Time_' | '_Fixed_Total_';
+export const DiscountEffectTypeSchema = z.union([z.literal('_Gift_Item_'), z.literal('_Amount_Monthly_'), z.literal('_Amount_One_Time_'), z.literal('_Fixed_Total_')]);
+
+export type DiscountAmountKind = '_Fixed_' | '_Percentage_';
+export const DiscountAmountKindSchema = z.union([z.literal('_Fixed_'), z.literal('_Percentage_')]);
 
 export type DiscountTargetScope = '_Whole_Cart_' | '_Specific_Items_' | '_Item_Category_' | '_Delivery_';
 export const DiscountTargetScopeSchema = z.union([z.literal('_Whole_Cart_'), z.literal('_Specific_Items_'), z.literal('_Item_Category_'), z.literal('_Delivery_')]);
@@ -313,6 +319,17 @@ export const DiscountRuleNodeSchema: z.ZodType<DiscountRuleNode> = z.lazy(() =>
 	children: z.array(DiscountRuleNodeSchema),
 }));
 
+export const DiscountRuleEffectSchema = z.object({
+	effectId: uuidSchema,
+	type: DiscountEffectTypeSchema,
+	kind: DiscountAmountKindSchema.nullable(),
+	itemId: uuidSchema.nullable(),
+	relativeItemId: uuidSchema.nullable(),
+	quantity: z.number().int().positive().nullable(),
+	value: z.number().nullable(),
+});
+export type DiscountRuleEffect = z.infer<typeof DiscountRuleEffectSchema>;
+
 export const DiscountRuleSchema = z.object({
 	ruleId: uuidSchema,
 	discountId: uuidSchema,
@@ -320,6 +337,7 @@ export const DiscountRuleSchema = z.object({
 	priority: z.number(),
 	amountExclVat: z.number(),
 	quantityItemId: uuidSchema.nullable().optional(),
+	effects: z.array(DiscountRuleEffectSchema).optional().default([]),
 	root: DiscountRuleNodeSchema.nullable(),
 });
 export type DiscountRule = z.infer<typeof DiscountRuleSchema>;
@@ -372,6 +390,14 @@ export const CartSchema = z.object({
 	status: CartStatusSchema,
 	currentStep: CartStepSchema,
 	maxReachedStep: CartStepSchema,
+	/**
+	 * The funnel order frozen onto this cart when it was created.
+	 *
+	 * Null means the referential order. Frozen rather than re-resolved on every page because a
+	 * cart whose steps are reordered halfway through would strand the customer on a step the
+	 * server no longer expects them to be on.
+	 */
+	stepOrder: z.array(CartStepSchema).nullable().default(null),
 	profile: ProfileTypeSchema.nullable(),
 	offerType: OfferTypeSchema.nullable(),
 	paymentMethod: PaymentMethodSchema.nullable(),
@@ -632,3 +658,676 @@ export const PartnerSchema = z.object({
 	notices: z.array(PartnerNoticeSchema),
 });
 export type Partner = z.infer<typeof PartnerSchema>;
+
+// =============================================================================
+// MVT - Multivariate testing
+// =============================================================================
+
+export type MvtStatus = '_Draft_' | '_Scheduled_' | '_Running_' | '_Paused_' | '_Stopped_' | '_Archived_';
+export const MvtStatusSchema = z.union([z.literal('_Draft_'), z.literal('_Scheduled_'), z.literal('_Running_'), z.literal('_Paused_'), z.literal('_Stopped_'), z.literal('_Archived_')]);
+
+export type MvtScope = '_Storefront_' | '_Checkout_' | '_Global_';
+export const MvtScopeSchema = z.union([z.literal('_Storefront_'), z.literal('_Checkout_'), z.literal('_Global_')]);
+
+export type MvtUnit = '_Visitor_' | '_Session_' | '_Cart_';
+export const MvtUnitSchema = z.union([z.literal('_Visitor_'), z.literal('_Session_'), z.literal('_Cart_')]);
+
+export type MvtDevice = '_Mobile_' | '_Tablet_' | '_Desktop_';
+export const MvtDeviceSchema = z.union([z.literal('_Mobile_'), z.literal('_Tablet_'), z.literal('_Desktop_')]);
+
+export type MvtNodeKind = '_And_' | '_Or_' | '_Not_' | '_Leaf_';
+export const MvtNodeKindSchema = z.union([z.literal('_And_'), z.literal('_Or_'), z.literal('_Not_'), z.literal('_Leaf_')]);
+
+export type MvtOperator =
+	| '_Device_In_'
+	| '_Lang_In_'
+	| '_Country_In_'
+	| '_Profile_In_'
+	| '_Partner_In_'
+	| '_Partner_Absent_'
+	| '_Campaign_Seen_'
+	| '_Campaign_Not_Seen_'
+	| '_Visitor_Is_New_'
+	| '_Visitor_Is_Returning_'
+	| '_Utm_Source_In_'
+	| '_Utm_Medium_In_'
+	| '_Utm_Campaign_In_'
+	| '_Referrer_Matches_'
+	| '_Path_Matches_'
+	| '_Has_Cart_'
+	| '_Hour_Of_Day_Between_'
+	| '_Day_Of_Week_In_';
+
+export const MvtOperatorSchema = z.union([
+	z.literal('_Device_In_'),
+	z.literal('_Lang_In_'),
+	z.literal('_Country_In_'),
+	z.literal('_Profile_In_'),
+	z.literal('_Partner_In_'),
+	z.literal('_Partner_Absent_'),
+	z.literal('_Campaign_Seen_'),
+	z.literal('_Campaign_Not_Seen_'),
+	z.literal('_Visitor_Is_New_'),
+	z.literal('_Visitor_Is_Returning_'),
+	z.literal('_Utm_Source_In_'),
+	z.literal('_Utm_Medium_In_'),
+	z.literal('_Utm_Campaign_In_'),
+	z.literal('_Referrer_Matches_'),
+	z.literal('_Path_Matches_'),
+	z.literal('_Has_Cart_'),
+	z.literal('_Hour_Of_Day_Between_'),
+	z.literal('_Day_Of_Week_In_'),
+]);
+
+/**
+ * Operators that read no value at all. Storing an empty value list against one of them is not an
+ * error worth refusing, but the evaluator ignores it, and the Tools condition builder hides the
+ * value editor rather than offering a field that changes nothing.
+ */
+export const MVT_NULLARY_OPERATORS: readonly MvtOperator[] = [
+	'_Partner_Absent_',
+	'_Visitor_Is_New_',
+	'_Visitor_Is_Returning_',
+	'_Has_Cart_',
+];
+
+export type MvtOverrideOp = 'set' | 'merge' | 'remove' | 'reorder' | 'insert' | 'patch';
+export const MvtOverrideOpSchema = z.union([z.literal('set'), z.literal('merge'), z.literal('remove'), z.literal('reorder'), z.literal('insert'), z.literal('patch')]);
+
+export const MvtOverrideSchema = z.object({
+	slot: z.string().min(1),
+	op: MvtOverrideOpSchema,
+	value: z.unknown().optional(),
+	at: z.number().int().nonnegative().optional(),
+	match: z.object({ by: z.string().min(1), equals: z.string() }).optional(),
+});
+export type MvtOverride = z.infer<typeof MvtOverrideSchema>;
+
+export type MvtAudienceNode = {
+	kind: MvtNodeKind;
+	operator?: MvtOperator | null | undefined;
+	values?: string[] | undefined;
+	children?: MvtAudienceNode[] | undefined;
+};
+
+export const MvtAudienceNodeSchema: z.ZodType<MvtAudienceNode> = z.lazy(() => z.object({
+	kind: MvtNodeKindSchema,
+	operator: MvtOperatorSchema.nullable().optional(),
+	values: z.array(z.string()).optional(),
+	children: z.array(z.lazy(() => MvtAudienceNodeSchema)).optional(),
+}));
+
+export const MvtVariantSchema = z.object({
+	id: uuidSchema,
+	key: z.string().min(1),
+	name: z.string(),
+	weight: z.number().int().nonnegative(),
+	control: z.boolean(),
+	overrides: z.array(MvtOverrideSchema),
+});
+export type MvtVariant = z.infer<typeof MvtVariantSchema>;
+
+export const MvtExperimentSchema = z.object({
+	id: uuidSchema,
+	key: z.string().min(1),
+	name: z.string(),
+	description: z.string().nullable(),
+	status: MvtStatusSchema,
+	scope: MvtScopeSchema,
+	unit: MvtUnitSchema,
+	salt: z.string().min(1),
+	startsAt: z.string().nullable(),
+	endsAt: z.string().nullable(),
+	priority: z.number().int(),
+	exclusionGroup: z.string().nullable(),
+	trafficPct: z.number().int().min(0).max(100),
+	sticky: z.boolean(),
+	audience: MvtAudienceNodeSchema.nullable(),
+	variants: z.array(MvtVariantSchema),
+});
+export type MvtExperiment = z.infer<typeof MvtExperimentSchema>;
+
+export const MvtConfigSchema = z.object({
+	version: z.string(),
+	enabled: z.boolean(),
+	experiments: z.array(MvtExperimentSchema),
+});
+export type MvtConfig = z.infer<typeof MvtConfigSchema>;
+
+/**
+ * Everything the audience tree is allowed to read, resolved once and frozen into the assignment.
+ *
+ * Frozen matters more than it looks: a visitor who rotates their phone crosses the tablet/desktop
+ * breakpoint, and a context read live would move them to another variant mid-session. The context
+ * captured at assignment time is the one that decides, for as long as the assignment lives.
+ */
+export interface MvtContext {
+	unitId: string;
+	device: MvtDevice;
+	lang: string;
+	country: string | null;
+	profile: string | null;
+	partner: string | null;
+	seen: Record<string, number>;
+	utm: { source: string | null; medium: string | null; campaign: string | null };
+	referrer: string | null;
+	path: string;
+	hasCart: boolean;
+	firstSeenAt: number;
+	now: number;
+}
+
+export interface MvtDecision {
+	experimentKey: string;
+	experimentId: UUID;
+	variantKey: string;
+	variantId: UUID;
+	control: boolean;
+	overrides: MvtOverride[];
+}
+
+const MVT_RETURNING_AFTER_MS = 30 * 60 * 1000;
+
+/**
+ * FNV-1a, 32 bits.
+ *
+ * Chosen for being trivially reimplementable and byte-for-byte identical everywhere: the API, the
+ * storefront and the checkout each bucket independently, with no round trip, and any disagreement
+ * between them would show up as a visitor silently changing variant when they cross from one
+ * application to the other.
+ */
+export function mvtHash(input: string): number {
+	let hash = 0x811c9dc5;
+
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+
+	return hash >>> 0;
+}
+
+export function mvtBucket(salt: string, unitId: string, namespace: string = 'variant'): number {
+	return mvtHash(`${salt}:${namespace}:${unitId}`) % 10000;
+}
+
+export function mvtIsEligibleForTraffic(experiment: MvtExperiment, unitId: string): boolean {
+	if (experiment.trafficPct >= 100) return true;
+	if (experiment.trafficPct <= 0) return false;
+
+	return mvtBucket(experiment.salt, unitId, 'traffic') < experiment.trafficPct * 100;
+}
+
+/**
+ * Pick the variant a unit falls into, by weight, deterministically.
+ *
+ * Weights are relative rather than percentages so that 90/10, 50/50 and 34/33/33 are all
+ * expressible without the operator having to make anything add up. They are sorted by key first,
+ * so that the mapping from bucket range to variant depends only on the weights themselves and not
+ * on the order rows happened to come back from the database.
+ */
+export function mvtPickVariant(experiment: MvtExperiment, unitId: string): MvtVariant | null {
+	const variants = [...experiment.variants].sort((a, b) => a.key.localeCompare(b.key));
+	const total = variants.reduce((sum, v) => sum + Math.max(v.weight, 0), 0);
+
+	if (!variants.length || total <= 0) return null;
+
+	const target = (mvtBucket(experiment.salt, unitId) / 10000) * total;
+	let cursor = 0;
+
+	for (const variant of variants) {
+		cursor += Math.max(variant.weight, 0);
+
+		if (target < cursor) return variant;
+	}
+
+	return variants[variants.length - 1];
+}
+
+function mvtMatchesPattern(value: string | null, patterns: string[]): boolean {
+	if (value === null) return false;
+
+	const haystack = value.toLowerCase();
+
+	return patterns.some(pattern => {
+		const needle = pattern.trim().toLowerCase();
+
+		if (!needle) return false;
+		if (needle.startsWith('*') && needle.endsWith('*')) return haystack.includes(needle.slice(1, -1));
+		if (needle.startsWith('*')) return haystack.endsWith(needle.slice(1));
+		if (needle.endsWith('*')) return haystack.startsWith(needle.slice(0, -1));
+
+		return haystack === needle;
+	});
+}
+
+function mvtEvaluateLeaf(operator: MvtOperator, values: string[], context: MvtContext): boolean {
+	const lower = values.map(v => v.toLowerCase());
+
+	switch (operator) {
+		case '_Device_In_':            return values.includes(context.device);
+		case '_Lang_In_':              return lower.includes(context.lang.toLowerCase());
+		case '_Country_In_':           return context.country !== null && lower.includes(context.country.toLowerCase());
+		case '_Profile_In_':           return context.profile !== null && values.includes(context.profile);
+		case '_Partner_In_':           return context.partner !== null && lower.includes(context.partner.toLowerCase());
+		case '_Partner_Absent_':       return context.partner === null;
+		case '_Campaign_Seen_':        return values.some(v => context.seen[`campaign:${v}`] !== undefined);
+		case '_Campaign_Not_Seen_':    return values.every(v => context.seen[`campaign:${v}`] === undefined);
+		case '_Visitor_Is_New_':       return context.now - context.firstSeenAt < MVT_RETURNING_AFTER_MS;
+		case '_Visitor_Is_Returning_': return context.now - context.firstSeenAt >= MVT_RETURNING_AFTER_MS;
+		case '_Utm_Source_In_':        return mvtMatchesPattern(context.utm.source, values);
+		case '_Utm_Medium_In_':        return mvtMatchesPattern(context.utm.medium, values);
+		case '_Utm_Campaign_In_':      return mvtMatchesPattern(context.utm.campaign, values);
+		case '_Referrer_Matches_':     return mvtMatchesPattern(context.referrer, values);
+		case '_Path_Matches_':         return mvtMatchesPattern(context.path, values);
+		case '_Has_Cart_':             return context.hasCart;
+		case '_Hour_Of_Day_Between_': {
+			const hour = new Date(context.now).getHours();
+			const from = Number(values[0] ?? 0);
+			const to = Number(values[1] ?? 23);
+
+			return from <= to ? hour >= from && hour <= to : hour >= from || hour <= to;
+		}
+		case '_Day_Of_Week_In_':       return values.map(Number).includes(new Date(context.now).getDay());
+		default:                       return false;
+	}
+}
+
+/**
+ * Evaluate an audience tree.
+ *
+ * A null tree targets everyone, which is the common case and should not require building a node.
+ * An operator this build does not know returns false rather than throwing: a Tools release that
+ * introduces a new operator must never be able to break a front that has not shipped yet, and
+ * failing closed means the visitor stays on control instead of seeing a broken page.
+ */
+export function mvtEvaluateAudience(node: MvtAudienceNode | null, context: MvtContext): boolean {
+	if (!node) return true;
+
+	switch (node.kind) {
+		case '_And_':  return (node.children ?? []).every(child => mvtEvaluateAudience(child, context));
+		case '_Or_':   return (node.children ?? []).some(child => mvtEvaluateAudience(child, context));
+		case '_Not_':  return !(node.children ?? []).some(child => mvtEvaluateAudience(child, context));
+		case '_Leaf_': return node.operator ? mvtEvaluateLeaf(node.operator, node.values ?? [], context) : false;
+		default:       return false;
+	}
+}
+
+export function mvtIsWithinWindow(experiment: MvtExperiment, now: number): boolean {
+	if (experiment.startsAt && Date.parse(experiment.startsAt) > now) return false;
+	if (experiment.endsAt && Date.parse(experiment.endsAt) <= now) return false;
+
+	return true;
+}
+
+export function mvtIsLive(experiment: MvtExperiment, now: number): boolean {
+	return experiment.status === '_Running_' && mvtIsWithinWindow(experiment, now);
+}
+
+/**
+ * Resolve every decision for one unit, in one pass.
+ *
+ * Experiments are walked by descending priority so that exclusion groups resolve predictably: the
+ * first live experiment of a group claims it, and the rest are skipped for this unit. Without an
+ * order the winner would depend on row order, and two visitors could end up in mutually exclusive
+ * tests that were meant to be exclusive.
+ */
+export function mvtResolve(config: MvtConfig, context: MvtContext, forced: Record<string, string> = {}): MvtDecision[] {
+	if (!config.enabled) return [];
+
+	const decisions: MvtDecision[] = [];
+	const claimed = new Set<string>();
+	const experiments = [...config.experiments].sort((a, b) => b.priority - a.priority || a.key.localeCompare(b.key));
+
+	for (const experiment of experiments) {
+		const forcedKey = forced[experiment.key];
+
+		if (forcedKey) {
+			const variant = experiment.variants.find(v => v.key === forcedKey);
+
+			if (variant) decisions.push(mvtToDecision(experiment, variant));
+
+			continue;
+		}
+
+		if (!mvtIsLive(experiment, context.now)) continue;
+		if (experiment.exclusionGroup && claimed.has(experiment.exclusionGroup)) continue;
+		if (!mvtEvaluateAudience(experiment.audience, context)) continue;
+		if (!mvtIsEligibleForTraffic(experiment, context.unitId)) continue;
+
+		const variant = mvtPickVariant(experiment, context.unitId);
+
+		if (!variant) continue;
+		if (experiment.exclusionGroup) claimed.add(experiment.exclusionGroup);
+
+		decisions.push(mvtToDecision(experiment, variant));
+	}
+
+	return decisions;
+}
+
+function mvtToDecision(experiment: MvtExperiment, variant: MvtVariant): MvtDecision {
+	return {
+		experimentKey: experiment.key,
+		experimentId: experiment.id,
+		variantKey: variant.key,
+		variantId: variant.id,
+		control: variant.control,
+		overrides: variant.overrides,
+	};
+}
+
+// -----------------------------------------------------------------------------
+// Slot registry
+// -----------------------------------------------------------------------------
+
+export type MvtSlotKind = 'boolean' | 'number' | 'duration' | 'text' | 'i18n' | 'color' | 'image' | 'enum' | 'list' | 'object' | 'record';
+
+/**
+ * One editable field of a fixed-shape slot.
+ *
+ * The registry describes the shape rather than leaving the interface to infer it, because the
+ * alternative is an operator typing JSON into a textarea and discovering their mistake from a
+ * customer. A field the editor does not recognise degrades to a text input rather than
+ * disappearing, so adding a kind here never blanks out a control in an older build.
+ */
+export interface MvtSlotField {
+	key: string;
+	label: string;
+	kind: MvtSlotKind;
+	options?: readonly string[];
+}
+
+export interface MvtSlotDefinition {
+	key: string;
+	scope: MvtScope;
+	area: string;
+	label: string;
+	/** One short sentence an operator reads before deciding whether this is the slot they want. */
+	hint: string;
+	kind: MvtSlotKind;
+	ops: readonly MvtOverrideOp[];
+	/** Allowed values for an `enum`, or the closed set of entries for a constrained `list`. */
+	options?: readonly string[];
+	/** The named fields of an `object`, or the per-item fields of a list of objects. */
+	fields?: readonly MvtSlotField[];
+	/** The kind every value takes in a `record`, whose keys are open-ended. */
+	entryKind?: MvtSlotKind;
+	/** Which property identifies an item, for the `remove`, `patch` and `reorder` operations. */
+	itemKey?: string;
+	schema: z.ZodType<unknown>;
+}
+
+const i18nTextSchema = z.record(LangSchema, z.string());
+const colorSchema = z.string().regex(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+
+function slot(definition: MvtSlotDefinition): MvtSlotDefinition {
+	return definition;
+}
+
+/**
+ * The single source of truth for what a test is allowed to change.
+ *
+ * Shared by all four applications on purpose. The API validates writes against it, so a malformed
+ * override is refused at authoring time rather than discovered by a customer; Tools reads it to
+ * render a typed editor instead of a free JSON field; and the fronts read it to reject anything
+ * that slipped through anyway. A slot absent from this list simply does not exist, which is what
+ * keeps the blast radius of the whole feature bounded.
+ *
+ * Nothing monetary appears here, and nothing ever should. Prices, items and discounts are steered
+ * by campaigns and discounts, which carry their own controls and their own audit trail. A test
+ * decides how an offer is presented, never what it costs.
+ */
+export const MVT_SLOTS: readonly MvtSlotDefinition[] = [
+	slot({ key: 'storefront.sections.order', scope: '_Storefront_', area: 'Structure', label: 'Section order', hint: 'Reorder the blocks of a page. Blocks not listed keep their place at the end.', kind: 'list', ops: ['reorder', 'set'], itemKey: 'id', schema: z.array(z.string()) }),
+	slot({ key: 'storefront.sections.hidden', scope: '_Storefront_', area: 'Structure', label: 'Hidden sections', hint: 'Blocks to take off the page entirely.', kind: 'list', ops: ['set'], schema: z.array(z.string()) }),
+	slot({ key: 'storefront.texts', scope: '_Storefront_', area: 'Structure', label: 'Text overrides', hint: 'Replace any piece of copy, written per language.', kind: 'record', entryKind: 'i18n', ops: ['merge', 'set'], schema: z.record(z.string(), i18nTextSchema) }),
+	slot({ key: 'storefront.links', scope: '_Storefront_', area: 'Structure', label: 'Link targets', hint: 'Repoint a link somewhere else, for instance from the product sheet to a comparison page.', kind: 'record', entryKind: 'text', ops: ['merge', 'set'], schema: z.record(z.string(), z.string()) }),
+
+	slot({
+		key: 'storefront.ctas', scope: '_Storefront_', area: 'CTA', label: 'Call to action list',
+		hint: 'Hide, reorder or reword the buttons of a page.',
+		kind: 'list', ops: ['remove', 'reorder', 'patch', 'insert', 'set'], itemKey: 'label',
+		fields: [
+			{ key: 'label', label: 'Label', kind: 'text' },
+			{ key: 'variant', label: 'Style', kind: 'enum', options: ['primary', 'secondary', 'tertiary'] },
+			{ key: 'route', label: 'Internal route', kind: 'text' },
+			{ key: 'href', label: 'External link', kind: 'text' },
+		],
+		schema: z.array(z.record(z.string(), z.unknown())),
+	}),
+	slot({
+		key: 'storefront.cta.colors', scope: '_Storefront_', area: 'CTA', label: 'Call to action colors',
+		hint: 'Recolour the buttons, per style.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'primary', label: 'Primary', kind: 'color' },
+			{ key: 'secondary', label: 'Secondary', kind: 'color' },
+			{ key: 'tertiary', label: 'Tertiary', kind: 'color' },
+		],
+		schema: z.record(z.string(), colorSchema),
+	}),
+	slot({ key: 'storefront.header.mobile.ctas.hidden', scope: '_Storefront_', area: 'CTA', label: 'Burger menu hidden CTAs', hint: 'Buttons to drop from the mobile menu only.', kind: 'list', ops: ['set'], schema: z.array(z.string()) }),
+
+	slot({
+		key: 'campaign.banner.colors', scope: '_Global_', area: 'Flash offer', label: 'Banner colors',
+		hint: 'Recolour the flash offer banner.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'background', label: 'Background', kind: 'color' },
+			{ key: 'text', label: 'Text', kind: 'color' },
+			{ key: 'tagBackground', label: 'Tag background', kind: 'color' },
+			{ key: 'tagText', label: 'Tag text', kind: 'color' },
+			{ key: 'countdownText', label: 'Countdown text', kind: 'color' },
+		],
+		schema: z.record(z.string(), colorSchema),
+	}),
+	slot({ key: 'campaign.banner.text', scope: '_Global_', area: 'Flash offer', label: 'Banner text', hint: 'The wording of the flash offer banner.', kind: 'i18n', ops: ['set'], schema: i18nTextSchema }),
+	slot({ key: 'campaign.banner.tag', scope: '_Global_', area: 'Flash offer', label: 'Banner tag', hint: 'The small badge at the start of the banner.', kind: 'i18n', ops: ['set'], schema: i18nTextSchema }),
+	slot({ key: 'campaign.banner.showCountdown', scope: '_Global_', area: 'Flash offer', label: 'Show countdown', hint: 'Whether the banner counts down to the end of the offer.', kind: 'boolean', ops: ['set'], schema: z.boolean() }),
+	slot({ key: 'campaign.banner.placement', scope: '_Global_', area: 'Flash offer', label: 'Banner placement', hint: 'Where the banner sits on the page.', kind: 'enum', ops: ['set'], options: ['top', 'below-header', 'sticky-bottom'], schema: z.enum(['top', 'below-header', 'sticky-bottom']) }),
+	slot({ key: 'campaign.priceTag.text', scope: '_Global_', area: 'Flash offer', label: 'Discount badge text', hint: 'The wording of the discount badge shown next to prices.', kind: 'i18n', ops: ['set'], schema: i18nTextSchema }),
+	slot({ key: 'campaign.priceTag.placement', scope: '_Global_', area: 'Flash offer', label: 'Discount badge placement', hint: 'Where the discount badge sits relative to the price.', kind: 'enum', ops: ['set'], options: ['price-inline', 'card-corner', 'above-price', 'hidden'], schema: z.enum(['price-inline', 'card-corner', 'above-price', 'hidden']) }),
+	slot({
+		key: 'campaign.priceTag.colors', scope: '_Global_', area: 'Flash offer', label: 'Discount badge colors',
+		hint: 'Recolour the discount badge.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'background', label: 'Background', kind: 'color' },
+			{ key: 'text', label: 'Text', kind: 'color' },
+		],
+		schema: z.record(z.string(), colorSchema),
+	}),
+	slot({ key: 'campaign.ribbon.text', scope: '_Global_', area: 'Flash offer', label: 'Ribbon text', hint: 'The ribbon shown on the offer summary.', kind: 'i18n', ops: ['set'], schema: i18nTextSchema }),
+
+	slot({ key: 'popup.welcome.enabled', scope: '_Storefront_', area: 'Popup', label: 'Welcome popup enabled', hint: 'Whether the welcome popup appears at all.', kind: 'boolean', ops: ['set'], schema: z.boolean() }),
+	slot({ key: 'popup.welcome.delayMs', scope: '_Storefront_', area: 'Popup', label: 'Welcome popup delay', hint: 'How long to wait before showing it.', kind: 'duration', ops: ['set'], schema: z.number().int().min(0).max(600000) }),
+	slot({ key: 'popup.welcome.trigger', scope: '_Storefront_', area: 'Popup', label: 'Welcome popup trigger', hint: 'What makes it appear: a timer, scrolling, or the cursor leaving the page.', kind: 'enum', ops: ['set'], options: ['timer', 'scroll', 'exit-intent'], schema: z.enum(['timer', 'scroll', 'exit-intent']) }),
+	slot({
+		key: 'popup.welcome.frequency', scope: '_Storefront_', area: 'Popup', label: 'Welcome popup frequency',
+		hint: 'How often one visitor sees it again.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'mode', label: 'Mode', kind: 'enum', options: ['once', 'session', 'days'] },
+			{ key: 'days', label: 'Every N days', kind: 'number' },
+		],
+		schema: z.object({ mode: z.enum(['once', 'session', 'days']), days: z.number().int().min(1).max(365).optional() }),
+	}),
+	slot({
+		key: 'popup.welcome.content', scope: '_Storefront_', area: 'Popup', label: 'Welcome popup content',
+		hint: 'The wording and image of the welcome popup.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'title', label: 'Title', kind: 'i18n' },
+			{ key: 'subtitle', label: 'Subtitle', kind: 'i18n' },
+			{ key: 'ctaLabel', label: 'Button label', kind: 'i18n' },
+			{ key: 'confirmationTitle', label: 'Confirmation title', kind: 'i18n' },
+			{ key: 'confirmationText', label: 'Confirmation text', kind: 'i18n' },
+			{ key: 'image', label: 'Image', kind: 'image' },
+			{ key: 'imageMobile', label: 'Image (mobile)', kind: 'image' },
+		],
+		schema: z.record(z.string(), z.unknown()),
+	}),
+
+	slot({ key: 'checkout.steps.order', scope: '_Checkout_', area: 'Funnel', label: 'Step order', hint: 'Reorder the funnel. Must remain a permutation of the six steps, or it is ignored.', kind: 'list', ops: ['reorder', 'set'], options: ['_Profile_', '_Offers_', '_Information_', '_Options_', '_Delivery_', '_Payment_'], schema: z.array(CartStepSchema) }),
+	slot({ key: 'checkout.steps.hidden', scope: '_Checkout_', area: 'Funnel', label: 'Hidden steps', hint: 'Steps to skip entirely.', kind: 'list', ops: ['set'], options: ['_Profile_', '_Offers_', '_Information_', '_Options_', '_Delivery_', '_Payment_'], schema: z.array(CartStepSchema) }),
+	slot({ key: 'checkout.options.preselected', scope: '_Checkout_', area: 'Funnel', label: 'Preselected options', hint: 'Options ticked by default on the options step.', kind: 'list', ops: ['set'], schema: z.array(z.string()) }),
+	slot({ key: 'checkout.progress.visible', scope: '_Checkout_', area: 'Funnel', label: 'Progress bar visible', hint: 'Whether a progress indicator is shown.', kind: 'boolean', ops: ['set'], schema: z.boolean() }),
+	slot({ key: 'checkout.progress.style', scope: '_Checkout_', area: 'Funnel', label: 'Progress bar style', hint: 'The shape the progress indicator takes.', kind: 'enum', ops: ['set'], options: ['bar', 'steps', 'percentage'], schema: z.enum(['bar', 'steps', 'percentage']) }),
+	slot({ key: 'checkout.chat.enabled', scope: '_Checkout_', area: 'Contact', label: 'Chat enabled', hint: 'Whether the chat widget loads inside the checkout.', kind: 'boolean', ops: ['set'], schema: z.boolean() }),
+	slot({ key: 'checkout.chat.delayMs', scope: '_Checkout_', area: 'Contact', label: 'Chat load delay', hint: 'How long to wait before loading the chat.', kind: 'duration', ops: ['set'], schema: z.number().int().min(0).max(600000) }),
+	slot({ key: 'checkout.exitIntent.enabled', scope: '_Checkout_', area: 'Contact', label: 'Exit popup enabled', hint: 'Whether a popup appears when the cursor leaves the page.', kind: 'boolean', ops: ['set'], schema: z.boolean() }),
+	slot({
+		key: 'checkout.exitIntent.content', scope: '_Checkout_', area: 'Contact', label: 'Exit popup content',
+		hint: 'The wording of the exit popup.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'title', label: 'Title', kind: 'i18n' },
+			{ key: 'text', label: 'Text', kind: 'i18n' },
+			{ key: 'ctaLabel', label: 'Button label', kind: 'i18n' },
+		],
+		schema: z.record(z.string(), i18nTextSchema),
+	}),
+	slot({ key: 'checkout.texts', scope: '_Checkout_', area: 'Structure', label: 'Text overrides', hint: 'Replace any piece of checkout copy, written per language.', kind: 'record', entryKind: 'i18n', ops: ['merge', 'set'], schema: z.record(z.string(), i18nTextSchema) }),
+	slot({
+		key: 'checkout.media.visible', scope: '_Checkout_', area: 'Structure', label: 'Media visibility',
+		hint: 'Show or hide the product photos, per device. Hiding them on mobile buys back a lot of height.',
+		kind: 'object', ops: ['merge', 'set'],
+		fields: [
+			{ key: 'mobile', label: 'Mobile', kind: 'boolean' },
+			{ key: 'tablet', label: 'Tablet', kind: 'boolean' },
+			{ key: 'desktop', label: 'Desktop', kind: 'boolean' },
+		],
+		schema: z.object({ mobile: z.boolean().optional(), tablet: z.boolean().optional(), desktop: z.boolean().optional() }),
+	}),
+] as const;
+
+const MVT_SLOTS_BY_KEY: ReadonlyMap<string, MvtSlotDefinition> = new Map(MVT_SLOTS.map(s => [s.key, s]));
+
+export function mvtSlot(key: string): MvtSlotDefinition | null {
+	return MVT_SLOTS_BY_KEY.get(key) ?? null;
+}
+
+export function mvtSlotsForScope(scope: MvtScope): MvtSlotDefinition[] {
+	return MVT_SLOTS.filter(s => s.scope === scope || s.scope === '_Global_' || scope === '_Global_');
+}
+
+export interface MvtOverrideIssue {
+	index: number;
+	slot: string;
+	reason: string;
+}
+
+/**
+ * Validate a variant's overrides against the registry.
+ *
+ * Called by the API before a variant is stored, so that a slot typo or a colour written as a name
+ * instead of a hex value is a 422 for the operator who can still fix it, rather than a silently
+ * ignored override that makes a test look like it had no effect.
+ */
+export function mvtValidateOverrides(overrides: MvtOverride[]): MvtOverrideIssue[] {
+	const issues: MvtOverrideIssue[] = [];
+
+	overrides.forEach((override, index) => {
+		const definition = mvtSlot(override.slot);
+
+		if (!definition) {
+			issues.push({ index, slot: override.slot, reason: 'unknown_slot' });
+
+			return;
+		}
+
+		if (!definition.ops.includes(override.op)) {
+			issues.push({ index, slot: override.slot, reason: 'unsupported_op' });
+
+			return;
+		}
+
+		if (override.op === 'remove' || override.op === 'reorder') return;
+
+		if (override.op === 'merge' || override.op === 'patch' || override.op === 'insert') {
+			if (override.value === undefined) issues.push({ index, slot: override.slot, reason: 'missing_value' });
+
+			return;
+		}
+
+		if (!definition.schema.safeParse(override.value).success)
+			issues.push({ index, slot: override.slot, reason: 'invalid_value' });
+	});
+
+	return issues;
+}
+
+/**
+ * Apply one override to a base value.
+ *
+ * Every branch is total: an operation that cannot be carried out on the shape it was given returns
+ * the base untouched. A test that does nothing is a disappointment; a test that throws inside a
+ * component's render path is an outage, and the two are not worth trading against each other.
+ */
+export function mvtApplyOverride<T>(base: T, override: MvtOverride): T {
+	const value = override.value;
+
+	switch (override.op) {
+		case 'set':
+			return (value as T);
+
+		case 'merge':
+			if (base === null || typeof base !== 'object' || Array.isArray(base)) return base;
+			if (value === null || typeof value !== 'object') return base;
+
+			return { ...(base as object), ...(value as object) } as T;
+
+		case 'remove': {
+			if (!Array.isArray(base)) return base;
+			const key = override.match?.by;
+			const equals = override.match?.equals;
+
+			if (!key) return base;
+
+			return (base as unknown[]).filter(item => String((item as Record<string, unknown>)?.[key] ?? item) !== equals) as T;
+		}
+
+		case 'reorder': {
+			if (!Array.isArray(base) || !Array.isArray(value)) return base;
+			const key = override.match?.by;
+			const identity = (item: unknown) => key ? String((item as Record<string, unknown>)?.[key] ?? '') : String(item);
+			const wanted = (value as unknown[]).map(String);
+			const known = (base as unknown[]).filter(item => wanted.includes(identity(item)));
+			const rest = (base as unknown[]).filter(item => !wanted.includes(identity(item)));
+
+			known.sort((a, b) => wanted.indexOf(identity(a)) - wanted.indexOf(identity(b)));
+
+			return [...known, ...rest] as T;
+		}
+
+		case 'insert': {
+			if (!Array.isArray(base) || value === undefined) return base;
+			const next = [...(base as unknown[])];
+			const at = Math.min(override.at ?? next.length, next.length);
+
+			next.splice(at, 0, value);
+
+			return next as T;
+		}
+
+		case 'patch': {
+			if (!Array.isArray(base) || value === null || typeof value !== 'object') return base;
+			const key = override.match?.by;
+			const equals = override.match?.equals;
+
+			if (!key) return base;
+
+			return (base as unknown[]).map(item => {
+				const current = item as Record<string, unknown>;
+
+				if (String(current?.[key] ?? '') !== equals) return item;
+
+				return { ...current, ...(value as object) };
+			}) as T;
+		}
+
+		default:
+			return base;
+	}
+}