@riverbankcms/sdk 0.111.0 → 0.119.0

package/dist/client/hooks.mjs

@@ -3254,151 +3254,6 @@ z$1.discriminatedUnion("kind", [
 	})
 ]);
 //#endregion
-//#region ../theme-core/src/surfaces/foregroundContract.ts
-const SURFACE_FOREGROUND_CSS_VARS = {
-	text: "--rb-surface-text-color",
-	heading: "--rb-surface-heading-color",
-	link: "--rb-surface-link-color",
-	supporting: "--rb-surface-supporting-color"
-};
-const DEFAULT_SURFACE_TEXT_COLOR = "rgb(var(--tb-text, 17 24 39))";
-const DEFAULT_ROLE_FALLBACKS = {
-	text: DEFAULT_SURFACE_TEXT_COLOR,
-	heading: DEFAULT_SURFACE_TEXT_COLOR,
-	link: "rgb(var(--tb-primary, var(--tb-text, 17 24 39)))",
-	supporting: "rgb(var(--tb-mutedText, 100 116 139))"
-};
-function requireSurfaceColorValue(role, value) {
-	const normalized = value.trim();
-	if (normalized.length === 0) throw new RangeError(`Surface foreground ${role} must be a non-empty CSS color.`);
-	return normalized;
-}
-function completeSurfaceForegrounds(input) {
-	const text = requireSurfaceColorValue("text", input.text);
-	return {
-		text,
-		heading: input.heading === void 0 ? text : requireSurfaceColorValue("heading", input.heading),
-		link: input.link === void 0 ? text : requireSurfaceColorValue("link", input.link),
-		supporting: input.supporting === void 0 ? text : requireSurfaceColorValue("supporting", input.supporting)
-	};
-}
-function surfaceForegroundValue(role, outsideProviderFallback = DEFAULT_ROLE_FALLBACKS[role]) {
-	const roleVariable = SURFACE_FOREGROUND_CSS_VARS[role];
-	const fallback = requireSurfaceColorValue("fallback", outsideProviderFallback);
-	if (role === "text") return `var(${roleVariable}, ${fallback})`;
-	return `var(${roleVariable}, var(${SURFACE_FOREGROUND_CSS_VARS.text}, ${fallback}))`;
-}
-function surfaceForegroundValueWithOpacity(role, opacityPercent) {
-	if (!Number.isFinite(opacityPercent) || opacityPercent < 0 || opacityPercent > 100) throw new RangeError("Surface foreground opacity must be between 0 and 100.");
-	return `color-mix(in srgb, ${surfaceForegroundValue(role)} ${opacityPercent}%, transparent)`;
-}
-function surfaceForegroundStyle(input) {
-	const foregrounds = completeSurfaceForegrounds(input);
-	return {
-		color: foregrounds.text,
-		[SURFACE_FOREGROUND_CSS_VARS.text]: foregrounds.text,
-		[SURFACE_FOREGROUND_CSS_VARS.heading]: foregrounds.heading,
-		[SURFACE_FOREGROUND_CSS_VARS.link]: foregrounds.link,
-		[SURFACE_FOREGROUND_CSS_VARS.supporting]: foregrounds.supporting
-	};
-}
-//#endregion
-//#region ../theme-core/src/utils/colorStyles.ts
-const COLOR_VAR_PREFIX = "--tb-";
-function parseToken(source) {
-	const parts = parseColorTokenParts(source);
-	if (parts.kind === "raw") return {
-		token: source,
-		raw: parts.value
-	};
-	if (parts.kind === "invalid") return { token: source };
-	return {
-		token: parts.token,
-		opacityPercent: parts.opacityPercent === null ? void 0 : parts.opacityPercent
-	};
-}
-const SURFACE_TEXT_ROLE_BY_TOKEN = {
-	text: "text",
-	heading: "heading",
-	mutedText: "supporting"
-};
-function surfaceRoleForTextToken(token) {
-	return Object.prototype.hasOwnProperty.call(SURFACE_TEXT_ROLE_BY_TOKEN, token) ? SURFACE_TEXT_ROLE_BY_TOKEN[token] : null;
-}
-/**
-* Converts a theme color token to a CSS rgb value.
-* This is the primary function for applying theme colors to CSS properties.
-*
-* @param token - Theme color token (semantic, with opacity, or raw)
-* @returns CSS color value (rgb with optional alpha, or raw CSS value)
-*
-* @example
-* rgbColorValue('primary') // => 'rgb(var(--tb-primary))'
-* rgbColorValue('surface/95') // => 'rgb(var(--tb-surface) / 0.95)'
-* rgbColorValue('raw:transparent') // => 'transparent'
-*/
-function rgbColorValue(token) {
-	const { token: baseToken, opacityPercent, raw } = parseToken(token);
-	if (raw) return raw;
-	const cssVar = `${COLOR_VAR_PREFIX}${baseToken}`;
-	if (opacityPercent === void 0) return `rgb(var(${cssVar}))`;
-	return `rgb(var(${cssVar}) / ${opacityPercent / 100})`;
-}
-/**
-* Creates a backgroundColor style object from a theme token.
-*
-* @param token - Theme color token
-* @returns CSSProperties with backgroundColor
-*/
-function backgroundColorStyle(token) {
-	return { backgroundColor: rgbColorValue(token) };
-}
-/**
-* Creates a text color style object from a theme token.
-*
-* @param token - Theme color token
-* @returns CSSProperties with color
-*/
-function textColorStyle(token) {
-	const parsed = parseToken(token);
-	const surfaceRole = parsed.raw ? null : surfaceRoleForTextToken(parsed.token);
-	if (surfaceRole) return { color: parsed.opacityPercent === void 0 ? surfaceForegroundValue(surfaceRole) : surfaceForegroundValueWithOpacity(surfaceRole, parsed.opacityPercent) };
-	return { color: rgbColorValue(token) };
-}
-/**
-* Creates a border color style object from a theme token.
-*
-* @param token - Theme color token
-* @returns CSSProperties with borderColor
-*/
-function borderColorStyle(token) {
-	return { borderColor: rgbColorValue(token) };
-}
-/**
-* Merges multiple CSSProperties objects into a single object.
-* Later styles override earlier ones. Undefined values are filtered out.
-* Returns undefined if the merged result is empty.
-*
-* @param styles - Variable number of CSSProperties objects (can be undefined)
-* @returns Merged CSSProperties object, or undefined if empty
-*
-* @example
-* mergeStyles(
-*   backgroundColorStyle('surface'),
-*   textColorStyle('text'),
-*   borderColorStyle('border')
-* )
-* // => { backgroundColor: '...', color: '...', borderColor: '...' }
-*/
-function mergeStyles(...styles) {
-	const merged = {};
-	for (const style of styles) {
-		if (!style) continue;
-		Object.assign(merged, style);
-	}
-	return Object.keys(merged).length ? merged : void 0;
-}
-//#endregion
 //#region ../theme-core/src/lib/media.ts
 const hotspotSchema$1 = z.object({
 	x: z.number().min(0).max(1),
@@ -3456,111 +3311,6 @@ const mediaSchema$1 = z.object({
 	transform: transformSchema$1.optional()
 });
 //#endregion
-//#region ../theme-core/src/buttons/effectClassification.ts
-/**
-* Exhaustive live policy for every registered effect id.
-*
-* The resolver consumes the transition payload directly, so adding an effect
-* cannot update classification without also defining its runtime behavior.
-*/
-const BUTTON_EFFECT_POLICIES = {
-	"darken-background": {
-		classification: "colour-transition",
-		transition: {
-			kind: "adjust-shade",
-			direction: "darker"
-		}
-	},
-	"lighten-background": {
-		classification: "colour-transition",
-		transition: {
-			kind: "adjust-shade",
-			direction: "lighter"
-		}
-	},
-	"background-on-hover": {
-		classification: "colour-transition",
-		transition: { kind: "replace-background" }
-	},
-	"background-on-hover-alpha": {
-		classification: "unsupported-colour",
-		reason: "alpha_requires_surface"
-	},
-	"fade-background": {
-		classification: "unsupported-colour",
-		reason: "changes_element_opacity"
-	},
-	"opacity-reduce": {
-		classification: "unsupported-colour",
-		reason: "changes_element_opacity"
-	},
-	"gradient-text": {
-		classification: "unsupported-colour",
-		reason: "changes_foreground"
-	},
-	"text-color-change": {
-		classification: "unsupported-colour",
-		reason: "changes_foreground"
-	},
-	"border-color-change": {
-		classification: "unsupported-colour",
-		reason: "changes_border"
-	},
-	"aurora-glow": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"cosmic-stardust": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"gradient-border-fill": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"animated-gradient-border-fill": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"nav-underline": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-base": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-hover": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-active": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"animated-gradient": { classification: "non-colour" },
-	"border-glow": { classification: "non-colour" },
-	"drop-shadow": { classification: "non-colour" },
-	"inner-shadow": { classification: "non-colour" },
-	"neumorphic-shadow": { classification: "non-colour" },
-	"outer-glow": { classification: "non-colour" },
-	"retro-3d-shadow": { classification: "non-colour" },
-	"scale-up": { classification: "non-colour" },
-	"scale-down": { classification: "non-colour" },
-	lift: { classification: "non-colour" },
-	"press-down": { classification: "non-colour" },
-	pop: { classification: "non-colour" },
-	"border-bottom-grow": { classification: "non-colour" },
-	"sketchy-border": { classification: "non-colour" },
-	"pulse-animation": { classification: "non-colour" }
-};
-function getButtonEffectPolicy(effectId) {
-	return Object.prototype.hasOwnProperty.call(BUTTON_EFFECT_POLICIES, effectId) ? BUTTON_EFFECT_POLICIES[effectId] : null;
-}
-function classifyButtonEffectId(effectId) {
-	return getButtonEffectPolicy(effectId)?.classification ?? "unknown";
-}
-//#endregion
 //#region ../theme-core/src/buttons/types.ts
 /**
 * Standard semantic variant roles a theme exposes.
@@ -3577,6 +3327,13 @@ const VARIANT_ROLES = [
 	"tertiary",
 	"accent"
 ];
+/**
+* Canonical persisted/CSS-safe button variant identifier.
+*
+* IDs become class selectors, so keep the contract deliberately narrower than
+* an arbitrary string and shared with every authoring/runtime boundary.
+*/
+const buttonVariantIdSchema = z$1.string().min(1).max(50).regex(/^[a-z0-9-]+$/, "Button variant IDs may contain lowercase letters, numbers, and hyphens only");
 function parseOpaqueButtonColourToken(value) {
 	const token = parseThemeColorToken(value);
 	if (token === null) return null;
@@ -3591,6 +3348,109 @@ const opaqueButtonColourTokenSchema = themeColorTokenSchema.refine((value) => pa
 	if (token === null) throw new Error("Invariant: opaque button token passed its schema");
 	return token;
 });
+const buttonShadeAmountSchema = z$1.number().finite().min(0).max(900).multipleOf(100);
+const buttonShadowIntensitySchema = z$1.enum([
+	"subtle",
+	"medium",
+	"strong"
+]);
+/**
+* The complete persisted button-effect contract.
+*
+* Navigation has its own generic interactive-effect model. Button variants use
+* this closed union so unsupported effect IDs, unknown option keys, and unsafe
+* CSS values cannot become representable after the schema boundary.
+*/
+const buttonEffectApplicationSchema = z$1.discriminatedUnion("effectId", [
+	z$1.strictObject({
+		effectId: z$1.literal("darken-background"),
+		options: z$1.strictObject({ amount: buttonShadeAmountSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("lighten-background"),
+		options: z$1.strictObject({ amount: buttonShadeAmountSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("background-on-hover"),
+		options: z$1.strictObject({ colorToken: opaqueButtonColourTokenSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("animated-gradient"),
+		options: z$1.strictObject({ direction: z$1.enum(["horizontal", "vertical"]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("drop-shadow"),
+		options: z$1.strictObject({ intensity: buttonShadowIntensitySchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("inner-shadow"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("neumorphic-shadow"),
+		options: z$1.strictObject({
+			mode: z$1.enum(["raised", "pressed"]).optional(),
+			intensity: buttonShadowIntensitySchema.optional()
+		}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("retro-3d-shadow"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("scale-up"),
+		options: z$1.strictObject({ scale: z$1.enum([
+			"1.02",
+			"1.03",
+			"1.05",
+			"1.10"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("scale-down"),
+		options: z$1.strictObject({ scale: z$1.enum([
+			"0.90",
+			"0.95",
+			"0.97",
+			"0.98"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("lift"),
+		options: z$1.strictObject({ amount: z$1.enum([
+			"0.25",
+			"0.5",
+			"1"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("press-down"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("pop"),
+		options: z$1.strictObject({ intensity: z$1.enum([
+			"subtle",
+			"medium",
+			"dramatic"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("border-bottom-grow"),
+		options: z$1.strictObject({
+			height: z$1.union([z$1.literal(1), z$1.literal(2)]).optional(),
+			origin: z$1.enum([
+				"left",
+				"center",
+				"right"
+			]).optional()
+		}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("sketchy-border"),
+		options: z$1.strictObject({ intensity: buttonShadowIntensitySchema.optional() }).optional()
+	})
+]);
 const cornerStyleSchema = z$1.enum([
 	"square",
 	"rounded",
@@ -3625,13 +3485,7 @@ const hoverTransformSchema = z$1.enum([
 	"scale",
 	"press"
 ]);
-const hoverColorSchema = z$1.enum([
-	"none",
-	"brighten",
-	"darken",
-	"saturate",
-	"token"
-]);
+z$1.enum(["none", "token"]);
 const buttonPaddingPresetSchema = z$1.enum([
 	"compact",
 	"default",
@@ -3692,7 +3546,7 @@ const buttonSizesSchema = z$1.object({
 	lg,
 	xl: xl ?? lg
 }));
-const canonicalButtonGlobalSettingsSchema = z$1.object({
+const buttonGlobalSettingsBaseSchema = z$1.strictObject({
 	cornerStyle: cornerStyleSchema,
 	cornerRadius: z$1.number().min(0).max(24).optional(),
 	/**
@@ -3705,30 +3559,23 @@ const canonicalButtonGlobalSettingsSchema = z$1.object({
 	shadow: shadowSizeSchema.optional(),
 	textTransform: textTransformSchema,
 	fontWeight: fontWeightSchema,
-	/**
-	* @deprecated Set per-variant via `variant.border.widthClass` instead.
-	* Schema field is preserved so existing presets parse; the value is unread
-	* by the current generator and will be removed once the legacy
-	* `primitives/content/components/Button.tsx` slot exports are deleted.
-	*/
-	borderWidth: z$1.union([
-		z$1.literal(1),
-		z$1.literal(2),
-		z$1.literal(3)
-	]),
 	typography: buttonTypographySchema.optional(),
 	fontSize: z$1.string().optional(),
 	letterSpacing: letterSpacingSchema.optional(),
 	italic: z$1.boolean().optional(),
 	paddingPreset: buttonPaddingPresetSchema.optional(),
 	hoverTransform: hoverTransformSchema,
-	hoverColor: hoverColorSchema,
-	hoverColorToken: opaqueButtonColourTokenSchema.optional(),
 	gradientStyle: gradientStyleSchema.optional(),
 	gradientAngle: z$1.number().min(0).max(360).optional(),
 	gradientSharpness: gradientSharpnessSchema.optional()
 });
-const buttonGlobalSettingsSchema = z$1.preprocess(normalizeLegacyButtonGlobalInput, canonicalButtonGlobalSettingsSchema);
+const buttonGlobalSettingsSchema = z$1.discriminatedUnion("hoverColor", [buttonGlobalSettingsBaseSchema.extend({
+	hoverColor: z$1.literal("none"),
+	hoverColorToken: z$1.never().optional()
+}), buttonGlobalSettingsBaseSchema.extend({
+	hoverColor: z$1.literal("token"),
+	hoverColorToken: opaqueButtonColourTokenSchema
+})]);
 const gradientDirectionSchema$1 = z$1.enum([
 	"to-r",
 	"to-l",
@@ -3740,11 +3587,11 @@ const gradientDirectionSchema$1 = z$1.enum([
 	"to-bl"
 ]);
 const buttonColourTreatmentSchema = z$1.discriminatedUnion("type", [
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("solid"),
 		colorToken: opaqueButtonColourTokenSchema
 	}),
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("gradient"),
 		stops: z$1.array(opaqueButtonColourTokenSchema).min(2).transform((stops) => {
 			const [first, second, ...rest] = stops;
@@ -3758,19 +3605,15 @@ const buttonColourTreatmentSchema = z$1.discriminatedUnion("type", [
 		direction: gradientDirectionSchema$1,
 		foregroundToken: opaqueButtonColourTokenSchema
 	}),
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("surface"),
 		role: z$1.literal("link")
 	})
 ]);
 const buttonBackgroundSchema = buttonColourTreatmentSchema;
-const effectApplicationSchema$1 = z$1.object({
-	effectId: z$1.string(),
-	options: z$1.record(z$1.string(), z$1.json()).optional()
-});
-const buttonBorderSchema = z$1.object({ widthClass: z$1.string() });
-const buttonVariantAffordanceSchema = z$1.object({ iconId: z$1.string().min(1) });
-const variantShadowSchema = z$1.object({
+const buttonBorderSchema = z$1.strictObject({ widthClass: z$1.string() });
+const buttonVariantAffordanceSchema = z$1.strictObject({ iconId: z$1.string().min(1) });
+const variantShadowSchema = z$1.strictObject({
 	elevation: z$1.enum([
 		"none",
 		"low",
@@ -3783,13 +3626,13 @@ const variantShadowSchema = z$1.object({
 		"hard"
 	]).nullable(),
 	position: z$1.enum(["bottom", "bottom-right"]).default("bottom"),
-	colorToken: themeColorTokenSchema.optional()
+	colorToken: opaqueButtonColourTokenSchema.optional()
 });
-const variantEffectsSchema = z$1.object({
-	base: z$1.array(effectApplicationSchema$1).optional(),
-	hover: z$1.array(effectApplicationSchema$1).optional(),
-	active: z$1.array(effectApplicationSchema$1).optional(),
-	focus: z$1.array(effectApplicationSchema$1).optional()
+const variantEffectsSchema = z$1.strictObject({
+	base: z$1.array(buttonEffectApplicationSchema).optional(),
+	hover: z$1.array(buttonEffectApplicationSchema).optional(),
+	active: z$1.array(buttonEffectApplicationSchema).optional(),
+	focus: z$1.array(buttonEffectApplicationSchema).optional()
 });
 /**
 * Per-variant size overrides schema — every entry is optional.
@@ -3810,8 +3653,8 @@ const variantSizeOverridesSchema = z$1.object({
 * default (e.g. link-style variants declaring zero horizontal padding at
 * every size).
 */
-const canonicalButtonVariantSchema = z$1.object({
-	id: z$1.string(),
+const buttonVariantSchema = z$1.strictObject({
+	id: buttonVariantIdSchema,
 	name: z$1.string().min(1).max(20),
 	enabled: z$1.boolean(),
 	priority: prioritySchema,
@@ -3825,154 +3668,73 @@ const canonicalButtonVariantSchema = z$1.object({
 	sizes: variantSizeOverridesSchema.optional(),
 	affordance: buttonVariantAffordanceSchema.optional()
 });
-/**
-* Temporary persisted-theme admission boundary for issue #1206.
-*
-* Production inventory on 2026-07-22 found 22 rows using the old independent
-* `textColorToken`/border colour shape. New source and all downstream code use
-* only the canonical relationship. Delete this preprocessor after the reviewed
-* production rewrite reports zero legacy rows.
-*/
-const buttonVariantSchema = z$1.preprocess(normalizeLegacyButtonVariantInput, canonicalButtonVariantSchema);
-const buttonSystemSchema = z$1.object({
+const buttonSystemSchema = z$1.strictObject({
 	global: buttonGlobalSettingsSchema,
 	variants: z$1.array(buttonVariantSchema).min(1).max(6),
 	sizes: buttonSizesSchema.optional()
+}).superRefine((system, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	system.variants.forEach((variant, index) => {
+		if (seen.has(variant.id)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"variants",
+				index,
+				"id"
+			],
+			message: `Duplicate button variant ID: ${variant.id}`
+		});
+		seen.add(variant.id);
+	});
 });
-function normalizeLegacyButtonVariantInput(input) {
-	if (!isUnknownRecord(input)) return input;
-	const background = input.background;
-	if (!isUnknownRecord(background)) return input;
-	if (!(background.type === "transparent" || Object.prototype.hasOwnProperty.call(input, "textColorToken") || isUnknownRecord(input.border) && Object.prototype.hasOwnProperty.call(input.border, "colorToken") || hasLegacyButtonEffects(input.effects) || hasLegacyAlphaToken(input, background))) return input;
-	const { textColorToken, ...withoutLegacyText } = input;
-	const normalizedBorder = isUnknownRecord(input.border) && typeof input.border.widthClass === "string" ? { widthClass: input.border.widthClass } : input.border;
-	const normalizedAffordance = isUnknownRecord(input.affordance) && typeof input.affordance.iconId === "string" ? { iconId: input.affordance.iconId } : input.affordance;
-	const normalizedEffects = normalizeLegacyButtonEffects(input.effects, background.type);
-	const hoverBackgroundToken = stripLegacyTokenAlpha(input.hoverBackgroundToken);
-	if (background.type === "transparent") return {
-		...withoutLegacyText,
-		background: {
-			type: "surface",
-			role: "link"
-		},
-		border: normalizedBorder,
-		affordance: normalizedAffordance,
-		effects: normalizedEffects,
-		hoverBackgroundToken
-	};
-	if (background.type === "gradient") {
-		const stops = Array.isArray(background.stops) ? background.stops.map(stripLegacyTokenAlpha) : background.stops;
-		return {
-			...withoutLegacyText,
-			background: {
-				...background,
-				stops,
-				foregroundToken: stripLegacyTokenAlpha(background.foregroundToken ?? textColorToken)
-			},
-			border: normalizedBorder,
-			affordance: normalizedAffordance,
-			effects: normalizedEffects,
-			hoverBackgroundToken
-		};
-	}
-	return {
-		...withoutLegacyText,
-		background: background.type === "solid" ? {
-			...background,
-			colorToken: stripLegacyTokenAlpha(background.colorToken)
-		} : background,
-		border: normalizedBorder,
-		affordance: normalizedAffordance,
-		effects: normalizedEffects,
-		hoverBackgroundToken
-	};
+//#endregion
+//#region ../theme-core/src/surfaces/foregroundContract.ts
+const SURFACE_FOREGROUND_CSS_VARS = {
+	text: "--rb-surface-text-color",
+	heading: "--rb-surface-heading-color",
+	link: "--rb-surface-link-color",
+	supporting: "--rb-surface-supporting-color"
+};
+const DEFAULT_SURFACE_TEXT_COLOR = "rgb(var(--tb-text, 17 24 39))";
+const DEFAULT_ROLE_FALLBACKS = {
+	text: DEFAULT_SURFACE_TEXT_COLOR,
+	heading: DEFAULT_SURFACE_TEXT_COLOR,
+	link: "rgb(var(--tb-primary, var(--tb-text, 17 24 39)))",
+	supporting: "rgb(var(--tb-mutedText, 100 116 139))"
+};
+function requireSurfaceColorValue(role, value) {
+	const normalized = value.trim();
+	if (normalized.length === 0) throw new RangeError(`Surface foreground ${role} must be a non-empty CSS color.`);
+	return normalized;
 }
-function normalizeLegacyButtonGlobalInput(input) {
-	if (!isUnknownRecord(input)) return input;
-	const hoverColorToken = stripLegacyTokenAlpha(input.hoverColorToken);
-	return hoverColorToken === input.hoverColorToken ? input : {
-		...input,
-		hoverColorToken
+function completeSurfaceForegrounds(input) {
+	const text = requireSurfaceColorValue("text", input.text);
+	return {
+		text,
+		heading: input.heading === void 0 ? text : requireSurfaceColorValue("heading", input.heading),
+		link: input.link === void 0 ? text : requireSurfaceColorValue("link", input.link),
+		supporting: input.supporting === void 0 ? text : requireSurfaceColorValue("supporting", input.supporting)
 	};
 }
-function hasLegacyAlphaToken(input, background) {
-	const stops = isUnknownArray(background.stops) ? background.stops : [];
-	return [
-		input.hoverBackgroundToken,
-		background.colorToken,
-		background.foregroundToken,
-		...stops
-	].some((token) => stripLegacyTokenAlpha(token) !== token);
-}
-function stripLegacyTokenAlpha(value) {
-	if (typeof value !== "string") return value;
-	const slashIndex = value.indexOf("/");
-	return slashIndex < 0 ? value : value.slice(0, slashIndex);
-}
-function hasLegacyButtonEffects(input) {
-	if (!isUnknownRecord(input)) return false;
-	return [
-		"base",
-		"hover",
-		"active",
-		"focus"
-	].some((state) => {
-		const effects = input[state];
-		return Array.isArray(effects) && effects.some((effect) => {
-			if (!isUnknownRecord(effect) || typeof effect.effectId !== "string") return true;
-			const classification = classifyButtonEffectId(effect.effectId);
-			if (classification !== "colour-transition" && classification !== "non-colour") return true;
-			return effect.effectId === "background-on-hover" && isUnknownRecord(effect.options) && stripLegacyTokenAlpha(effect.options.colorToken) !== effect.options.colorToken;
-		});
-	});
-}
-function normalizeLegacyButtonEffects(input, backgroundType) {
-	if (!isUnknownRecord(input)) return input;
-	const normalized = {};
-	for (const state of [
-		"base",
-		"hover",
-		"active",
-		"focus"
-	]) {
-		const effects = input[state];
-		if (!Array.isArray(effects)) continue;
-		const safeEffects = effects.flatMap((effect) => {
-			if (!isUnknownRecord(effect) || typeof effect.effectId !== "string") return [];
-			const classification = classifyButtonEffectId(effect.effectId);
-			if (classification === "non-colour") return [effect];
-			if (classification !== "colour-transition") return [];
-			if (effect.effectId === "background-on-hover") {
-				const options = isUnknownRecord(effect.options) ? effect.options : null;
-				const colorToken = options === null ? null : parseOpaqueButtonColourToken(stripLegacyTokenAlpha(options.colorToken));
-				return colorToken === null ? [] : [{
-					...effect,
-					options: {
-						...options,
-						colorToken
-					}
-				}];
-			}
-			if (backgroundType !== "solid") return [];
-			const rawAmount = isUnknownRecord(effect.options) ? effect.options.amount : void 0;
-			const amount = typeof rawAmount === "number" && rawAmount > 0 ? Math.max(100, Math.round(rawAmount / 100) * 100) : 100;
-			return [{
-				...effect,
-				options: {
-					...isUnknownRecord(effect.options) ? effect.options : {},
-					amount
-				}
-			}];
-		});
-		if (safeEffects.length > 0) normalized[state] = safeEffects;
-	}
-	return Object.keys(normalized).length === 0 ? void 0 : normalized;
+function surfaceForegroundValue(role, outsideProviderFallback = DEFAULT_ROLE_FALLBACKS[role]) {
+	const roleVariable = SURFACE_FOREGROUND_CSS_VARS[role];
+	const fallback = requireSurfaceColorValue("fallback", outsideProviderFallback);
+	if (role === "text") return `var(${roleVariable}, ${fallback})`;
+	return `var(${roleVariable}, var(${SURFACE_FOREGROUND_CSS_VARS.text}, ${fallback}))`;
 }
-function isUnknownRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+function surfaceForegroundValueWithOpacity(role, opacityPercent) {
+	if (!Number.isFinite(opacityPercent) || opacityPercent < 0 || opacityPercent > 100) throw new RangeError("Surface foreground opacity must be between 0 and 100.");
+	return `color-mix(in srgb, ${surfaceForegroundValue(role)} ${opacityPercent}%, transparent)`;
 }
-function isUnknownArray(value) {
-	return Array.isArray(value);
+function surfaceForegroundStyle(input) {
+	const foregrounds = completeSurfaceForegrounds(input);
+	return {
+		color: foregrounds.text,
+		[SURFACE_FOREGROUND_CSS_VARS.text]: foregrounds.text,
+		[SURFACE_FOREGROUND_CSS_VARS.heading]: foregrounds.heading,
+		[SURFACE_FOREGROUND_CSS_VARS.link]: foregrounds.link,
+		[SURFACE_FOREGROUND_CSS_VARS.supporting]: foregrounds.supporting
+	};
 }
 buttonSizeNameSchema.options;
 //#endregion
@@ -4129,7 +3891,6 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 500,
-			borderWidth: 1,
 			typography: "body",
 			fontSize: "text-sm",
 			letterSpacing: "loose",
@@ -4193,7 +3954,7 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 					affordance: { iconId: "ArrowRight" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -4304,7 +4065,6 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 2,
 			hoverTransform: "lift",
 			hoverColor: "none"
 		},
@@ -4323,10 +4083,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 						position: "bottom"
 					},
 					effects: {
-						hover: [{
-							effectId: "lift",
-							options: { translateY: "-1px" }
-						}],
+						hover: [{ effectId: "lift" }],
 						active: [{
 							effectId: "scale-down",
 							options: { scale: "0.98" }
@@ -4345,7 +4102,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4360,7 +4117,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4374,7 +4131,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-full",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4404,7 +4161,6 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "lift",
 			hoverColor: "none",
 			typography: "body",
@@ -4440,12 +4196,9 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 						position: "bottom"
 					},
 					effects: {
-						hover: [{
-							effectId: "lift",
-							options: { translateY: "-1px" }
-						}, {
+						hover: [{ effectId: "lift" }, {
 							effectId: "background-on-hover",
-							options: { colorToken: "accent" }
+							options: { colorToken: unsafeAsOpaqueButtonColourToken("accent") }
 						}],
 						active: [{
 							effectId: "scale-down",
@@ -4465,7 +4218,7 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "muted" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("muted") }
 					}] }
 				}
 			},
@@ -4480,7 +4233,7 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -4540,7 +4293,6 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 			shadow: "medium",
 			textTransform: "none",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -4581,7 +4333,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "background" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("background") }
 					}] }
 				}
 			},
@@ -4596,7 +4348,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4610,7 +4362,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-md",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4645,7 +4397,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "square",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -4663,7 +4414,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 2,
-							colorToken: "text",
 							origin: "left"
 						}
 					}] }
@@ -4682,7 +4432,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "mutedText",
 							origin: "left"
 						}
 					}] }
@@ -4701,7 +4450,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -4725,7 +4473,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 					effectId: "border-bottom-grow",
 					options: {
 						height: 2,
-						colorToken: "accent",
 						origin: "left"
 					}
 				}] } }
@@ -4747,7 +4494,6 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "pill",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 2,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -4792,7 +4538,7 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "accent" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("accent") }
 					}] }
 				}
 			},
@@ -4807,7 +4553,7 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4862,7 +4608,6 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -4927,7 +4672,7 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4941,7 +4686,7 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-lg",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -4970,7 +4715,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none",
 			letterSpacing: "loose"
@@ -5028,7 +4772,7 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -5043,7 +4787,7 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -5077,7 +4821,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -5108,7 +4851,6 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "none",
 			fontWeight: 600,
-			borderWidth: 1,
 			typography: "body",
 			letterSpacing: "tight",
 			paddingPreset: "default",
@@ -5140,12 +4882,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "secondary" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
 					}] }
 				}
 			},
@@ -5158,12 +4897,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					border: { widthClass: "border" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -5176,12 +4912,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					border: { widthClass: "border" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -5193,10 +4926,7 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 						role: "link"
 					},
 					borderRadius: "rounded-lg",
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}] }
+					effects: { hover: [{ effectId: "lift" }] }
 				}
 			},
 			accent: {
@@ -5208,10 +4938,7 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}] }
+					effects: { hover: [{ effectId: "lift" }] }
 				}
 			}
 		}
@@ -5232,9 +4959,8 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "uppercase",
 			fontWeight: 700,
-			borderWidth: 2,
 			hoverTransform: "lift",
-			hoverColor: "darken",
+			hoverColor: "none",
 			typography: "body",
 			paddingPreset: "spacious",
 			italic: false
@@ -5292,7 +5018,7 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "background" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("background") }
 					}] }
 				}
 			},
@@ -5306,7 +5032,7 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-full",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -5341,7 +5067,6 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 			typography: "heading",
 			fontWeight: 700,
 			fontSize: "text-lg",
-			borderWidth: 2,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -5376,7 +5101,7 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 						elevation: "high",
 						softness: "hard",
 						position: "bottom-right",
-						colorToken: "text"
+						colorToken: unsafeAsOpaqueButtonColourToken("text")
 					},
 					effects: { hover: [{ effectId: "press-down" }] }
 				}
@@ -5394,7 +5119,7 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 						elevation: "high",
 						softness: "hard",
 						position: "bottom-right",
-						colorToken: "secondary"
+						colorToken: unsafeAsOpaqueButtonColourToken("secondary")
 					},
 					effects: { hover: [{ effectId: "press-down" }] }
 				}
@@ -5439,7 +5164,6 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none",
 			letterSpacing: "loose"
@@ -5475,7 +5199,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					effects: {
 						hover: [{
 							effectId: "background-on-hover",
-							options: { colorToken: "primary-100" }
+							options: { colorToken: unsafeAsOpaqueButtonColourToken("primary-100") }
 						}],
 						active: [{
 							effectId: "scale-down",
@@ -5495,7 +5219,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -5510,7 +5234,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "muted" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("muted") }
 					}] }
 				}
 			},
@@ -5544,7 +5268,6 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -6653,6 +6376,102 @@ new Set(themeV2NormalEditorRawStyleFieldNames);
 const pageDesignEditorBackgroundOverrideOwner = "page-design-editor";
 const siteChromeBackgroundOverrideOwner = "site-chrome-editor";
 //#endregion
+//#region ../theme-core/src/utils/colorStyles.ts
+const COLOR_VAR_PREFIX = "--tb-";
+function parseToken(source) {
+	const parts = parseColorTokenParts(source);
+	if (parts.kind === "raw") return {
+		token: source,
+		raw: parts.value
+	};
+	if (parts.kind === "invalid") return { token: source };
+	return {
+		token: parts.token,
+		opacityPercent: parts.opacityPercent === null ? void 0 : parts.opacityPercent
+	};
+}
+const SURFACE_TEXT_ROLE_BY_TOKEN = {
+	text: "text",
+	heading: "heading",
+	mutedText: "supporting"
+};
+function surfaceRoleForTextToken(token) {
+	return Object.prototype.hasOwnProperty.call(SURFACE_TEXT_ROLE_BY_TOKEN, token) ? SURFACE_TEXT_ROLE_BY_TOKEN[token] : null;
+}
+/**
+* Converts a theme color token to a CSS rgb value.
+* This is the primary function for applying theme colors to CSS properties.
+*
+* @param token - Theme color token (semantic, with opacity, or raw)
+* @returns CSS color value (rgb with optional alpha, or raw CSS value)
+*
+* @example
+* rgbColorValue('primary') // => 'rgb(var(--tb-primary))'
+* rgbColorValue('surface/95') // => 'rgb(var(--tb-surface) / 0.95)'
+* rgbColorValue('raw:transparent') // => 'transparent'
+*/
+function rgbColorValue(token) {
+	const { token: baseToken, opacityPercent, raw } = parseToken(token);
+	if (raw) return raw;
+	const cssVar = `${COLOR_VAR_PREFIX}${baseToken}`;
+	if (opacityPercent === void 0) return `rgb(var(${cssVar}))`;
+	return `rgb(var(${cssVar}) / ${opacityPercent / 100})`;
+}
+/**
+* Creates a backgroundColor style object from a theme token.
+*
+* @param token - Theme color token
+* @returns CSSProperties with backgroundColor
+*/
+function backgroundColorStyle(token) {
+	return { backgroundColor: rgbColorValue(token) };
+}
+/**
+* Creates a text color style object from a theme token.
+*
+* @param token - Theme color token
+* @returns CSSProperties with color
+*/
+function textColorStyle(token) {
+	const parsed = parseToken(token);
+	const surfaceRole = parsed.raw ? null : surfaceRoleForTextToken(parsed.token);
+	if (surfaceRole) return { color: parsed.opacityPercent === void 0 ? surfaceForegroundValue(surfaceRole) : surfaceForegroundValueWithOpacity(surfaceRole, parsed.opacityPercent) };
+	return { color: rgbColorValue(token) };
+}
+/**
+* Creates a border color style object from a theme token.
+*
+* @param token - Theme color token
+* @returns CSSProperties with borderColor
+*/
+function borderColorStyle(token) {
+	return { borderColor: rgbColorValue(token) };
+}
+/**
+* Merges multiple CSSProperties objects into a single object.
+* Later styles override earlier ones. Undefined values are filtered out.
+* Returns undefined if the merged result is empty.
+*
+* @param styles - Variable number of CSSProperties objects (can be undefined)
+* @returns Merged CSSProperties object, or undefined if empty
+*
+* @example
+* mergeStyles(
+*   backgroundColorStyle('surface'),
+*   textColorStyle('text'),
+*   borderColorStyle('border')
+* )
+* // => { backgroundColor: '...', color: '...', borderColor: '...' }
+*/
+function mergeStyles(...styles) {
+	const merged = {};
+	for (const style of styles) {
+		if (!style) continue;
+		Object.assign(merged, style);
+	}
+	return Object.keys(merged).length ? merged : void 0;
+}
+//#endregion
 //#region ../theme-core/src/utils/tokenOrColor.ts
 /**
 * Runtime color-reference fields intentionally accept any string, including
@@ -13533,6 +13352,7 @@ const DISPLAY_MEDIA_KINDS = [
 	"video",
 	"audio"
 ];
+const DEFAULT_MEDIA_FIELD_KINDS = ["image"];
 const PUBLIC_FILE_FIELD_KINDS = [
 	"document",
 	"spreadsheet",
@@ -13733,18 +13553,28 @@ const inlineTextFieldSchema = baseFieldSchema.extend({
 	maxLength: z$1.number().int().positive().optional(),
 	plainTextField: z$1.string().min(1).optional()
 });
+function hasMediaDefaultIdentifier(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.identifier === "string" && value.identifier.trim().length > 0;
+}
+function validateMediaFieldDefault(field, ctx) {
+	if (field.defaultValue !== void 0 && field.defaultValue !== null && !hasMediaDefaultIdentifier(field.defaultValue)) ctx.addIssue({
+		code: z$1.ZodIssueCode.custom,
+		path: ["defaultValue"],
+		message: `${field.type} defaultValue must be null or an object with a non-empty identifier`
+	});
+}
 const mediaFieldSchema = baseFieldSchema.extend({
 	type: z$1.literal("media"),
-	mediaKinds: z$1.array(z$1.enum(MEDIA_KINDS)).default(["image"]).transform((kinds) => {
+	mediaKinds: z$1.array(z$1.enum(MEDIA_KINDS)).default([...DEFAULT_MEDIA_FIELD_KINDS]).transform((kinds) => {
 		const displayKinds = kinds.filter(isDisplayMediaKind);
-		return displayKinds.length > 0 ? displayKinds : ["image"];
+		return displayKinds.length > 0 ? displayKinds : [...DEFAULT_MEDIA_FIELD_KINDS];
 	}),
 	aspectRatio: z$1.string().optional()
-});
+}).superRefine(validateMediaFieldDefault);
 const fileFieldSchema = baseFieldSchema.extend({
 	type: z$1.literal("file"),
 	fileKinds: z$1.array(z$1.enum(PUBLIC_FILE_FIELD_KINDS)).default([...PUBLIC_FILE_FIELD_KINDS])
-});
+}).superRefine(validateMediaFieldDefault);
 const booleanFieldSchema = baseFieldSchema.extend({ type: z$1.literal("boolean") });
 const dateFieldSchema = baseFieldSchema.extend({ type: z$1.literal("date") });
 const timeFieldSchema = baseFieldSchema.extend({ type: z$1.literal("time") });
@@ -22044,20 +21874,10 @@ function visitRichTextNode(node, allowedTokens, tokenValues) {
 }
 function interpolateRichTextTokens(value, options, context) {
 	if (!isRecord$8(value)) return value;
-	const allowedTokens = new Set(options.tokens);
-	const tokenValues = {
+	return visitRichTextNode(value, new Set(options.tokens), {
 		year: String((/* @__PURE__ */ new Date()).getFullYear()),
 		site_name: getSiteName(context)
-	};
-	if (isRecord$8(value.doc)) {
-		const nextDoc = visitRichTextNode(value.doc, allowedTokens, tokenValues);
-		if (nextDoc === value.doc) return value;
-		return {
-			...value,
-			doc: nextDoc
-		};
-	}
-	return visitRichTextNode(value, allowedTokens, tokenValues);
+	});
 }
 const contentTransforms = [{
 	id: "content.interpolateRichTextTokens",
@@ -24440,11 +24260,8 @@ const mediaSchema = z.discriminatedUnion("type", [
 * This module provides a single source of truth for TipTap rich text validation
 * across both the block-form editor and the block rendering system.
 *
-* Format compatibility:
-* - Unwrapped format (new): { type: 'doc', content: [...] }
-* - Wrapped format (legacy): { doc: { type: 'doc', content: [...] } }
-*
-* Both formats are supported for backward compatibility during migration.
+* Rich-text fields use one canonical root shape:
+* `{ type: 'doc', content: [...] }`.
 */
 /**
 * TipTap document node schema (recursive structure)
@@ -24457,17 +24274,40 @@ const mediaSchema = z.discriminatedUnion("type", [
 * - marks: Text formatting marks (e.g., bold, italic)
 */
 const TipTapMarkSchema = z$1.object({
-	type: z$1.string(),
+	type: z$1.string().min(1),
 	attrs: z$1.record(z$1.string(), z$1.unknown()).optional()
-});
+}).strict();
 const TipTapNodeSchema = z$1.lazy(() => z$1.object({
-	type: z$1.string(),
+	type: z$1.string().min(1),
 	content: z$1.array(TipTapNodeSchema).optional(),
 	text: z$1.string().optional(),
 	attrs: z$1.record(z$1.string(), z$1.unknown()).optional(),
 	marks: z$1.array(TipTapMarkSchema).optional()
+}).strict().superRefine((node, ctx) => {
+	if (node.type === "doc") ctx.addIssue({
+		code: "custom",
+		path: ["type"],
+		message: "Document nodes are only valid at the rich-text root"
+	});
+	if (node.type === "text") {
+		if (node.text === void 0 || node.text.length === 0) ctx.addIssue({
+			code: "custom",
+			path: ["text"],
+			message: "Text nodes require a non-empty text value"
+		});
+		if (node.content !== void 0) ctx.addIssue({
+			code: "custom",
+			path: ["content"],
+			message: "Text nodes cannot contain child nodes"
+		});
+		return;
+	}
+	if (node.text !== void 0) ctx.addIssue({
+		code: "custom",
+		path: ["text"],
+		message: "Only text nodes can contain a text value"
+	});
 }));
-z$1.union([TipTapNodeSchema, z$1.object({ doc: TipTapNodeSchema })]);
 /**
 * Canonical schema for a TipTap rich-text document root.
 *
@@ -24476,13 +24316,11 @@ z$1.union([TipTapNodeSchema, z$1.object({ doc: TipTapNodeSchema })]);
 * (dummy content, editor output, migrations) must emit, and the shape every
 * non-legacy consumer can rely on.
 *
-* Legacy envelopes are read-tolerated by {@link RichTextValueSchema} but
-* normalised before reaching anywhere typed as `RichTextDoc`.
 */
 const RichTextDocSchema = z$1.object({
 	type: z$1.literal("doc"),
 	content: z$1.array(TipTapNodeSchema)
-});
+}).strict();
 //#endregion
 //#region ../blocks/src/system/blocks/shared/bookingPaymentTerms.ts
 const bookingDepositRefundPolicySchema = z$1.enum(["refundable", "non_refundable"]);
@@ -35832,6 +35670,7 @@ const CANONICAL_REFUND_PLANNER_ERROR_CODES = [
 		"idempotency_amount_mismatch",
 		"idempotency_method_mismatch",
 		"idempotency_receipt_mismatch",
+		"idempotency_scope_mismatch",
 		"refund_in_progress"
 	],
 	"invalid_amount",
@@ -36218,7 +36057,7 @@ const SITE_BANNER_TONE_VALUES = [
 ];
 const siteBannerScopeSchema = z$1.enum(SITE_BANNER_SCOPE_VALUES);
 const siteBannerToneSchema = z$1.enum(SITE_BANNER_TONE_VALUES);
-const siteBannerBodySchema = z$1.unknown().transform(unwrapRichTextValue);
+const siteBannerBodySchema = RichTextDocSchema;
 const siteBannerCtaSchema = z$1.object({
 	label: z$1.string().trim().min(1),
 	link: linkPayloadSchema
@@ -36246,7 +36085,8 @@ const EMPTY_SITE_BANNER_BODY = {
 	}]
 };
 function analyzeSiteBannerBody(body) {
-	const sanitizedBody = sanitizeSiteBannerBodyInternal(body, { limitParagraphs: false });
+	const parsed = RichTextDocSchema.safeParse(body);
+	const sanitizedBody = parsed.success ? sanitizeSiteBannerBodyInternal(parsed.data, { limitParagraphs: false }) : EMPTY_SITE_BANNER_BODY;
 	const paragraphs = collectParagraphs(sanitizedBody);
 	const textLength = paragraphs.reduce((total, paragraph) => total + paragraphTextLength(paragraph), 0);
 	const issues = [];
@@ -36268,7 +36108,7 @@ function siteBannerBodyIssueMessage(issue) {
 	}
 }
 function sanitizeSiteBannerBodyInternal(input, options) {
-	const content = normalizeTopLevelNodes(unwrapRichTextValue(input).content ?? [], options);
+	const content = normalizeTopLevelNodes(input.content, options);
 	return {
 		type: "doc",
 		content: content.length > 0 ? content : EMPTY_SITE_BANNER_BODY.content
@@ -36349,28 +36189,6 @@ function sanitizeMarks(marks) {
 	});
 	return sanitized.length > 0 ? sanitized : void 0;
 }
-function unwrapRichTextValue(value) {
-	if (isRecord$1(value) && isRecord$1(value.doc)) return unwrapRichTextValue(value.doc);
-	if (isRecord$1(value) && value.type === "doc") return {
-		type: "doc",
-		content: Array.isArray(value.content) ? value.content.filter(isTipTapNodeLike).map(coerceTipTapNode) : []
-	};
-	return EMPTY_SITE_BANNER_BODY;
-}
-function isTipTapNodeLike(value) {
-	return isRecord$1(value) && typeof value.type === "string";
-}
-function coerceTipTapNode(value) {
-	return {
-		type: value.type,
-		...Array.isArray(value.content) ? { content: value.content.filter(isTipTapNodeLike).map(coerceTipTapNode) } : {},
-		...typeof value.text === "string" ? { text: value.text } : {},
-		...Array.isArray(value.marks) ? { marks: value.marks.filter((mark) => isRecord$1(mark) && typeof mark.type === "string").map((mark) => ({
-			type: mark.type,
-			...isRecord$1(mark.attrs) ? { attrs: mark.attrs } : {}
-		})) } : {}
-	};
-}
 function paragraphTextLength(paragraph) {
 	return collectText(paragraph).length;
 }