@lifeaz/lors-helper 1.0.27 → 1.1.1

package/src/main.ts

@@ -390,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(),
@@ -650,3 +658,1039 @@ 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_'
+	| '_Query_Param_Matches_'
+	| '_Screen_Width_Between_'
+	| '_Visits_At_Least_'
+	| '_Logged_In_'
+	| '_Logged_Out_'
+	| '_Is_Weekend_'
+	| '_Date_Between_';
+
+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_'),
+	z.literal('_Query_Param_Matches_'),
+	z.literal('_Screen_Width_Between_'),
+	z.literal('_Visits_At_Least_'),
+	z.literal('_Logged_In_'),
+	z.literal('_Logged_Out_'),
+	z.literal('_Is_Weekend_'),
+	z.literal('_Date_Between_'),
+]);
+
+/**
+ * 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_',
+	'_Logged_In_',
+	'_Logged_Out_',
+	'_Is_Weekend_',
+];
+
+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),
+	/**
+	 * Optional sub-targeting. A variant carrying one stops being a share of the split and becomes
+	 * a rule: every unit matching it lands here, whatever the weights say. See mvtPickVariant.
+	 */
+	audience: MvtAudienceNodeSchema.nullable().default(null),
+	/** Evaluation order of the targeted variants. The first match wins, so this is the tie-break. */
+	order: z.number().int().default(0),
+	/** Purely cosmetic, so one arm keeps the same colour across the split bar, the studio and the results. */
+	color: z.string().nullable().default(null),
+	description: z.string().nullable().default(null),
+});
+export type MvtVariant = z.infer<typeof MvtVariantSchema>;
+
+/**
+ * How one variant ends up receiving traffic, resolved from the variant set as a whole.
+ *
+ * `_Targeted_` variants are claimed by their own conditions and take no part in the weighted
+ * draw; `_Weighted_` ones share whatever is left. Computed in one place because the operator is
+ * shown this and the evaluator obeys it, and the two disagreeing would be the worst outcome.
+ */
+export type MvtAllocationMode = '_Targeted_' | '_Weighted_' | '_Unreachable_';
+
+export interface MvtAllocationRow {
+	key: string;
+	mode: MvtAllocationMode;
+	weight: number;
+	/** Share of the units that reach the weighted draw. Zero for a targeted variant, whose share depends on the audience rather than on a number. */
+	sharePct: number;
+}
+
+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;
+	/** Query string of the landing URL, lowercased keys. Reads as a targeting dimension of its own so an ad link can pin an arm without an UTM convention. */
+	query: Record<string, string>;
+	/** Viewport width in CSS pixels. Coarser than the device buckets, for the tests where the breakpoint itself is the subject. */
+	screenWidth: number;
+	/** Sessions this unit has opened, this one included. */
+	visits: number;
+	loggedIn: boolean;
+}
+
+/**
+ * Fill in the dimensions an older caller does not provide.
+ *
+ * The context grew, and a front built against the previous shape must not start failing every
+ * leaf that reads a new field. Defaults are chosen so an absent dimension excludes rather than
+ * includes: a condition on something the caller cannot observe should not match everybody.
+ */
+export function mvtNormalizeContext(context: Partial<MvtContext> & { unitId: string }): MvtContext {
+	return {
+		device: '_Desktop_',
+		lang: 'fr',
+		country: null,
+		profile: null,
+		partner: null,
+		seen: {},
+		utm: { source: null, medium: null, campaign: null },
+		referrer: null,
+		path: '/',
+		hasCart: false,
+		firstSeenAt: Date.now(),
+		now: Date.now(),
+		query: {},
+		screenWidth: 0,
+		visits: 1,
+		loggedIn: false,
+		...context,
+	};
+}
+
+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, context?: MvtContext): MvtVariant | null {
+	const targeted = experiment.variants
+		.filter(variant => !!variant.audience)
+		.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.key.localeCompare(b.key));
+
+	// Targeted arms are rules, not shares: the first whose own conditions hold claims the unit
+	// outright. Evaluated before the draw so that "everyone on mobile sees B" means exactly that
+	// rather than "mobile visitors have a better chance of seeing B", which is what a weight
+	// nudged by hand would have produced and what an operator would have had to verify by eye.
+	if (context)
+		for (const variant of targeted)
+			if (mvtEvaluateAudience(variant.audience ?? null, context)) return variant;
+
+	const pool = experiment.variants.filter(variant => !variant.audience).sort((a, b) => a.key.localeCompare(b.key));
+	const total = pool.reduce((sum, v) => sum + Math.max(v.weight, 0), 0);
+
+	// Every arm targeted and none of them matching leaves nobody to fall back on. The unit is
+	// left out of the experiment entirely rather than pushed onto an arm whose conditions it
+	// failed, which would silently make the targeting a lie.
+	if (!pool.length || total <= 0) return null;
+
+	const target = (mvtBucket(experiment.salt, unitId) / 10000) * total;
+	let cursor = 0;
+
+	for (const variant of pool) {
+		cursor += Math.max(variant.weight, 0);
+
+		if (target < cursor) return variant;
+	}
+
+	return pool[pool.length - 1];
+}
+
+/**
+ * How the split actually resolves, for the operator rather than the evaluator.
+ *
+ * Weights are relative and targeted arms are outside the draw entirely, so the number an operator
+ * typed and the share it buys are rarely the same. Computing that here, from the same rules the
+ * bucketing obeys, is what lets the interface show a split bar that cannot drift from the truth.
+ */
+export function mvtDistribution(variants: readonly MvtVariant[]): MvtAllocationRow[] {
+	const pool = variants.filter(variant => !variant.audience);
+	const total = pool.reduce((sum, v) => sum + Math.max(v.weight, 0), 0);
+
+	return variants.map(variant => {
+		if (variant.audience) return { key: variant.key, mode: '_Targeted_' as const, weight: variant.weight, sharePct: 0 };
+		if (total <= 0 || variant.weight <= 0) return { key: variant.key, mode: '_Unreachable_' as const, weight: variant.weight, sharePct: 0 };
+
+		return {
+			key: variant.key,
+			mode: '_Weighted_' as const,
+			weight: variant.weight,
+			sharePct: Math.round((Math.max(variant.weight, 0) / total) * 1000) / 10,
+		};
+	});
+}
+
+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());
+		case '_Logged_In_':            return context.loggedIn;
+		case '_Logged_Out_':           return !context.loggedIn;
+		case '_Is_Weekend_':           return [0, 6].includes(new Date(context.now).getDay());
+		case '_Visits_At_Least_':      return context.visits >= Number(values[0] ?? 1);
+
+		// Written "name=value", or "name" on its own to test for presence. The value side goes
+		// through the same wildcard matcher as the UTM leaves, so utm-like conventions carried in
+		// a bespoke parameter behave the way an operator already expects them to.
+		case '_Query_Param_Matches_': {
+			return values.some(raw => {
+				const separator = raw.indexOf('=');
+				const name = (separator < 0 ? raw : raw.slice(0, separator)).trim().toLowerCase();
+				const expected = separator < 0 ? null : raw.slice(separator + 1);
+				const actual = context.query[name];
+
+				if (actual === undefined) return false;
+				if (expected === null) return true;
+
+				return mvtMatchesPattern(actual, [expected]);
+			});
+		}
+
+		case '_Screen_Width_Between_': {
+			const from = Number(values[0] ?? 0);
+			const to = Number(values[1] ?? Number.MAX_SAFE_INTEGER);
+
+			return context.screenWidth >= from && context.screenWidth <= to;
+		}
+
+		// Bounds are wall-clock dates, and either may be left out for an open-ended window. This
+		// is not the experiment's own schedule: it is for the tests whose point is a date, such
+		// as a variant that only exists over a sale weekend.
+		case '_Date_Between_': {
+			const from = values[0] ? Date.parse(values[0]) : Number.NEGATIVE_INFINITY;
+			const to = values[1] ? Date.parse(values[1]) : Number.POSITIVE_INFINITY;
+
+			if (Number.isNaN(from) || Number.isNaN(to)) return false;
+
+			return context.now >= from && context.now <= to;
+		}
+
+		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, context);
+
+		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>;
+}
+
+/**
+ * A piece of copy, written in whichever languages the operator filled in.
+ *
+ * Partial on purpose, and it has to be said in the schema rather than left to convention: zod
+ * treats a record keyed by a closed set as exhaustive, so `z.record` here would refuse a French-
+ * only override at write time - which is the normal case, since a language left empty is
+ * documented everywhere as keeping the untouched original rather than blanking it.
+ */
+const i18nTextSchema = z.partialRecord(LangSchema, z.string());
+const colorSchema = z.string().regex(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+
+/**
+ * What a test may do to one anchored element.
+ *
+ * This is the whole vocabulary of the visual editor, and it is deliberately short. Hide it, move
+ * it, reword it, repoint it, restyle it within a closed set of properties. Nothing here can
+ * inject markup or a script, so an override authored by clicking around a page carries the same
+ * blast radius as one typed into the registry editor, which is what makes the studio safe to
+ * hand to somebody who is not going to read a diff.
+ *
+ * Every field is optional and absence means untouched, so the patches stay small and two editing
+ * sessions on the same element compose instead of overwriting one another.
+ */
+export const MvtAnchorPatchSchema = z.object({
+	hidden: z.boolean().optional(),
+	/** Position among its siblings. Lower comes first; anchors without one keep their place. */
+	order: z.number().int().min(-999).max(999).optional(),
+	text: i18nTextSchema.optional(),
+	href: z.string().max(2048).optional(),
+	route: z.string().max(512).optional(),
+	image: z.string().max(2048).optional(),
+	style: z.object({
+		background: colorSchema.optional(),
+		color: colorSchema.optional(),
+		borderColor: colorSchema.optional(),
+		borderRadius: z.number().int().min(0).max(96).optional(),
+		fontSize: z.number().int().min(8).max(96).optional(),
+		fontWeight: z.enum(['300', '400', '500', '600', '700', '800']).optional(),
+		align: z.enum(['left', 'center', 'right']).optional(),
+		paddingY: z.number().int().min(0).max(160).optional(),
+		paddingX: z.number().int().min(0).max(160).optional(),
+	}).optional(),
+});
+export type MvtAnchorPatch = z.infer<typeof MvtAnchorPatchSchema>;
+
+const anchorsSchema = z.record(z.string(), MvtAnchorPatchSchema);
+
+const ANCHOR_FIELDS: readonly MvtSlotField[] = [
+	{ key: 'hidden', label: 'Hidden', kind: 'boolean' },
+	{ key: 'order', label: 'Position', kind: 'number' },
+	{ key: 'text', label: 'Text', kind: 'i18n' },
+	{ key: 'href', label: 'External link', kind: 'text' },
+	{ key: 'route', label: 'Internal route', kind: 'text' },
+	{ key: 'image', label: 'Image', kind: 'image' },
+];
+
+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() }),
+	}),
+
+	slot({
+		key: 'storefront.anchors', scope: '_Storefront_', area: 'Studio', label: 'Anchored elements',
+		hint: 'Everything the visual editor writes: elements hidden, moved, reworded or restyled by clicking on the page itself.',
+		kind: 'record', entryKind: 'object', ops: ['merge', 'set'], fields: ANCHOR_FIELDS, itemKey: 'anchor',
+		schema: anchorsSchema,
+	}),
+	slot({
+		key: 'checkout.anchors', scope: '_Checkout_', area: 'Studio', label: 'Anchored elements',
+		hint: 'Everything the visual editor writes: elements hidden, moved, reworded or restyled by clicking on the page itself.',
+		kind: 'record', entryKind: 'object', ops: ['merge', 'set'], fields: ANCHOR_FIELDS, itemKey: 'anchor',
+		schema: anchorsSchema,
+	}),
+] 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;
+			}
+
+			// A merge onto a record is still a record of the same entries, so the full schema
+			// applies and catches a malformed anchor patch here rather than in a customer's
+			// browser. A merge onto a fixed-shape object is a partial by definition, and running
+			// the whole schema over it would refuse every legitimate single-field edit.
+			if (definition.kind === 'record' && !definition.schema.safeParse(override.value).success)
+				issues.push({ index, slot: override.slot, reason: 'invalid_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;
+	}
+}
+
+// -----------------------------------------------------------------------------
+// Anchors
+// -----------------------------------------------------------------------------
+
+export const MVT_ANCHOR_ATTRIBUTE = 'data-mvt-anchor';
+
+/**
+ * The anchors slot for one scope.
+ *
+ * Kept as a lookup rather than a naming convention the call sites repeat, because the studio, the
+ * API validator and the two fronts all have to agree on it, and a typo in any of the four would
+ * produce an override that validates and does nothing.
+ */
+export function mvtAnchorsSlot(scope: MvtScope): string {
+	return scope === '_Checkout_' ? 'checkout.anchors' : 'storefront.anchors';
+}
+
+/**
+ * Fold a stack of anchor patches into one.
+ *
+ * Later patches win field by field rather than wholesale: two overrides touching the same element,
+ * one hiding it and one rewording it, both have to survive, or the operator has to remember which
+ * of their own edits cancelled which.
+ */
+export function mvtMergeAnchorPatch(base: MvtAnchorPatch | undefined, next: MvtAnchorPatch | undefined): MvtAnchorPatch {
+	if (!base) return next ?? {};
+	if (!next) return base;
+
+	return {
+		...base,
+		...next,
+		text: next.text || base.text ? { ...(base.text ?? {}), ...(next.text ?? {}) } : undefined,
+		style: next.style || base.style ? { ...(base.style ?? {}), ...(next.style ?? {}) } : undefined,
+	};
+}
+
+/**
+ * The inline style an anchor patch asks for, as a plain property bag.
+ *
+ * Only the closed set the patch schema allows can come out of here, which is the point: a front
+ * applying this is not evaluating anything an operator wrote, it is reading a handful of numbers
+ * and colours that have already been validated twice.
+ */
+export function mvtAnchorStyle(patch: MvtAnchorPatch | null | undefined): Record<string, string> {
+	const style = patch?.style;
+
+	if (!style) return {};
+
+	const out: Record<string, string> = {};
+
+	if (style.background) out['background-color'] = style.background;
+	if (style.color) out['color'] = style.color;
+	if (style.borderColor) out['border-color'] = style.borderColor;
+	if (style.borderRadius !== undefined) out['border-radius'] = `${style.borderRadius}px`;
+	if (style.fontSize !== undefined) out['font-size'] = `${style.fontSize}px`;
+	if (style.fontWeight) out['font-weight'] = style.fontWeight;
+	if (style.align) out['text-align'] = style.align;
+	if (style.paddingY !== undefined) out['padding-block'] = `${style.paddingY}px`;
+	if (style.paddingX !== undefined) out['padding-inline'] = `${style.paddingX}px`;
+
+	return out;
+}
+
+// -----------------------------------------------------------------------------
+// Studio bridge
+// -----------------------------------------------------------------------------
+
+/**
+ * The message vocabulary between the Tools studio and the front rendered inside its frame.
+ *
+ * A separate protocol rather than a preview link with more query parameters, because the studio
+ * has to do two things a link cannot: read back what is actually on the page - the anchors, their
+ * labels, their nesting - and apply an edit without a reload, so that changing a colour is a
+ * colour changing rather than a page blinking.
+ *
+ * Every message carries the protocol version. A front and a Tools release drift apart eventually,
+ * and a version mismatch has to degrade to a plain preview rather than to an editor whose clicks
+ * quietly do nothing.
+ */
+export const MVT_STUDIO_PROTOCOL = 1;
+
+export type MvtStudioAnchorRole = 'section' | 'cta' | 'text' | 'image' | 'block';
+
+export interface MvtStudioAnchor {
+	/** Stable identifier written into the markup by the front, never derived from the DOM position. */
+	id: string;
+	label: string;
+	role: MvtStudioAnchorRole;
+	/** The anchor this one sits inside, for the studio's tree. Null at the top level. */
+	parentId: string | null;
+	order: number;
+	/** What the untouched page shows today, so the editor opens on the real copy rather than an empty field. */
+	text: string | null;
+	movable: boolean;
+	hideable: boolean;
+	rect: { top: number; left: number; width: number; height: number };
+}
+
+/** Tools to front. */
+export type MvtStudioRequest =
+	| { protocol: number; type: 'studio:hello' }
+	| { protocol: number; type: 'studio:scan' }
+	| { protocol: number; type: 'studio:select'; anchorId: string | null }
+	| { protocol: number; type: 'studio:apply'; anchors: Record<string, MvtAnchorPatch>; lang: string }
+	| { protocol: number; type: 'studio:mode'; picking: boolean }
+	| { protocol: number; type: 'studio:navigate'; path: string };
+
+/** Front to Tools. */
+export type MvtStudioEvent =
+	| { protocol: number; type: 'studio:ready'; scope: MvtScope; path: string; langs: string[] }
+	| { protocol: number; type: 'studio:anchors'; anchors: MvtStudioAnchor[]; path: string }
+	| { protocol: number; type: 'studio:picked'; anchor: MvtStudioAnchor }
+	| { protocol: number; type: 'studio:navigated'; path: string };
+
+export function mvtIsStudioEvent(data: unknown): data is MvtStudioEvent {
+	if (!data || typeof data !== 'object') return false;
+
+	const message = data as Partial<MvtStudioEvent>;
+
+	return message.protocol === MVT_STUDIO_PROTOCOL && typeof message.type === 'string' && message.type.startsWith('studio:');
+}
+
+export function mvtIsStudioRequest(data: unknown): data is MvtStudioRequest {
+	return mvtIsStudioEvent(data);
+}