@riverbankcms/sdk 0.149.0 → 0.150.0

package/dist/server/theme-bridge.mjs

@@ -808,6 +808,7 @@ const buttonSystemSchema = z.strictObject({
 });
 //#endregion
 //#region ../theme-core/src/palette/utils/colorConversion.ts
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
 function hexToRgb(hex) {
 	const h = hex.replace(/^#/, "");
 	const m = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
@@ -819,12 +820,38 @@ function hexToRgb(hex) {
 		b: int & 255
 	};
 }
+function rgbToHex(r, g, b) {
+	const to = (n) => Math.round(n).toString(16).padStart(2, "0");
+	return `#${to(r)}${to(g)}${to(b)}`;
+}
 function srgbToLinear(u) {
 	const x = u / 255;
 	return x <= .04045 ? x / 12.92 : Math.pow((x + .055) / 1.055, 2.4);
 }
-//#endregion
-//#region ../theme-core/src/palette/utils/contrast.ts
+function linearToSrgb(x) {
+	return clamp01(x <= .0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - .055) * 255;
+}
+function oklabToSrgb(L, a, b) {
+	const l_ = Math.pow(L + .3963377774 * a + .2158037573 * b, 3);
+	const m_ = Math.pow(L - .1055613458 * a - .0638541728 * b, 3);
+	const s_ = Math.pow(L - .0894841775 * a - 1.291485548 * b, 3);
+	const R = 4.0767416621 * l_ - 3.3077115913 * m_ + .2309699292 * s_;
+	const G = -1.2684380046 * l_ + 2.6097574011 * m_ - .3413193965 * s_;
+	const B = -.0041960863 * l_ - .7034186147 * m_ + 1.707614701 * s_;
+	return {
+		r: linearToSrgb(R),
+		g: linearToSrgb(G),
+		b: linearToSrgb(B)
+	};
+}
+function oklchToOklab(L, C, h) {
+	const hr = h * Math.PI / 180;
+	return {
+		L,
+		a: C * Math.cos(hr),
+		b: C * Math.sin(hr)
+	};
+}
 function relativeLuminance(r, g, b) {
 	const R = srgbToLinear(r), G = srgbToLinear(g), B = srgbToLinear(b);
 	return .2126 * R + .7152 * G + .0722 * B;
@@ -961,6 +988,17 @@ function surfaceForegroundStyle(input) {
 function surfaceForegroundDeclarations(input) {
 	return Object.entries(surfaceForegroundStyle(input)).map(([property, value]) => `${property}: ${value};`);
 }
+function surfaceForegroundInputFromResolved(foreground, color) {
+	const { roles } = foreground;
+	return {
+		text: color(roles.text),
+		heading: color(roles.heading),
+		link: color(roles.link),
+		linkHover: color(roles.linkHover),
+		supporting: color(roles.supporting),
+		hoverDecoration: foreground.hoverDecoration
+	};
+}
 function hoverDecoration(input) {
 	return input.hoverDecoration ?? "underline";
 }
@@ -985,6 +1023,16 @@ const GRADIENT_DIRECTION_MAP$1 = {
 	"to-tr": "to top right",
 	"to-tl": "to top left"
 };
+/**
+* Map Tailwind border-width tokens to CSS values
+*/
+const BORDER_WIDTH_MAP$3 = {
+	"border-0": "0px",
+	"border": "1px",
+	"border-2": "2px",
+	"border-4": "4px",
+	"border-8": "8px"
+};
 //#endregion
 //#region ../theme-core/src/buttons/effectClassification.ts
 /**
@@ -1659,6 +1707,278 @@ function interpolateHex(startHex, endHex, position) {
 	return `#${channel(start.r, end.r)}${channel(start.g, end.g)}${channel(start.b, end.b)}`;
 }
 //#endregion
+//#region ../theme-core/src/palette/utils/opaqueSurfaceColor.ts
+/** Resolve an opaque colour, compositing alpha against an explicit underlay. */
+function resolveOpaqueSurfaceHex(reference, palette, underlayReference) {
+	const opaque = resolveConcreteColorHex(reference, palette);
+	if (opaque) return opaque;
+	if (!underlayReference) return null;
+	const underlayHex = resolveConcreteColorHex(underlayReference, palette);
+	if (!underlayHex) return null;
+	const parts = parseColorTokenParts(reference);
+	if (parts.kind === "token" && parts.opacityPercent !== null) {
+		const foregroundHex = normalizePaletteHex(palette[parts.token] ?? "");
+		return foregroundHex ? compositeHex(foregroundHex, underlayHex, parts.opacityPercent / 100) : null;
+	}
+	const rgba = parseRgba(parts.kind === "raw" ? parts.value : reference);
+	return rgba ? compositeHex(rgbToHex(rgba.r, rgba.g, rgba.b), underlayHex, rgba.alpha) : null;
+}
+/** Resolve a colour reference only when it is already fully opaque. */
+function resolveConcreteColorHex(reference, palette) {
+	const literalHex = normalizePaletteHex(reference);
+	if (literalHex) return literalHex;
+	const parts = parseColorTokenParts(reference);
+	if (parts.kind === "token") {
+		if (parts.opacityPercent !== null) return null;
+		return normalizePaletteHex(palette[parts.token] ?? "");
+	}
+	const literal = parts.kind === "raw" ? parts.value : reference;
+	if (literal.toLowerCase() === "black") return "#000000";
+	if (literal.toLowerCase() === "white") return "#ffffff";
+	return normalizePaletteHex(literal);
+}
+function compositeHex(foregroundHex, underlayHex, alpha) {
+	const foreground = hexToRgb(foregroundHex);
+	const underlay = hexToRgb(underlayHex);
+	const channel = (foregroundValue, underlayValue) => Math.round(foregroundValue * alpha + underlayValue * (1 - alpha));
+	return rgbToHex(channel(foreground.r, underlay.r), channel(foreground.g, underlay.g), channel(foreground.b, underlay.b));
+}
+function parseRgba(value) {
+	const match = value.trim().match(/^rgba?\(\s*([\d.]+)(?:\s*,\s*|\s+)([\d.]+)(?:\s*,\s*|\s+)([\d.]+)(?:\s*(?:,|\/)\s*([\d.]+%?))?\s*\)$/i);
+	if (!match) return null;
+	const [, rSource, gSource, bSource] = match;
+	if (!rSource || !gSource || !bSource) return null;
+	const r = Number(rSource);
+	const g = Number(gSource);
+	const b = Number(bSource);
+	const alpha = parseAlpha(match[4]);
+	if (alpha === null || !isRgbChannel(r) || !isRgbChannel(g) || !isRgbChannel(b)) return null;
+	return {
+		r,
+		g,
+		b,
+		alpha
+	};
+}
+function parseAlpha(source) {
+	if (!source) return 1;
+	const value = source.endsWith("%") ? Number(source.slice(0, -1)) / 100 : Number(source);
+	return Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+function isRgbChannel(value) {
+	return Number.isFinite(value) && value >= 0 && value <= 255;
+}
+/**
+* Derive the hover foreground that belongs with a resolved resting foreground.
+*
+* A resting foreground is chosen to be legible against a known surface. A hover
+* state derived from it stays within a bounded distance of that colour, so it
+* inherits most of the resting colour's contrast margin instead of asserting
+* an unrelated brand colour that no one checked against the surface.
+*
+* That bounded-distance property is what lets this be used on a transparent
+* overlay header, where the backdrop is only partly knowable: the scrolled
+* state composites a 60% glass tint over arbitrary page content, so no
+* compile-time contrast proof is available there. Staying near a colour that
+* is already trusted in both states is a weaker claim than a contrast proof,
+* and it is one this function can actually keep.
+*
+* Returns `null` when the resting token is not a plain palette token — an
+* already-faded or raw value has no well-defined softening, and the caller
+* should leave hover alone rather than guess.
+*/
+function deriveForegroundHoverToken(restingToken) {
+	const parts = parseColorTokenParts(restingToken);
+	if (parts.kind !== "token") return null;
+	if (parts.opacityPercent !== null) return null;
+	return parseThemeColorToken(`${parts.token}/85`);
+}
+/**
+* Prefer an authored hover that survives every measured backdrop, then a
+* checked softening of the resting colour. A null backdrop set represents a
+* trusted treatment: only an explicit authored hover may change the colour.
+* When neither option works, retain the resting colour and underline it.
+*/
+function planForegroundHover(input) {
+	const { restingToken, candidate, palette, backdrops } = input;
+	if (candidate && candidate !== restingToken) {
+		if (backdrops === null || survivesEveryBackdrop(candidate, palette, backdrops)) return {
+			kind: "candidate",
+			token: candidate,
+			decoration: "initial"
+		};
+	}
+	const softened = deriveForegroundHoverToken(restingToken);
+	if (softened && backdrops && survivesEveryBackdrop(softened, palette, backdrops)) return {
+		kind: "softened",
+		token: softened,
+		decoration: "initial"
+	};
+	return {
+		kind: "resting",
+		token: restingToken,
+		decoration: "underline"
+	};
+}
+function survivesEveryBackdrop(token, palette, backdrops) {
+	return backdrops.length > 0 && backdrops.every((backdrop) => {
+		const foreground = resolveOpaqueSurfaceHex(token, palette, backdrop);
+		return foreground !== null && contrastRatio(foreground, backdrop) >= 4.5;
+	});
+}
+//#endregion
+//#region ../theme-core/src/surfaces/resolveSurfaceForeground.ts
+const FALLBACK_TEXT_TOKENS = [
+	"text",
+	"primaryForeground",
+	"secondaryForeground",
+	"accentForeground",
+	"neutral-950",
+	"neutral-50"
+];
+const CANONICAL_EQUIVALENT_TOKEN_ORDER = [
+	"text",
+	"primaryForeground",
+	"secondaryForeground",
+	"accentForeground",
+	"onPrimary",
+	"onSecondary",
+	"onAccent",
+	"onSurface",
+	"neutral-950",
+	"neutral-50"
+];
+/**
+* Resolve the complete foreground contract for an effective page/section or
+* site-chrome background.
+*
+* Deterministic colour backgrounds are validated at ordinary-text WCAG AA.
+* Existing image/video/gradient treatments are trusted only when they already
+* carry a usable foreground token; this function deliberately does not claim
+* pixel-level contrast proof for media.
+*/
+function resolveSurfaceForeground(background, palette, candidates = {}, options = {}) {
+	const authored = foregroundCandidates(background, candidates);
+	if (background === null) return resolveDeterministicForeground("background", {
+		...authored,
+		text: authored.text ?? "text"
+	}, palette);
+	if (background.type === "color") {
+		const backgroundReference = normalizedReference(background.color);
+		if (!backgroundReference || backgroundReference === "transparent") return { kind: "unknown" };
+		return resolveDeterministicForeground(backgroundReference, authored, palette, options.compositeBase);
+	}
+	return resolveTrustedTreatmentForeground(authored, palette);
+}
+function foregroundCandidates(background, overrides) {
+	return {
+		text: candidateOrBackground(overrides.text, background?.textColor),
+		heading: candidateOrBackground(overrides.heading, background?.headingColor),
+		link: candidateOrBackground(overrides.link, background?.linkColor),
+		linkHover: candidateOrBackground(overrides.linkHover),
+		supporting: candidateOrBackground(overrides.supporting, background?.supportingColor)
+	};
+}
+function candidateOrBackground(candidate, backgroundValue) {
+	return candidate ?? backgroundValue ?? null;
+}
+function resolveDeterministicForeground(backgroundReference, candidates, palette, compositeBase) {
+	const backgroundHex = resolveOpaqueSurfaceHex(backgroundReference, palette, compositeBase);
+	if (!backgroundHex) return resolveTrustedTreatmentForeground(candidates, palette);
+	const backgroundToken = paletteToken(backgroundReference);
+	const derivedOnToken = backgroundToken ? onColorTokenName(backgroundToken) : null;
+	const text = firstSafeToken([
+		candidates.text,
+		derivedOnToken,
+		...FALLBACK_TEXT_TOKENS
+	], backgroundHex, palette, derivedOnToken ? [derivedOnToken] : []);
+	if (!text) return { kind: "unknown" };
+	return knownForeground({
+		text,
+		heading: safeTokenOr(candidates.heading, text, backgroundHex, palette),
+		link: safeTokenOr(candidates.link, text, backgroundHex, palette),
+		supporting: safeTokenOr(candidates.supporting, text, backgroundHex, palette)
+	}, {
+		kind: "measured",
+		backdropHex: backgroundHex
+	}, candidates.linkHover, palette);
+}
+function resolveTrustedTreatmentForeground(candidates, palette) {
+	const text = canonicalToken(candidates.text, palette);
+	if (!text) return { kind: "unknown" };
+	return knownForeground({
+		text,
+		heading: canonicalToken(candidates.heading, palette) ?? text,
+		link: canonicalToken(candidates.link, palette) ?? text,
+		supporting: canonicalToken(candidates.supporting, palette) ?? text
+	}, { kind: "trusted-treatment" }, candidates.linkHover, palette);
+}
+function knownForeground(roles, provenance, hoverCandidate, palette) {
+	const hover = planForegroundHover({
+		restingToken: roles.link,
+		candidate: canonicalHoverToken(hoverCandidate, palette),
+		palette,
+		backdrops: provenance.kind === "measured" ? [provenance.backdropHex] : null
+	});
+	return {
+		kind: "known",
+		provenance,
+		roles: {
+			...roles,
+			linkHover: hover.token
+		},
+		hoverDecoration: hover.decoration
+	};
+}
+function canonicalHoverToken(reference, palette) {
+	const token = parseThemeColorToken(reference);
+	if (token) {
+		const parts = parseColorTokenParts(token);
+		if (parts.kind === "token" && resolveConcreteColorHex(parts.token, palette)) return token;
+	}
+	return canonicalToken(reference, palette);
+}
+function safeTokenOr(candidate, fallback, backgroundHex, palette) {
+	return firstSafeToken([candidate], backgroundHex, palette) ?? fallback;
+}
+function firstSafeToken(candidates, backgroundHex, palette, preferredEquivalentTokens = []) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		const token = canonicalToken(candidate, palette, preferredEquivalentTokens);
+		if (!token || seen.has(token)) continue;
+		seen.add(token);
+		const foregroundHex = resolveConcreteColorHex(token, palette);
+		if (foregroundHex && contrastRatio(backgroundHex, foregroundHex) >= 4.5) return token;
+	}
+	return null;
+}
+function canonicalToken(reference, palette, preferredEquivalentTokens = []) {
+	const normalized = normalizedReference(reference);
+	if (!normalized || normalized === "transparent") return null;
+	const direct = parseThemeColorToken(normalized);
+	if (direct && resolveConcreteColorHex(direct, palette)) return direct;
+	const referenceHex = resolveConcreteColorHex(normalized, palette);
+	if (!referenceHex) return null;
+	const equivalent = [
+		...preferredEquivalentTokens,
+		...CANONICAL_EQUIVALENT_TOKEN_ORDER,
+		...Object.keys(palette).sort()
+	].find((token) => {
+		const parsed = parseThemeColorToken(token);
+		return parsed !== null && resolveConcreteColorHex(parsed, palette)?.toLowerCase() === referenceHex.toLowerCase();
+	});
+	return equivalent ? parseThemeColorToken(equivalent) : null;
+}
+function paletteToken(reference) {
+	const parts = parseColorTokenParts(reference);
+	return parts.kind === "token" && parts.opacityPercent === null ? parts.token : null;
+}
+function normalizedReference(value) {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : null;
+}
+//#endregion
 //#region ../theme-core/src/utils/colorStyles.ts
 const COLOR_VAR_PREFIX = "--tb-";
 function parseToken(source) {
@@ -1791,14 +2111,449 @@ function shadeBackgroundEffect(config) {
 * palette context and happens in `parseThemeColorReference`.
 */
 const tokenOrCssColorValueSchema = z.string();
+const CSS_COLOR_FUNCTION_PATTERN = /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color|color-mix|light-dark)\(/i;
+const CSS_HEX_COLOR_PATTERN = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const CSS_COLOR_KEYWORDS = /* @__PURE__ */ new Set([
+	"transparent",
+	"currentcolor",
+	"inherit",
+	"initial",
+	"revert",
+	"revert-layer",
+	"unset"
+]);
+const COMMON_CSS_NAMED_COLORS = /* @__PURE__ */ new Set([
+	"black",
+	"blue",
+	"gray",
+	"green",
+	"grey",
+	"orange",
+	"pink",
+	"purple",
+	"red",
+	"white",
+	"yellow"
+]);
+function isCssColorLiteral(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return false;
+	return CSS_HEX_COLOR_PATTERN.test(trimmed) || CSS_COLOR_FUNCTION_PATTERN.test(trimmed) || /^var\(/i.test(trimmed) || CSS_COLOR_KEYWORDS.has(trimmed.toLowerCase());
+}
+function parseContextThemeColorToken(value, context) {
+	const parts = parseColorTokenParts(value);
+	if (parts.kind !== "token") return null;
+	if (!(Boolean(context?.palette?.[value.trim()]) || parts.opacityPercent !== null && Boolean(context?.palette?.[parts.token]))) return null;
+	return value.trim();
+}
+function isTokenShapedTypo(value) {
+	if (COMMON_CSS_NAMED_COLORS.has(value.toLowerCase())) return false;
+	if (!/^[a-zA-Z][a-zA-Z0-9]*(?:-[a-zA-Z0-9]+)*(?:\/[^/]+)?$/.test(value)) return false;
+	return !isCssColorLiteral(value);
+}
+function warnUnknownThemeColorReference(value) {
+	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+	if (!isTokenShapedTypo(value)) return;
+	console.warn(`[theme-core] Unknown Theme V2 color token "${value}" treated as literal CSS. Use raw:* for deliberate custom CSS values.`);
+}
+function parseThemeColorReference(input, context) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("raw:")) return {
+		kind: "literal-css",
+		value: trimmed.slice(4)
+	};
+	const contextToken = parseContextThemeColorToken(trimmed, context);
+	if (contextToken) return {
+		kind: "palette-context-token",
+		token: contextToken
+	};
+	const knownToken = parseThemeColorToken(trimmed);
+	if (knownToken) return {
+		kind: "theme-token",
+		token: knownToken
+	};
+	warnUnknownThemeColorReference(trimmed);
+	return {
+		kind: "literal-css",
+		value: trimmed
+	};
+}
+function resolveThemeColorReferenceValue(input, context) {
+	const reference = parseThemeColorReference(input, context);
+	return reference.kind === "literal-css" ? reference.value : rgbColorValue(reference.token);
+}
 //#endregion
 //#region ../theme-core/src/buttons/buttonSurfaceContext.ts
+/**
+* Derive only what the rendered section can honestly prove about its backing.
+* Images, gradients, alpha/composite layers and arbitrary CSS remain unknown.
+*/
+function deriveButtonSurfaceContext(input, palette, fallbackToken) {
+	const background = deriveKnownBackground(input, palette, fallbackToken);
+	if (background.kind === "unknown") return background;
+	const explicitForeground = resolveKnownColour(input.kind === "solid" || input.kind === "inherit" ? input.foreground ?? "" : "", palette);
+	const foreground = explicitForeground && contrastRatio(background.colour.hex, explicitForeground.hex) >= 4.5 ? explicitForeground : safestBlackOrWhite(background.colour.hex);
+	return {
+		kind: "known-solid",
+		source: background.source,
+		surface: {
+			kind: "solid",
+			backgroundHex: background.colour.hex,
+			backgroundCss: background.colour.css,
+			foregroundHex: foreground.hex,
+			foregroundCss: foreground.css
+		}
+	};
+}
+function deriveKnownBackground(input, palette, fallbackToken) {
+	switch (input.kind) {
+		case "inherit": return fallbackBackground(fallbackToken, palette);
+		case "image": return {
+			kind: "unknown",
+			reason: "image-background"
+		};
+		case "gradient": return {
+			kind: "unknown",
+			reason: "gradient-background"
+		};
+		case "unknown": return {
+			kind: "unknown",
+			reason: "unresolvable-colour"
+		};
+		case "solid": if (input.composited) return {
+			kind: "unknown",
+			reason: "composited-background"
+		};
+	}
+	const authored = readNonEmptyString(input.color);
+	const backgroundValue = authored ?? fallbackToken;
+	if (!backgroundValue) return {
+		kind: "unknown",
+		reason: "missing-background"
+	};
+	const colour = resolveKnownSurfaceColour(backgroundValue, palette, authored ? fallbackToken : void 0);
+	if (!colour) return {
+		kind: "unknown",
+		reason: "unresolvable-colour"
+	};
+	return {
+		kind: "known",
+		colour,
+		source: authored ? colour.source : "fallback-token"
+	};
+}
+function resolveKnownSurfaceColour(value, palette, underlayReference) {
+	const hex = resolveOpaqueSurfaceHex(value, palette, underlayReference);
+	if (!hex) return resolveKnownColour(value, palette);
+	const reference = parseThemeColorReference(value, { palette });
+	return {
+		hex,
+		css: resolveThemeColorReferenceValue(value, { palette }),
+		source: reference.kind === "literal-css" ? "literal-css" : "palette-token"
+	};
+}
+function fallbackBackground(fallbackToken, palette) {
+	if (!fallbackToken) return {
+		kind: "unknown",
+		reason: "missing-background"
+	};
+	const colour = resolveKnownColour(fallbackToken, palette);
+	return colour ? {
+		kind: "known",
+		colour,
+		source: "fallback-token"
+	} : {
+		kind: "unknown",
+		reason: "unresolvable-colour"
+	};
+}
+/**
+* The complete button context a surface publishes: `--rb-action-*` variables
+* for every role, resolved against the surface when its colour is provable,
+* and an explicit reset when it is not (image, gradient, composited), so a
+* nested surface never inherits a context resolved for an outer band.
+* A surface with no background of its own publishes nothing and inherits.
+*
+* Sections (through the blocks background transforms), card roles and opaque
+* block panels all publish through this one function.
+*/
+function surfaceButtonContextStyles(input) {
+	if (!input.buttonSystem) return {};
+	const context = deriveButtonSurfaceContext(input.surface, input.palette, input.fallbackToken);
+	if (context.kind !== "known-solid") return context.reason === "missing-background" ? {} : contextualButtonSurfaceResetStyles();
+	return knownSurfaceButtonContextStyles({
+		surface: context.surface,
+		palette: input.palette,
+		buttonSystem: input.buttonSystem
+	});
+}
+/** Every role's contextual styles against one proven solid surface. */
+function knownSurfaceButtonContextStyles(input) {
+	return Object.fromEntries(VARIANT_ROLES.flatMap((role) => Object.entries(contextualButtonSurfaceStyles(resolveContextualButtonRole({
+		role,
+		buttonSystem: input.buttonSystem,
+		palette: input.palette,
+		surface: input.surface
+	})))));
+}
+function resolveContextualButtonRole(input) {
+	const requested = findVariant(input.buttonSystem, input.role);
+	if (!requested) return {
+		kind: "unresolved",
+		requestedRole: input.role,
+		rejectedCandidates: []
+	};
+	const rejected = [];
+	const preferred = compileCandidate(requested, input.buttonSystem, input.palette, input.surface);
+	if (preferred.ok) {
+		if (preferred.contextualHoverRepair) return {
+			kind: "repaired",
+			requestedRole: input.role,
+			candidate: "contextual-hover",
+			states: preferred.states,
+			focusIndicator: preferred.focusIndicator,
+			boundary: boundaryForVariant(requested),
+			rejectedCandidates: []
+		};
+		return {
+			kind: "preferred",
+			requestedRole: input.role,
+			states: preferred.states,
+			focusIndicator: preferred.focusIndicator,
+			boundary: boundaryForVariant(requested)
+		};
+	}
+	rejected.push({
+		candidate: "preferred",
+		error: preferred.error
+	});
+	const policy = input.buttonSystem.surfacePolicy ?? STANDARD_BUTTON_SURFACE_POLICY;
+	for (const fallback of policy[input.role]) {
+		const candidate = candidateVariant(fallback, requested, input.buttonSystem);
+		if (!candidate) continue;
+		const compiled = compileCandidate(candidate.variant, input.buttonSystem, input.palette, input.surface);
+		if (!compiled.ok) {
+			rejected.push({
+				candidate: candidate.name,
+				error: compiled.error
+			});
+			continue;
+		}
+		return {
+			kind: "repaired",
+			requestedRole: input.role,
+			candidate: candidate.name,
+			states: candidate.name === "surface-outline" ? withSurfaceInversion(compiled.states, input.surface) : compiled.states,
+			focusIndicator: compiled.focusIndicator,
+			boundary: candidate.boundary,
+			rejectedCandidates: rejected
+		};
+	}
+	return {
+		kind: "unresolved",
+		requestedRole: input.role,
+		rejectedCandidates: rejected
+	};
+}
+function contextualButtonSurfaceStyles(resolution) {
+	if (resolution.kind === "unresolved") return resetActionVariables(resolution.requestedRole);
+	const styles = {};
+	for (const state of BUTTON_VISUAL_STATES) {
+		const colour = resolution.states[state];
+		const prefix = actionVariablePrefix(resolution.requestedRole, state);
+		styles[`${prefix}-background-color`] = colour.kind === "solid" || colour.kind === "known-solid" ? colour.backgroundCss : "transparent";
+		styles[`${prefix}-background-image`] = colour.kind === "gradient" ? colour.backgroundCss : "none";
+		styles[`${prefix}-color`] = colour.foregroundCss;
+	}
+	const focus = resolution.focusIndicator;
+	styles[actionVariableName(resolution.requestedRole, "focus", "outline")] = focus.kind === "two-tone" ? `2px solid ${focus.innerCss}` : `3px solid ${focus.colorCss}`;
+	styles[actionVariableName(resolution.requestedRole, "focus", "outline-offset")] = focus.kind === "two-tone" ? "2px" : "3px";
+	styles[actionVariableName(resolution.requestedRole, "focus", "box-shadow")] = focus.kind === "two-tone" ? `0 0 0 4px ${focus.outerCss}` : "none";
+	styles[actionVariableName(resolution.requestedRole, "base", "outline")] = resolution.boundary ? `${resolution.boundary.width} solid ${resolution.boundary.color}` : "none";
+	styles[actionVariableName(resolution.requestedRole, "base", "outline-offset")] = resolution.boundary ? `-${resolution.boundary.width}` : "0px";
+	return styles;
+}
+/**
+* Break an inherited surface contract when a nested element establishes a
+* backing whose colours cannot be proven (for example an image or gradient).
+*/
+function contextualButtonSurfaceResetStyles() {
+	return Object.fromEntries(VARIANT_ROLES.flatMap((role) => Object.entries(resetActionVariables(role))));
+}
+function resetActionVariables(role) {
+	const styles = {};
+	for (const state of BUTTON_VISUAL_STATES) for (const property of [
+		"background-color",
+		"background-image",
+		"color"
+	]) styles[actionVariableName(role, state, property)] = "initial";
+	for (const [state, property] of [
+		["base", "outline"],
+		["base", "outline-offset"],
+		["focus", "outline"],
+		["focus", "outline-offset"],
+		["focus", "box-shadow"]
+	]) styles[actionVariableName(role, state, property)] = "initial";
+	return styles;
+}
+function withSurfaceInversion(states, surface) {
+	const inverted = {
+		kind: "known-solid",
+		backgroundCss: surface.foregroundCss,
+		foregroundCss: surface.backgroundCss
+	};
+	return {
+		...states,
+		hover: inverted,
+		active: inverted
+	};
+}
 function actionVariableName(role, state, property) {
 	return `--rb-action-${role}-${state}-${property}`;
 }
 function actionVariableFallback(role, state, property, fallback) {
 	return `var(${actionVariableName(role, state, property)}, ${fallback})`;
 }
+function actionVariablePrefix(role, state) {
+	return `--rb-action-${role}-${state}`;
+}
+function compileCandidate(variant, system, palette, surface) {
+	return compileButtonColourStates({
+		variant,
+		global: system.global,
+		palette,
+		surface
+	});
+}
+function candidateVariant(fallback, requested, system) {
+	if (fallback.kind === "variant") {
+		const variant = findVariant(system, fallback.role);
+		return variant ? {
+			name: fallback.role,
+			variant,
+			boundary: boundaryForVariant(variant)
+		} : null;
+	}
+	const width = BORDER_WIDTH_MAP$3.border ?? "1px";
+	return {
+		name: "surface-outline",
+		variant: {
+			...requested,
+			background: {
+				type: "surface",
+				role: "link"
+			},
+			border: { widthClass: "border" },
+			hoverBackgroundToken: void 0,
+			contextualHover: void 0,
+			effects: void 0
+		},
+		boundary: {
+			width,
+			color: "currentColor"
+		}
+	};
+}
+function boundaryForVariant(variant) {
+	if (!variant.border) return null;
+	return {
+		width: BORDER_WIDTH_MAP$3[variant.border.widthClass] ?? "1px",
+		color: "currentColor"
+	};
+}
+function findVariant(system, role) {
+	return system.variants.find((variant) => variant.enabled && variant.id === role);
+}
+function resolveKnownColour(value, palette) {
+	const reference = parseThemeColorReference(value, { palette });
+	if (reference.kind !== "literal-css") {
+		const token = String(reference.token);
+		const paletteHex = palette[token];
+		const hex = paletteHex ? normalizeOpaqueHex(paletteHex) : null;
+		if (hex) return {
+			hex,
+			css: resolveThemeColorReferenceValue(value, { palette }),
+			source: "palette-token"
+		};
+		const namedHex = NAMED_OPAQUE_COLOURS[token.toLowerCase()];
+		return namedHex ? {
+			hex: namedHex,
+			css: token,
+			source: "literal-css"
+		} : null;
+	}
+	const hex = normalizeOpaqueCssColour(reference.value);
+	return hex ? {
+		hex,
+		css: reference.value,
+		source: "literal-css"
+	} : null;
+}
+const NAMED_OPAQUE_COLOURS = {
+	black: "#000000",
+	white: "#ffffff",
+	red: "#ff0000",
+	green: "#008000",
+	blue: "#0000ff",
+	yellow: "#ffff00",
+	gray: "#808080",
+	grey: "#808080",
+	orange: "#ffa500",
+	purple: "#800080",
+	pink: "#ffc0cb"
+};
+function normalizeOpaqueCssColour(value) {
+	const trimmed = value.trim();
+	const hex = normalizeOpaqueHex(trimmed);
+	if (hex) return hex;
+	return NAMED_OPAQUE_COLOURS[trimmed.toLowerCase()] ?? normalizeOpaqueRgb(trimmed) ?? normalizeOpaqueOklch(trimmed);
+}
+function normalizeOpaqueRgb(value) {
+	const match = value.match(/^rgb\(\s*(\d{1,3})\s*[, ]\s*(\d{1,3})\s*[, ]\s*(\d{1,3})\s*\)$/i);
+	if (!match) return null;
+	const channels = match.slice(1).map(Number);
+	if (channels.some((channel) => channel < 0 || channel > 255)) return null;
+	const [red, green, blue] = channels;
+	return red === void 0 || green === void 0 || blue === void 0 ? null : rgbToHex(red, green, blue);
+}
+function normalizeOpaqueOklch(value) {
+	const match = value.match(/^oklch\(\s*([\d.]+)(%)?\s+([\d.]+)\s+([\d.]+)(?:deg)?\s*\)$/i);
+	if (!match?.[1] || !match[3] || !match[4]) return null;
+	const lightness = Number(match[1]) / (match[2] ? 100 : 1);
+	const chroma = Number(match[3]);
+	const hue = Number(match[4]);
+	if (![
+		lightness,
+		chroma,
+		hue
+	].every(Number.isFinite)) return null;
+	if (lightness < 0 || lightness > 1) return null;
+	const lab = oklchToOklab(lightness, chroma, hue);
+	const rgb = oklabToSrgb(lab.L, lab.a, lab.b);
+	return rgbToHex(clampChannel(rgb.r), clampChannel(rgb.g), clampChannel(rgb.b));
+}
+function clampChannel(value) {
+	return Math.max(0, Math.min(255, value));
+}
+function normalizeOpaqueHex(value) {
+	const match = value.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+	if (!match?.[1]) return null;
+	return `#${(match[1].length === 3 ? match[1].split("").map((digit) => `${digit}${digit}`).join("") : match[1]).toLowerCase()}`;
+}
+function safestBlackOrWhite(backgroundHex) {
+	return contrastRatio(backgroundHex, "#000000") >= contrastRatio(backgroundHex, "#ffffff") ? {
+		hex: "#000000",
+		css: "#000000",
+		source: "literal-css"
+	} : {
+		hex: "#ffffff",
+		css: "#ffffff",
+		source: "literal-css"
+	};
+}
+function readNonEmptyString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : null;
+}
 //#endregion
 //#region ../theme-core/src/buttons/resolvedButtonCss.ts
 /**
@@ -3914,6 +4669,50 @@ function cardDecorationPseudoRules(containerSelectors, decorations, resolveColor
 	});
 }
 //#endregion
+//#region ../theme-core/src/surfaces/opaqueSurface.ts
+/**
+* The declarations that make an element own its surface: `color`, every
+* `--rb-surface-*` role and every `--rb-action-*` variable. Card roles and
+* opaque block panels both publish through this, so a nested surface can never
+* inherit a band's light text or its band-resolved buttons.
+*/
+function opaqueSurfaceDeclarations(paint, context) {
+	if (paint.kind === "transparent") return inheritedSurfaceDeclarations();
+	const textToken = paint.foregroundToken ?? "text";
+	const foreground = resolveSurfaceForeground(paint.kind === "solid" ? {
+		type: "color",
+		color: paint.token,
+		textColor: textToken
+	} : {
+		type: "gradient",
+		textColor: textToken
+	}, context.palette, { linkHover: context.linkHoverToken });
+	const buttonContext = context.buttonSystem ? surfaceButtonContextStyles({
+		surface: paint.kind === "solid" ? {
+			kind: "solid",
+			color: paint.token,
+			foreground: foreground.kind === "known" ? foreground.roles.link : void 0,
+			composited: false
+		} : { kind: "gradient" },
+		palette: context.palette,
+		buttonSystem: context.buttonSystem
+	}) : contextualButtonSurfaceResetStyles();
+	return [...surfaceForegroundDeclarations(foreground.kind === "known" ? surfaceForegroundInputFromResolved(foreground, rgbColorValue) : { text: colorValue(textToken) }), ...Object.entries(buttonContext).map(([property, value]) => `${property}: ${value};`)];
+}
+function colorValue(token) {
+	const parsed = parseThemeColorToken(token);
+	return parsed ? rgbColorValue(parsed) : token;
+}
+/** Every property a surface publishes, set to `inherit`. */
+function inheritedSurfaceDeclarations() {
+	return [
+		"color",
+		...Object.values(SURFACE_FOREGROUND_CSS_VARS),
+		"--rb-surface-link-hover-decoration",
+		...Object.keys(contextualButtonSurfaceResetStyles())
+	].map((property) => `${property}: inherit;`);
+}
+//#endregion
 //#region ../theme-core/src/utils/cssDeclarations.ts
 /** Render CSS declarations whether callers provide terminators or fragments. */
 function renderCssDeclarations(declarations) {
@@ -5213,12 +6012,22 @@ const mediaPresentationSchema = commonSchema.extend({
 const boxBackgroundSchema = z.discriminatedUnion("type", [
 	commonSchema.extend({
 		type: z.literal("color"),
-		color: tokenOrCssColorValueSchema.nullable().optional()
+		color: tokenOrCssColorValueSchema.nullable().optional(),
+		/**
+		* Compiler-owned. The scrim a site-style colour surface lays over media
+		* that replaces it (a Look's band meeting an authored photo), sized so the
+		* surface's foreground stays legible over any pixel. A colour background
+		* never draws it itself; `resolveSectionBackground` moves it onto the
+		* merged media background as its overlay.
+		*/
+		mediaScrim: boxBackgroundOverlaySchema.nullable().optional()
 	}),
 	commonSchema.extend({
 		type: z.literal("gradient"),
 		gradient: z.string().nullable().optional(),
-		gradientPresetId: z.string().min(1).nullable().optional()
+		gradientPresetId: z.string().min(1).nullable().optional(),
+		/** Compiler-owned; see the colour branch. */
+		mediaScrim: boxBackgroundOverlaySchema.nullable().optional()
 	}),
 	mediaPresentationSchema.extend({
 		type: z.literal("image"),
@@ -6048,6 +6857,172 @@ function generateShadowCssVars(theme) {
 	};
 }
 //#endregion
+//#region ../theme-core/src/blocks/opaquePanels.ts
+/**
+* Every element in `blocks-static/` CSS that paints its own background behind
+* text or buttons, with the palette token it paints.
+*
+* The CSS owns layout and the paint itself; this registry owns what the paint
+* implies. `generateOpaquePanelCss` publishes each panel's foreground contract
+* and button context from the theme, exactly as card roles and section
+* backgrounds do, so a white panel inside a dark band never inherits the band's
+* light text or its band-resolved buttons. `opaquePanels.test.ts` scans the
+* static CSS and fails when a rule paints a surface token without an entry
+* here, or when a registered rule declares the contract by hand.
+*
+* Selectors are written without the theme-scope prefix; the generator adds it.
+* A `transparent` entry is a treatment that turns a surface-owning class into
+* a boxless row, so it hands the surrounding surface's contract back.
+*/
+const opaquePanels = [
+	{
+		selector: ":where([data-block=\"event-registration\"], [data-block=\"appointment-booking\"]) .rb-reg-surface",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ":where([data-block='event-registration']) .er-booking-teaser",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ":where([data-block='event-registration']) .er-booking-bar",
+		paint: {
+			kind: "solid",
+			token: "background"
+		}
+	},
+	{
+		selector: ":where([data-block='event-registration']) .er-modal",
+		paint: {
+			kind: "solid",
+			token: "background"
+		}
+	},
+	{
+		selector: ":where([data-block='event-registration']) .er-booking-overlay__panel",
+		paint: {
+			kind: "solid",
+			token: "background"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .event-agenda-card",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .event-timetable-event",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .event-week-board",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .event-week-board-top",
+		paint: {
+			kind: "solid",
+			token: "surfaceAlt"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .event-week-board-foot",
+		paint: {
+			kind: "solid",
+			token: "surfaceAlt"
+		}
+	},
+	{
+		selector: ":where([data-block='event-calendar']) .ec-modal",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ".event-listing-compact-container",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ".shop__card",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: ".shop--register .shop__card",
+		paint: { kind: "transparent" }
+	},
+	{
+		selector: ":where([data-block=\"shop\"]) .shop__return",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: "[data-block=\"feature-cards\"][data-block-composition=\"asymmetric-emphasis\"] .rb-feature-card:nth-child(even)",
+		paint: {
+			kind: "solid",
+			token: "secondary"
+		}
+	},
+	{
+		selector: ".rb-feature-cards-grid--editorial-diptych .rb-feature-card[data-surface-role=\"panel\"]",
+		paint: {
+			kind: "solid",
+			token: "primary"
+		}
+	},
+	{
+		selector: ":is(.rb-event-list-treatment-ruled-register, .rb-event-list-treatment-editorial-register, .rb-event-list-treatment-dense-index) .event-card.event-card",
+		paint: { kind: "transparent" }
+	},
+	{
+		selector: ".feedback-callout",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	},
+	{
+		selector: "[data-block=\"gifting\"] .gifting-feedback",
+		paint: {
+			kind: "solid",
+			token: "surface"
+		}
+	}
+];
+/**
+* Publishes every registered panel's surface contract. Emitted after the card
+* CSS in both the theme runtime and the SDK theme bridge, so a composition
+* that recolours a card role (the feature-card diptych panel) or a treatment
+* that empties one (the event registers) wins over the role's own contract.
+*/
+function generateOpaquePanelCss(input) {
+	return opaquePanels.map((panel) => {
+		const declarations = opaqueSurfaceDeclarations(panel.paint, input.surface);
+		return `:where([data-theme-scope="${input.themeId}"]) ${panel.selector} {\n  ${renderCssDeclarations(declarations)}\n}`;
+	}).join("\n\n");
+}
+//#endregion
 //#region ../theme-core/src/site-styles/styleTags.ts
 /**
 * Descriptive style-axis metadata for button personalities and palette
@@ -9504,6 +10479,17 @@ function defineBlockAppearancePreset(preset) {
 * (`defineBlockAppearancePreset` defaults it to `none`) — the block's own
 * composition still governs how its items look. The per-Look rationale for the card-bearing ones lives
 * in `.project/plans/1297-card-role-contract-site-styles-own-card-surfaces/mapping-table.md`.
+*
+* A Look asking for the `alternative` or `open` role is offered only where the
+* site style defines that role (`siteStyleSupportsLookDesign`), so two Looks
+* that differ only in role are distinct wherever both are offered.
+*
+* Retiring a Look is removing its entry. A stored pin to a retired id reads as
+* an unsupported pin in the page design editor model and renders the block's
+* auto Look, the same path an unavailable Look takes. Duplicates retired in
+* the 2026-09 Look audit: `feature-cards-soft-panels`,
+* `feature-cards-photo-tiles`, `feature-cards-editorial-pathways`,
+* `testimonials-default-cards`.
 */
 const brandScrimOptionGroups = [{
 	id: "image-surface-treatment",
@@ -9888,16 +10874,6 @@ defineBlockAppearancePreset({
 			treatment: "framed-programme"
 		}
 	}
-}), defineBlockAppearancePreset({
-	id: "feature-cards-soft-panels",
-	target: "feature-cards",
-	label: "Soft tinted panels",
-	blockKinds: ["block.feature-cards"],
-	design: {
-		sectionSurface: "base",
-		contentFrame: plainFrame,
-		cardRole: "alternative"
-	}
 }), defineBlockAppearancePreset({
 	id: "feature-cards-editorial-diptych",
 	target: "feature-cards",
@@ -9909,27 +10885,6 @@ defineBlockAppearancePreset({
 		contentFrame: plainFrame,
 		cardRole: "default"
 	}
-}), defineBlockAppearancePreset({
-	id: "feature-cards-editorial-pathways",
-	target: "feature-cards",
-	label: "Editorial pathways",
-	blockKinds: ["block.feature-cards"],
-	constraints: { layoutVariantKeys: ["editorial-pathways"] },
-	design: {
-		sectionSurface: "base",
-		contentFrame: plainFrame,
-		cardRole: "default"
-	}
-}), defineBlockAppearancePreset({
-	id: "feature-cards-photo-tiles",
-	target: "feature-cards",
-	label: "Photo tiles",
-	blockKinds: ["block.feature-cards"],
-	design: {
-		sectionSurface: "base",
-		contentFrame: plainFrame,
-		cardRole: "default"
-	}
 }), defineBlockAppearancePreset({
 	id: "events-lined-panel",
 	target: "events",
@@ -10018,16 +10973,6 @@ defineBlockAppearancePreset({
 		contentFrame: panelFrame("raised"),
 		cardRole: "default"
 	}
-}), defineBlockAppearancePreset({
-	id: "testimonials-default-cards",
-	target: "testimonials",
-	label: "Default cards",
-	blockKinds: ["block.testimonials"],
-	design: {
-		sectionSurface: "base",
-		contentFrame: plainFrame,
-		cardRole: "default"
-	}
 }), defineBlockAppearancePreset({
 	id: "testimonials-statement-cards",
 	target: "testimonials",
@@ -11262,9 +12207,7 @@ const curatedSiteStyles = [
 		recommendedAppearancePresetIds: [
 			"hero-split-editorial",
 			"intro-portrait-bio",
-			"feature-cards-soft-panels",
-			"feature-cards-editorial-columns",
-			"feature-cards-photo-tiles",
+			"feature-cards-bold-colors",
 			"testimonials-non-carded",
 			"faq-contained-help",
 			"contact-form-panel"
@@ -11908,8 +12851,7 @@ const curatedSiteStyles = [
 			"intro-portrait-bio",
 			"feature-cards-editorial-columns",
 			"feature-cards-editorial-diptych",
-			"feature-cards-editorial-pathways",
-			"feature-cards-soft-panels",
+			"feature-cards-bold-colors",
 			"events-lined-panel",
 			"testimonials-non-carded",
 			"faq-base-accordion",
@@ -12563,7 +13505,7 @@ ${`:where([data-theme-scope="${themeId}"]) :where([data-block="event-registratio
   --er-step-inactive: rgb(var(--tb-mutedText));
   --er-step-completed: rgb(var(--tb-success));
   --er-step-text: rgb(255 255 255);
-  --er-step-text-active: rgb(var(--tb-primaryText, 255 255 255));
+  --er-step-text-active: rgb(var(--tb-onPrimary, 255 255 255));
   --er-step-connector: rgba(var(--tb-border), 0.5);
 
   /* Step title */
@@ -12607,7 +13549,7 @@ ${`:where([data-theme-scope="${themeId}"]) :where([data-block="event-registratio
 
   /* Checkmark indicator */
   --er-check-bg: rgb(var(--tb-primary));
-  --er-check-text: rgb(var(--tb-primaryText, 255 255 255));
+  --er-check-text: rgb(var(--tb-onPrimary, 255 255 255));
 
   /* Order summary */
   --er-summary-bg: rgba(var(--tb-primary), 0.1);
@@ -12819,7 +13761,7 @@ ${`:where([data-theme-scope="${themeId}"]) :where([data-block="appointment-booki
   --rb-reg-step-completed: rgb(var(--tb-success));
   --rb-reg-step-inactive: rgb(var(--tb-mutedText));
   --rb-reg-step-text: rgb(255 255 255);
-  --rb-reg-step-text-active: rgb(var(--tb-primaryText, 255 255 255));
+  --rb-reg-step-text-active: rgb(var(--tb-onPrimary, 255 255 255));
   --rb-reg-step-connector: rgba(var(--tb-border), 0.5);
   --rb-reg-summary-bg: var(--ab-muted-bg);
   --rb-reg-summary-border: var(--ab-card-border);
@@ -16682,140 +17624,17 @@ const containerResponsiveThemeCss = `/*
   border: 1px solid var(--rb-reg-border, rgb(var(--tb-border, 226 232 240)));
   padding: clamp(1rem, 2vw, 1.5rem);
   background: var(--rb-reg-surface-bg, rgb(var(--tb-surface, 248 250 252)));
-  color: var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42))));
-  --rb-surface-text-color: var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42))));
-  --rb-surface-heading-color: var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42))));
-  --rb-surface-link-color: var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42))));
-  --rb-surface-link-hover-color: var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42))));
-  --rb-surface-link-hover-decoration: underline;
-  --rb-surface-supporting-color: var(--rb-reg-on-surface-muted, var(--rb-reg-on-surface, rgb(var(--tb-onSurface, var(--tb-text, 15 23 42)))));
+  /* The panel paints its own surface, so it owns its foreground and its
+   * button context. Both are published from the theme by the opaque-panel
+   * registry (theme-core/src/blocks/opaquePanels.ts): an enclosing brand band
+   * would otherwise hand its light text and band-resolved buttons (on Anna's
+   * therapy page, a white-on-white Continue) to this light panel. */
   transition: border-color var(--rb-block-transition, 150ms) ease;
   width: 100%;
   max-width: 800px;
   margin-inline: 0;
 }
 
-/* The panel paints its own opaque surface, so it also has to break the button
- * colour contract it inherits. An enclosing section that sits on a brand band
- * publishes \`--rb-action-*\` variables resolved against *that* band — on Anna's
- * therapy page a ghost primary: transparent background, white label. Those
- * variables inherit, so without this reset a Continue button inside the light
- * form panel renders white-on-white and only appears on hover.
- *
- * Resetting to \`initial\` sends each button back to the generated fallback in
- * its own rule (\`var(--rb-action-…, rgb(var(--tb-primary)))\`), which is the
- * theme's standard button resolved against a normal surface — correct here,
- * because this panel *is* a normal surface.
- *
- * Mirrors \`contextualButtonSurfaceResetStyles()\` in theme-core/buttons; the
- * pairing is pinned by registration-surface-action-reset.test.ts. */
-:where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-reg-surface {
-  --rb-action-primary-base-background-color: initial;
-  --rb-action-primary-base-background-image: initial;
-  --rb-action-primary-base-color: initial;
-  --rb-action-primary-hover-background-color: initial;
-  --rb-action-primary-hover-background-image: initial;
-  --rb-action-primary-hover-color: initial;
-  --rb-action-primary-focus-background-color: initial;
-  --rb-action-primary-focus-background-image: initial;
-  --rb-action-primary-focus-color: initial;
-  --rb-action-primary-active-background-color: initial;
-  --rb-action-primary-active-background-image: initial;
-  --rb-action-primary-active-color: initial;
-  --rb-action-primary-disabled-background-color: initial;
-  --rb-action-primary-disabled-background-image: initial;
-  --rb-action-primary-disabled-color: initial;
-  --rb-action-primary-base-outline: initial;
-  --rb-action-primary-base-outline-offset: initial;
-  --rb-action-primary-focus-outline: initial;
-  --rb-action-primary-focus-outline-offset: initial;
-  --rb-action-primary-focus-box-shadow: initial;
-
-  --rb-action-secondary-base-background-color: initial;
-  --rb-action-secondary-base-background-image: initial;
-  --rb-action-secondary-base-color: initial;
-  --rb-action-secondary-hover-background-color: initial;
-  --rb-action-secondary-hover-background-image: initial;
-  --rb-action-secondary-hover-color: initial;
-  --rb-action-secondary-focus-background-color: initial;
-  --rb-action-secondary-focus-background-image: initial;
-  --rb-action-secondary-focus-color: initial;
-  --rb-action-secondary-active-background-color: initial;
-  --rb-action-secondary-active-background-image: initial;
-  --rb-action-secondary-active-color: initial;
-  --rb-action-secondary-disabled-background-color: initial;
-  --rb-action-secondary-disabled-background-image: initial;
-  --rb-action-secondary-disabled-color: initial;
-  --rb-action-secondary-base-outline: initial;
-  --rb-action-secondary-base-outline-offset: initial;
-  --rb-action-secondary-focus-outline: initial;
-  --rb-action-secondary-focus-outline-offset: initial;
-  --rb-action-secondary-focus-box-shadow: initial;
-
-  --rb-action-outline-base-background-color: initial;
-  --rb-action-outline-base-background-image: initial;
-  --rb-action-outline-base-color: initial;
-  --rb-action-outline-hover-background-color: initial;
-  --rb-action-outline-hover-background-image: initial;
-  --rb-action-outline-hover-color: initial;
-  --rb-action-outline-focus-background-color: initial;
-  --rb-action-outline-focus-background-image: initial;
-  --rb-action-outline-focus-color: initial;
-  --rb-action-outline-active-background-color: initial;
-  --rb-action-outline-active-background-image: initial;
-  --rb-action-outline-active-color: initial;
-  --rb-action-outline-disabled-background-color: initial;
-  --rb-action-outline-disabled-background-image: initial;
-  --rb-action-outline-disabled-color: initial;
-  --rb-action-outline-base-outline: initial;
-  --rb-action-outline-base-outline-offset: initial;
-  --rb-action-outline-focus-outline: initial;
-  --rb-action-outline-focus-outline-offset: initial;
-  --rb-action-outline-focus-box-shadow: initial;
-
-  --rb-action-ghost-base-background-color: initial;
-  --rb-action-ghost-base-background-image: initial;
-  --rb-action-ghost-base-color: initial;
-  --rb-action-ghost-hover-background-color: initial;
-  --rb-action-ghost-hover-background-image: initial;
-  --rb-action-ghost-hover-color: initial;
-  --rb-action-ghost-focus-background-color: initial;
-  --rb-action-ghost-focus-background-image: initial;
-  --rb-action-ghost-focus-color: initial;
-  --rb-action-ghost-active-background-color: initial;
-  --rb-action-ghost-active-background-image: initial;
-  --rb-action-ghost-active-color: initial;
-  --rb-action-ghost-disabled-background-color: initial;
-  --rb-action-ghost-disabled-background-image: initial;
-  --rb-action-ghost-disabled-color: initial;
-  --rb-action-ghost-base-outline: initial;
-  --rb-action-ghost-base-outline-offset: initial;
-  --rb-action-ghost-focus-outline: initial;
-  --rb-action-ghost-focus-outline-offset: initial;
-  --rb-action-ghost-focus-box-shadow: initial;
-
-  --rb-action-accent-base-background-color: initial;
-  --rb-action-accent-base-background-image: initial;
-  --rb-action-accent-base-color: initial;
-  --rb-action-accent-hover-background-color: initial;
-  --rb-action-accent-hover-background-image: initial;
-  --rb-action-accent-hover-color: initial;
-  --rb-action-accent-focus-background-color: initial;
-  --rb-action-accent-focus-background-image: initial;
-  --rb-action-accent-focus-color: initial;
-  --rb-action-accent-active-background-color: initial;
-  --rb-action-accent-active-background-image: initial;
-  --rb-action-accent-active-color: initial;
-  --rb-action-accent-disabled-background-color: initial;
-  --rb-action-accent-disabled-background-image: initial;
-  --rb-action-accent-disabled-color: initial;
-  --rb-action-accent-base-outline: initial;
-  --rb-action-accent-base-outline-offset: initial;
-  --rb-action-accent-focus-outline: initial;
-  --rb-action-accent-focus-outline-offset: initial;
-  --rb-action-accent-focus-box-shadow: initial;
-}
-
 /* Selectable option card */
 :where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-option-card {
   position: relative;
@@ -16875,7 +17694,7 @@ const containerResponsiveThemeCss = `/*
 :where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-option-check svg {
   width: 0.75rem;
   height: 0.75rem;
-  color: var(--rb-reg-check-text, rgb(var(--tb-primaryText, var(--tb-primaryForeground, 255 255 255))));
+  color: var(--rb-reg-check-text, rgb(var(--tb-onPrimary, var(--tb-primaryForeground, 255 255 255))));
 }
 
 /* Step indicator */
@@ -16915,12 +17734,12 @@ const containerResponsiveThemeCss = `/*
 
 :where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-step-circle--active {
   background: var(--rb-reg-step-active, rgb(var(--tb-primary, 17 24 39)));
-  color: var(--rb-reg-step-text-active, rgb(var(--tb-primaryText, var(--tb-primaryForeground, 255 255 255))));
+  color: var(--rb-reg-step-text-active, rgb(var(--tb-onPrimary, var(--tb-primaryForeground, 255 255 255))));
 }
 
 :where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-step-circle--completed {
   background: var(--rb-reg-step-completed, rgb(var(--tb-success, 22 163 74)));
-  color: var(--rb-reg-step-text-active, rgb(var(--tb-primaryText, var(--tb-primaryForeground, 255 255 255))));
+  color: var(--rb-reg-step-text-active, rgb(var(--tb-onPrimary, var(--tb-primaryForeground, 255 255 255))));
 }
 
 :where(.theme-scope) :where([data-block="event-registration"], [data-block="appointment-booking"]) .rb-step-check {
@@ -17179,7 +17998,7 @@ const containerResponsiveThemeCss = `/*
   justify-content: center;
   border-radius: calc(var(--rb-block-radius) * 0.6);
   background: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, var(--tb-primaryForeground, 255 255 255)));
+  color: rgb(var(--tb-onPrimary, var(--tb-primaryForeground, 255 255 255)));
   padding: 0.625rem 1rem;
   font-size: 0.875rem;
   font-weight: 600;
@@ -19154,7 +19973,7 @@ const containerResponsiveThemeCss = `/*
 :where(.theme-scope) :where([data-block='event-registration']) .er-modal-btn {
   padding: 0.75rem 1.5rem;
   background: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primary-foreground, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
   border: none;
   border-radius: var(--rb-block-radius);
   font-weight: 500;
@@ -19202,7 +20021,7 @@ const containerResponsiveThemeCss = `/*
   border: 1px solid var(--er-border);
   border-radius: var(--rb-block-radius);
   background: var(--er-event-card-bg);
-  color: var(--er-on-surface);
+  /* Foreground and button context: theme-core/src/blocks/opaquePanels.ts. */
 }
 
 :where(.theme-scope)
@@ -19353,7 +20172,7 @@ const containerResponsiveThemeCss = `/*
   min-height: 0;
   overflow: hidden;
   background: rgb(var(--tb-background));
-  color: var(--er-on-surface);
+  /* Foreground and button context: theme-core/src/blocks/opaquePanels.ts. */
 }
 
 :where(.theme-scope)
@@ -20120,7 +20939,7 @@ const containerResponsiveThemeCss = `/*
   .event-category-btn--active {
   background-color: rgb(var(--tb-primary));
   border-color: rgb(var(--tb-primary));
-  color: var(--ec-event-solid-text);
+  color: rgb(var(--tb-onPrimary));
 }
 
 :where(.theme-scope)
@@ -20187,7 +21006,7 @@ const containerResponsiveThemeCss = `/*
   opacity: 1;
   background-color: rgb(var(--tb-primary));
   border-color: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
 }
 
 /* -----------------------------------------------------------------------------
@@ -20245,7 +21064,7 @@ const containerResponsiveThemeCss = `/*
   text-transform: uppercase;
   letter-spacing: 0.05em;
   background-color: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
   border-radius: var(--rb-button-radius);
 }
 
@@ -20287,7 +21106,8 @@ const containerResponsiveThemeCss = `/*
   border: 1px solid var(--ec-border-subtle);
   border-radius: var(--rb-block-radius);
   text-decoration: none;
-  color: inherit;
+  /* Paints its own surface: its foreground and button context come from the
+   * opaque-panel registry (theme-core/src/blocks/opaquePanels.ts). */
   transition: all var(--rb-block-transition) ease;
 }
 
@@ -20621,7 +21441,7 @@ const containerResponsiveThemeCss = `/*
   .event-timetable-day-tab--active {
   background-color: rgb(var(--tb-primary));
   border-color: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
 }
 
 :where(.theme-scope)
@@ -20687,7 +21507,7 @@ const containerResponsiveThemeCss = `/*
   padding: 0.125rem 0.375rem;
   border-radius: var(--rb-button-radius);
   background-color: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
   font-size: 0.625rem;
   font-weight: 700;
   text-transform: uppercase;
@@ -20743,7 +21563,6 @@ const containerResponsiveThemeCss = `/*
   border-left-width: 4px;
   border-radius: calc(var(--rb-block-radius) / 1.5);
   background-color: var(--ec-surface);
-  color: var(--ec-text);
   box-shadow: 0 1px 2px rgba(var(--tb-text), 0.08);
   cursor: pointer;
   font: inherit;
@@ -20916,7 +21735,6 @@ const containerResponsiveThemeCss = `/*
   border: 1px solid var(--ec-border);
   border-radius: var(--rb-block-radius);
   background-color: var(--ec-surface);
-  color: var(--ec-text);
   overflow: hidden;
 }
 
@@ -21866,7 +22684,7 @@ const containerResponsiveThemeCss = `/*
   justify-content: center;
   border-radius: calc(var(--rb-reg-radius, var(--rb-block-radius, 1rem)) * 0.6);
   background: rgb(var(--tb-primary, 17 24 39));
-  color: rgb(var(--tb-primaryText, var(--tb-primaryForeground, 255 255 255)));
+  color: rgb(var(--tb-onPrimary, var(--tb-primaryForeground, 255 255 255)));
   padding: 0.625rem 1rem;
   font-size: 0.875rem;
   font-weight: 600;
@@ -22304,7 +23122,7 @@ const containerResponsiveThemeCss = `/*
 
 :where(.theme-scope) .event-reset-filters-btn:hover {
   background-color: rgb(var(--tb-primary));
-  color: rgb(var(--tb-primaryText, 255 255 255));
+  color: rgb(var(--tb-onPrimary, 255 255 255));
 }
 
 :where(.theme-scope) .event-reset-filters-btn:focus-visible {
@@ -22662,14 +23480,8 @@ const containerResponsiveThemeCss = `/*
   border: 0;
   border-bottom: 1px solid color-mix(in oklab, currentColor, transparent 78%);
   border-radius: 0;
+  /* Boxless row: the opaque-panel registry hands the band's contract back. */
   background: transparent;
-  color: inherit;
-  --rb-surface-text-color: inherit;
-  --rb-surface-heading-color: inherit;
-  --rb-surface-link-color: inherit;
-  --rb-surface-link-hover-color: inherit;
-  --rb-surface-link-hover-decoration: inherit;
-  --rb-surface-supporting-color: inherit;
 }
 
 :where(.theme-scope) .shop--register .shop__card-header {
@@ -22761,14 +23573,8 @@ const containerResponsiveThemeCss = `/*
 
 /* Product card */
 :where(.theme-scope) .shop__card {
+  /* Foreground and button context: theme-core/src/blocks/opaquePanels.ts. */
   background: rgb(var(--tb-surface));
-  color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-text-color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-heading-color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-link-color: rgb(var(--tb-primary, var(--tb-text, 17 24 39)));
-  --rb-surface-link-hover-color: var(--rb-prose-link-hover-color, rgb(var(--tb-primary, var(--tb-text, 17 24 39))));
-  --rb-surface-link-hover-decoration: initial;
-  --rb-surface-supporting-color: rgb(var(--tb-mutedText, 100 116 139));
   border: 1px solid rgb(var(--tb-border));
   border-radius: var(--shop-card-radius);
   padding: 1.5rem;
@@ -22929,14 +23735,8 @@ const containerResponsiveThemeCss = `/*
   margin-bottom: 1.25rem;
   border: 1px solid rgb(var(--tb-border));
   border-radius: var(--shop-card-radius);
+  /* Foreground and button context: theme-core/src/blocks/opaquePanels.ts. */
   background: rgb(var(--tb-surface));
-  color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-text-color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-heading-color: rgb(var(--tb-text, 17 24 39));
-  --rb-surface-link-color: rgb(var(--tb-primary, var(--tb-text, 17 24 39)));
-  --rb-surface-link-hover-color: var(--rb-prose-link-hover-color, rgb(var(--tb-primary, var(--tb-text, 17 24 39))));
-  --rb-surface-link-hover-decoration: initial;
-  --rb-surface-supporting-color: rgb(var(--tb-mutedText, 100 116 139));
 }
 
 :where(.theme-scope) :where([data-block="shop"]) .rb-state-icon--success {
@@ -24879,8 +25679,11 @@ const containerResponsiveThemeCss = `/*
   border-radius: 9999px;
 }
 
+/* The callout is its own opaque surface: tones tint over the theme surface,
+ * not over whatever band the callout sits on, so its foreground and button
+ * context (theme-core/src/blocks/opaquePanels.ts) hold on any section. */
 :where(.theme-scope) .feedback-callout {
-  background: rgba(var(--tb-surface, 248 250 252), 0.92);
+  background: rgb(var(--tb-surface, 248 250 252));
   border-color: rgba(var(--tb-border, 226 232 240), 0.72);
   --rb-feedback-callout-bg-opacity: 0.1;
   --rb-feedback-callout-border-opacity: 0.24;
@@ -24888,25 +25691,33 @@ const containerResponsiveThemeCss = `/*
 
 :where(.theme-scope) .feedback-callout[data-feedback-tone="info"] {
   --rb-feedback-callout-bg-opacity: 0.08;
-  background: rgba(var(--tb-primary, 37 99 235), var(--rb-feedback-callout-bg-opacity));
+  background:
+    linear-gradient(rgba(var(--tb-primary, 37 99 235), var(--rb-feedback-callout-bg-opacity)), rgba(var(--tb-primary, 37 99 235), var(--rb-feedback-callout-bg-opacity))),
+    rgb(var(--tb-surface, 248 250 252));
   border-color: rgba(var(--tb-primary, 37 99 235), var(--rb-feedback-callout-border-opacity));
 }
 
 :where(.theme-scope) .feedback-callout[data-feedback-tone="success"] {
-  background: rgba(var(--tb-success, 34 197 94), var(--rb-feedback-callout-bg-opacity));
+  background:
+    linear-gradient(rgba(var(--tb-success, 34 197 94), var(--rb-feedback-callout-bg-opacity)), rgba(var(--tb-success, 34 197 94), var(--rb-feedback-callout-bg-opacity))),
+    rgb(var(--tb-surface, 248 250 252));
   border-color: rgba(var(--tb-success, 34 197 94), var(--rb-feedback-callout-border-opacity));
 }
 
 :where(.theme-scope) .feedback-callout[data-feedback-tone="warning"] {
   --rb-feedback-callout-bg-opacity: 0.12;
   --rb-feedback-callout-border-opacity: 0.28;
-  background: rgba(var(--tb-warning, 245 158 11), var(--rb-feedback-callout-bg-opacity));
+  background:
+    linear-gradient(rgba(var(--tb-warning, 245 158 11), var(--rb-feedback-callout-bg-opacity)), rgba(var(--tb-warning, 245 158 11), var(--rb-feedback-callout-bg-opacity))),
+    rgb(var(--tb-surface, 248 250 252));
   border-color: rgba(var(--tb-warning, 245 158 11), var(--rb-feedback-callout-border-opacity));
 }
 
 :where(.theme-scope) .feedback-callout[data-feedback-tone="error"] {
   --rb-feedback-callout-border-opacity: 0.26;
-  background: rgba(var(--tb-destructive, 239 68 68), var(--rb-feedback-callout-bg-opacity));
+  background:
+    linear-gradient(rgba(var(--tb-destructive, 239 68 68), var(--rb-feedback-callout-bg-opacity)), rgba(var(--tb-destructive, 239 68 68), var(--rb-feedback-callout-bg-opacity))),
+    rgb(var(--tb-surface, 248 250 252));
   border-color: rgba(var(--tb-destructive, 239 68 68), var(--rb-feedback-callout-border-opacity));
 }
 
@@ -25380,26 +26191,30 @@ const containerResponsiveThemeCss = `/*
   border: 1px solid rgb(var(--tb-text, 17 24 39) / 0.12);
   border-radius: 1rem;
   padding: 0.875rem 1rem;
-  background: rgb(var(--tb-surface, 255 255 255) / 0.92);
-  color: rgb(var(--tb-text, 17 24 39));
+  /* Opaque surface; foreground and button context come from the opaque-panel
+   * registry (theme-core/src/blocks/opaquePanels.ts). Tones tint over it. */
+  background: rgb(var(--tb-surface, 255 255 255));
 }
 
 :where(.theme-scope) [data-block="gifting"] .gifting-feedback[data-feedback-tone="success"] {
   border-color: rgba(var(--tb-success, 34 197 94), 0.3);
-  background: rgba(var(--tb-success, 34 197 94), 0.1);
-  color: rgb(var(--tb-success, 34 197 94));
+  background:
+    linear-gradient(rgba(var(--tb-success, 34 197 94), 0.1), rgba(var(--tb-success, 34 197 94), 0.1)),
+    rgb(var(--tb-surface, 255 255 255));
 }
 
 :where(.theme-scope) [data-block="gifting"] .gifting-feedback[data-feedback-tone="warning"] {
   border-color: rgba(var(--tb-warning, 245 158 11), 0.35);
-  background: rgba(var(--tb-warning, 245 158 11), 0.12);
-  color: rgb(var(--tb-warning, 245 158 11));
+  background:
+    linear-gradient(rgba(var(--tb-warning, 245 158 11), 0.12), rgba(var(--tb-warning, 245 158 11), 0.12)),
+    rgb(var(--tb-surface, 255 255 255));
 }
 
 :where(.theme-scope) [data-block="gifting"] .gifting-feedback[data-feedback-tone="error"] {
   border-color: rgba(var(--tb-destructive, 239 68 68), 0.3);
-  background: rgba(var(--tb-destructive, 239 68 68), 0.1);
-  color: rgb(var(--tb-destructive, 239 68 68));
+  background:
+    linear-gradient(rgba(var(--tb-destructive, 239 68 68), 0.1), rgba(var(--tb-destructive, 239 68 68), 0.1)),
+    rgb(var(--tb-surface, 255 255 255));
 }
 
 /* =============================================================================
@@ -25779,10 +26594,14 @@ const containerResponsiveThemeCss = `/*
  * These treatments retain the event list's content and structural layout.
  * Their contrast relationships come exclusively from the active semantic
  * section surface and named palette tokens.
+ *
+ * The treatment list is \`:is()\`, not \`:where()\`, so each rule outranks the card
+ * role (\`.card-role-x.card-role-x\`) the event card also carries: the rows must
+ * stay boxless whichever stylesheet the page loads last.
  * ============================================================================= */
 
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25794,12 +26613,12 @@ const containerResponsiveThemeCss = `/*
   border-radius: 0;
   background: transparent;
   box-shadow: none;
-  color: inherit;
+  /* Boxless row: the opaque-panel registry hands the band's contract back. */
 }
 
 /* Register treatments intentionally prioritise schedule data over imagery. */
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25810,7 +26629,7 @@ const containerResponsiveThemeCss = `/*
 }
 
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25822,7 +26641,7 @@ const containerResponsiveThemeCss = `/*
 }
 
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25834,7 +26653,7 @@ const containerResponsiveThemeCss = `/*
 }
 
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25846,7 +26665,7 @@ const containerResponsiveThemeCss = `/*
 }
 
 :where(.theme-scope)
-  :where(
+  :is(
     .rb-event-list-treatment-ruled-register,
     .rb-event-list-treatment-editorial-register,
     .rb-event-list-treatment-dense-index
@@ -25944,7 +26763,7 @@ const containerResponsiveThemeCss = `/*
 @container rb-site (min-width: 768px) {
 @scope ([data-rb-responsive-mode="container"]) to (:scope [data-rb-responsive-mode]) {
 :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -25954,7 +26773,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -25969,7 +26788,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -25980,7 +26799,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -25993,7 +26812,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -26005,7 +26824,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -26016,7 +26835,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -26024,7 +26843,7 @@ const containerResponsiveThemeCss = `/*
     .event-card.event-card.event-card--horizontal
     .card-content > .card-body,
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -26035,7 +26854,7 @@ const containerResponsiveThemeCss = `/*
   }
 
   :where(.theme-scope)
-    :where(
+    :is(
       .rb-event-list-treatment-ruled-register,
       .rb-event-list-treatment-editorial-register,
       .rb-event-list-treatment-dense-index
@@ -26086,13 +26905,7 @@ const containerResponsiveThemeCss = `/*
   padding: clamp(1.125rem, 2.5vw, 1.875rem);
   border-radius: calc(var(--rb-block-radius, 0.75rem) * 1.5);
   background: rgb(var(--tb-secondary));
-  color: rgb(var(--tb-onSecondary));
-  --rb-surface-text-color: rgb(var(--tb-onSecondary));
-  --rb-surface-heading-color: rgb(var(--tb-onSecondary));
-  --rb-surface-link-color: rgb(var(--tb-onSecondary));
-  --rb-surface-link-hover-color: rgb(var(--tb-onSecondary));
-  --rb-surface-link-hover-decoration: underline;
-  --rb-surface-supporting-color: rgb(var(--tb-onSecondary));
+  /* Foreground and button context: theme-core/src/blocks/opaquePanels.ts. */
 }
 
 :where(.theme-scope)
@@ -26217,16 +27030,8 @@ const containerResponsiveThemeCss = `/*
 }
 
 /* Diptych filled panel: a composition over the \`alternative\` role's surface.
-   The 18% supporting alpha is accepted CSS-side — see issue 1297 mapping-table. */
-:where(.theme-scope) .rb-feature-cards-grid--editorial-diptych .rb-feature-card[data-surface-role="panel"] {
-  color: rgb(var(--tb-onPrimary));
-  --rb-surface-text-color: rgb(var(--tb-onPrimary));
-  --rb-surface-heading-color: rgb(var(--tb-onPrimary));
-  --rb-surface-link-color: rgb(var(--tb-onPrimary));
-  --rb-surface-link-hover-color: rgb(var(--tb-onPrimary));
-  --rb-surface-link-hover-decoration: underline;
-  --rb-surface-supporting-color: color-mix(in oklab, rgb(var(--tb-onPrimary)), transparent 18%);
-}
+   It paints primary (below); its foreground and button context for that paint
+   come from theme-core/src/blocks/opaquePanels.ts. */
 
 :where(.theme-scope) .rb-feature-cards-grid--editorial-diptych .rb-feature-card[data-surface-role="panel"] > .rb-bg-surface {
   background: rgb(var(--tb-primary));
@@ -26729,6 +27534,51 @@ function ThemeScopeCore({ cssVars, buttonCss, headerCss, footerCss, cardCss, acc
 	});
 }
 //#endregion
+//#region ../theme-core/src/runtime/bridgeColourTokens.ts
+/**
+* The SDK theme bridge's colour tokens: RGB channel triplets as CSS vars, the
+* on-colours derived for them, and the same tokens as an opaque hex palette
+* for the contrast-checked generators (buttons, block panels).
+*/
+const RGB_CHANNELS_PATTERN = /^(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?$/;
+function hexToRgbChannels(hex) {
+	try {
+		const { r, g, b } = hexToRgb(hex);
+		return `${r} ${g} ${b}`;
+	} catch {
+		throw new Error(`[ThemeBridge] Invalid token value "${hex}": expected a valid hex colour, CSS var(), or RGB channel value.`);
+	}
+}
+function deriveConcreteBridgeOnTokens(tokens) {
+	return Object.fromEntries(Object.entries(tokens).flatMap(([name, value]) => {
+		if (!isOnColorBackgroundCandidateToken(name)) return [];
+		const hex = rgbChannelsToOpaqueHex(value);
+		const onToken = onColorTokenName(name);
+		return hex === null || tokens[onToken] !== void 0 ? [] : [[onToken, hexToRgbChannels(getTextColorForBackground(hex))]];
+	}));
+}
+function buildBridgeButtonPalette(tokens) {
+	return {
+		...Object.fromEntries(Object.entries({
+			...tokens,
+			...deriveConcreteBridgeOnTokens(tokens)
+		}).flatMap(([name, value]) => {
+			const hex = rgbChannelsToOpaqueHex(value);
+			return hex === null ? [] : [[name, hex]];
+		})),
+		meta: { mode: "light" }
+	};
+}
+function rgbChannelsToOpaqueHex(value) {
+	const match = value.match(RGB_CHANNELS_PATTERN);
+	if (!match || match[4] !== void 0) return null;
+	return `#${[
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+}
+//#endregion
 //#region ../theme-core/src/buttons/core.ts
 const CORNER_RADIUS_MAP$1 = {
 	square: "0",
@@ -27063,7 +27913,6 @@ const BRIDGE_DEFAULT_TOKENS = {
 };
 const TOKEN_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9-]*$/;
 const CSS_VARIABLE_REFERENCE_PATTERN = /^var\(\s*--[a-zA-Z][a-zA-Z0-9-]*(?:\s*,\s*[^{};<>]+)?\s*\)$/;
-const RGB_CHANNELS_PATTERN = /^(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})(?:\s*\/\s*(0|1|0?\.\d+|\d{1,3}%))?$/;
 const CSS_DECLARATION_PROPERTY_PATTERN = /^(?:-[a-zA-Z][a-zA-Z0-9-]*|[a-zA-Z][a-zA-Z0-9-]*|--[a-zA-Z][a-zA-Z0-9-]*)$/;
 const UNSAFE_CSS_MARKUP_PATTERN = /[{}<>]|<\/|<script/i;
 const EXTERNAL_URL_PATTERN = /url\s*\(\s*['"]?(?:https?:|\/\/)/i;
@@ -27149,14 +27998,6 @@ const TOKEN_ALIASES = [
 		target: "info"
 	}
 ];
-function hexToRgbChannels(hex) {
-	try {
-		const { r, g, b } = hexToRgb(hex);
-		return `${r} ${g} ${b}`;
-	} catch {
-		throw new Error(`[ThemeBridge] Invalid token value "${hex}": expected a valid hex colour, CSS var(), or RGB channel value.`);
-	}
-}
 function normalizeTokenValue(value) {
 	const trimmedValue = value.trim();
 	if (!isSafeBridgeTokenValue(trimmedValue)) throw new Error(`[ThemeBridge] Invalid token value "${value}": expected a hex colour, CSS var(), or RGB channel value.`);
@@ -27174,7 +28015,13 @@ function buildThemeBridgeRuntime(config) {
 		themeId,
 		cssVars,
 		buttonCss: shouldGenerateComponent(config.components?.buttons) ? generateButtonsCss(config, corners, config.shadows ?? "medium") : void 0,
-		cardCss: generateCardsCss(config, corners, config.shadows ?? "medium"),
+		cardCss: `${generateCardsCss(config, corners, config.shadows ?? "medium")}\n\n${generateOpaquePanelCss({
+			themeId,
+			surface: {
+				palette: buildBridgeButtonPalette(resolveBridgeTokens(validatedConfig.tokens)),
+				buttonSystem: void 0
+			}
+		})}`,
 		inputCss: shouldGenerateComponent(config.components?.inputs) ? generateInputsCss(corners, config.shadows ?? "medium") : void 0,
 		statusCss: generateStatusCss({
 			themeId,
@@ -27336,41 +28183,6 @@ function resolveBridgeTokens(tokens) {
 	for (const [name, value] of Object.entries(BRIDGE_DEFAULT_TOKENS)) if (!isPresentTokenValue(resolved[name])) resolved[name] = value;
 	return resolved;
 }
-function deriveConcreteBridgeOnTokens(tokens) {
-	const derived = {};
-	for (const [name, value] of Object.entries(tokens)) {
-		if (!isOnColorBackgroundCandidateToken(name)) continue;
-		const hex = rgbChannelsToOpaqueHex(value);
-		if (hex === null) continue;
-		const onToken = onColorTokenName(name);
-		if (tokens[onToken] === void 0) derived[onToken] = hexToRgbChannels(getTextColorForBackground(hex));
-	}
-	return derived;
-}
-function buildBridgeButtonPalette(tokens) {
-	const palette = {};
-	for (const [name, value] of Object.entries(tokens)) {
-		const hex = rgbChannelsToOpaqueHex(value);
-		if (hex !== null) palette[name] = hex;
-	}
-	for (const [name, value] of Object.entries(deriveConcreteBridgeOnTokens(tokens))) {
-		const hex = rgbChannelsToOpaqueHex(value);
-		if (hex !== null) palette[name] = hex;
-	}
-	return {
-		...palette,
-		meta: { mode: "light" }
-	};
-}
-function rgbChannelsToOpaqueHex(value) {
-	const match = value.match(RGB_CHANNELS_PATTERN);
-	if (!match || match[4] !== void 0) return null;
-	return `#${[
-		Number(match[1]),
-		Number(match[2]),
-		Number(match[3])
-	].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
-}
 function isPresentTokenValue(value) {
 	return typeof value === "string" && value.trim().length > 0;
 }