@riverbankcms/sdk 0.130.0 → 0.132.0

package/dist/_dts/theme-core/src/site-styles/types.d.ts

@@ -1,4 +1,5 @@
 import type { Theme } from '../schema';
+import type { CardRole } from '../cards';
 export type Brand<T, TBrand extends string> = T & {
     readonly __brand: TBrand;
 };
@@ -99,7 +100,6 @@ export type DesignResolutionPolicy = 'generated' | 'user' | 'admin' | 'sdk';
 export type DesignIssueSeverity = 'blocking' | 'repairable' | 'advisory';
 export declare function designIssueSeverityForPolicy(policy: DesignResolutionPolicy): DesignIssueSeverity;
 export type SiteStyleSurfaceIntent = 'base' | 'muted-band' | 'accent-band' | 'brand-depth-band' | 'hero-image';
-export type SiteStyleItemSurfaceIntent = 'none' | 'default' | 'flat' | 'outlined' | 'raised' | 'inset' | 'editorial' | 'color-blocked';
 export type SiteStyleSectionTransitionIntent = 'none' | 'soft-fade-short' | 'soft-fade-long' | 'soft-fade-expansive' | 'wave-edge' | 'wave-edge-balanced' | 'wave-edge-gentle' | 'wave-edge-bold' | 'wave-edge-drift' | 'angle-edge' | 'angle-edge-subtle' | 'angle-edge-steep';
 export type SiteStyleEmphasis = 'low' | 'medium' | 'high';
 export type SectionHeightIntent = 'default' | 'banner' | 'hero' | 'immersive';
@@ -200,7 +200,6 @@ export type ImageSurfaceTreatment = Readonly<{
     intensity?: ImageSurfaceTreatmentIntensity;
 }>;
 export type ImageSurfaceTreatmentKind = ImageSurfaceTreatment['kind'];
-export type TestimonialCardTreatment = 'default' | 'statement' | 'non-carded' | 'accent-quote' | 'editorial-serif-quote';
 export declare const tileTreatmentValues: readonly ["default", "quiet", "brand-depth"];
 export type TileTreatment = (typeof tileTreatmentValues)[number];
 export declare const eventListTreatmentValues: readonly ["plain", "lined-panel", "ruled-register", "editorial-register", "dense-index"];
@@ -209,6 +208,14 @@ export declare const introCompositionTreatmentValues: readonly ["editorial-state
 export type IntroCompositionTreatment = (typeof introCompositionTreatmentValues)[number];
 export declare const featureCardCompositionTreatmentValues: readonly ["asymmetric-emphasis", "framed-programme"];
 export type FeatureCardCompositionTreatment = (typeof featureCardCompositionTreatmentValues)[number];
+export declare const testimonialsCompositionTreatmentValues: readonly ["open-editorial", "evergreen-lead", "room-and-response", "open-floor"];
+export type TestimonialsCompositionTreatment = (typeof testimonialsCompositionTreatmentValues)[number];
+/**
+ * How an offerings preview arranges its groups. Structure only — the group
+ * card surface is the Look's `cardRole` and the site style's card system.
+ */
+export declare const offeringsPreviewCompositionTreatmentValues: readonly ["paired-feature-cards", "open-editorial-columns", "joined-programme-panel"];
+export type OfferingsPreviewCompositionTreatment = (typeof offeringsPreviewCompositionTreatmentValues)[number];
 /**
  * A closed description of structural presentation selected by a Look.
  * Concrete spacing, radii, colour, and shadow remain site-style concerns.
@@ -219,6 +226,12 @@ export type BlockCompositionIntent = Readonly<{
 }> | Readonly<{
     kind: 'feature-cards';
     treatment: FeatureCardCompositionTreatment;
+}> | Readonly<{
+    kind: 'testimonials';
+    treatment: TestimonialsCompositionTreatment;
+}> | Readonly<{
+    kind: 'offerings-preview';
+    treatment: OfferingsPreviewCompositionTreatment;
 }>;
 export type BlockCompositionCapability = Readonly<{
     kind: 'none';
@@ -228,6 +241,12 @@ export type BlockCompositionCapability = Readonly<{
 }> | Readonly<{
     kind: 'feature-cards';
     treatments: NonEmptyReadonlyArray<FeatureCardCompositionTreatment>;
+}> | Readonly<{
+    kind: 'testimonials';
+    treatments: NonEmptyReadonlyArray<TestimonialsCompositionTreatment>;
+}> | Readonly<{
+    kind: 'offerings-preview';
+    treatments: NonEmptyReadonlyArray<OfferingsPreviewCompositionTreatment>;
 }>;
 export declare const eyebrowTreatmentValues: readonly ["plain", "accent", "pill", "accent-pill", "pill-bounce", "accent-pill-bounce"];
 export type EyebrowTreatment = (typeof eyebrowTreatmentValues)[number];
@@ -283,16 +302,21 @@ export type GeneratedFlushPanelFrameIntent = Readonly<{
 export type GeneratedContentFrameIntent = PlainFrameIntent | GeneratedPanelFrameIntent | GeneratedFlushPanelFrameIntent;
 export type UserContentFrameIntent = ContentFrameIntent;
 export type AdvancedContentFrameIntent = ContentFrameIntent | AdvancedDetachedDesignValue;
-export type GeneratedItemSurfaceIntent = Extract<SiteStyleItemSurfaceIntent, 'none' | 'default' | 'flat' | 'outlined' | 'raised' | 'inset' | 'editorial' | 'color-blocked'>;
-export type UserItemSurfaceIntent = SiteStyleItemSurfaceIntent;
-export type AdvancedItemSurfaceIntent = SiteStyleItemSurfaceIntent | AdvancedDetachedDesignValue;
+/**
+ * Card roles are a closed, global vocabulary — every source may express the
+ * whole set, unlike surfaces or frames where generation is deliberately
+ * narrower than the user catalog.
+ */
+export type GeneratedCardRoleIntent = CardRole;
+export type UserCardRoleIntent = CardRole;
+export type AdvancedCardRoleIntent = CardRole | AdvancedDetachedDesignValue;
 export type GeneratedSectionTransitionIntent = Extract<SiteStyleSectionTransitionIntent, 'none' | 'soft-fade-short' | 'soft-fade-long'>;
 export type UserSectionTransitionIntent = SiteStyleSectionTransitionIntent;
 export type AdvancedSectionTransitionIntent = SiteStyleSectionTransitionIntent | AdvancedDetachedDesignValue;
 export type GeneratedBlockDesignIntent = Readonly<{
     sectionSurface: GeneratedDesignChoice<GeneratedSurfaceIntent>;
     contentFrame: GeneratedDesignChoice<GeneratedContentFrameIntent>;
-    itemSurface: GeneratedDesignChoice<GeneratedItemSurfaceIntent>;
+    cardRole: GeneratedDesignChoice<GeneratedCardRoleIntent>;
     transitionAfter: GeneratedDesignChoice<GeneratedSectionTransitionIntent>;
     emphasis: GeneratedDesignChoice<SiteStyleEmphasis>;
 }>;
@@ -319,14 +343,14 @@ export type GeneratedPageDesignIntent<TBlockId extends string = string> = Readon
 export type UserBlockDesignIntent = Readonly<{
     sectionSurface: UserDesignChoice<UserSurfaceIntent>;
     contentFrame: UserDesignChoice<UserContentFrameIntent>;
-    itemSurface: UserDesignChoice<UserItemSurfaceIntent>;
+    cardRole: UserDesignChoice<UserCardRoleIntent>;
     transitionAfter: UserDesignChoice<UserSectionTransitionIntent>;
     emphasis: UserDesignChoice<SiteStyleEmphasis>;
 }>;
 export type AdvancedBlockDesignIntent = Readonly<{
     sectionSurface: AdvancedDesignChoice<AdvancedSurfaceIntent>;
     contentFrame: AdvancedDesignChoice<AdvancedContentFrameIntent>;
-    itemSurface: AdvancedDesignChoice<AdvancedItemSurfaceIntent>;
+    cardRole: AdvancedDesignChoice<AdvancedCardRoleIntent>;
     transitionAfter: AdvancedDesignChoice<AdvancedSectionTransitionIntent>;
     emphasis: AdvancedDesignChoice<SiteStyleEmphasis>;
 }>;
@@ -383,7 +407,6 @@ export type DesignSystemTemplate = Readonly<{
     compositionBudget: CompositionBudget;
     supportedSectionSurfaces: readonly SiteStyleSurfaceIntent[];
     supportedContentFrames: readonly FrameKind[];
-    supportedItemSurfaces: readonly SiteStyleItemSurfaceIntent[];
     supportedTransitions: readonly SiteStyleSectionTransitionIntent[];
 }>;
 export type SiteTheme = Readonly<{
@@ -407,7 +430,12 @@ export type BlockDesignPlan<TBlockId extends string = DesignBlockId, TPurpose ex
     appearancePresetId?: AppearancePresetId;
     sectionSurface: SiteStyleSurfaceIntent;
     contentFrame: ContentFrameIntent;
-    itemSurface: SiteStyleItemSurfaceIntent;
+    /**
+     * Which card role this block asks the site style for. Absent means the same
+     * as `none`: the Look asks for no site-style card, and the block's own
+     * composition governs what the item looks like.
+     */
+    cardRole?: CardRole;
     transitionAfter: SiteStyleSectionTransitionIntent;
     emphasis: SiteStyleEmphasis;
     sectionHeight?: SectionHeightIntent;
@@ -416,7 +444,6 @@ export type BlockDesignPlan<TBlockId extends string = DesignBlockId, TPurpose ex
     heroTypographyScale?: HeroTypographyScaleIntent;
     imageSurfaceTreatment?: ImageSurfaceTreatment;
     imageSurfaceMotion?: ImageSurfaceMotion;
-    testimonialCardTreatment?: TestimonialCardTreatment;
     tileTreatment?: TileTreatment;
     eventListTreatment?: EventListTreatment;
     eyebrowTreatment?: EyebrowTreatment;
@@ -427,12 +454,15 @@ export type ResolvedBlockDesignPlan<TBlockId extends string = DesignBlockId, TPu
     appliedSectionSurface: SiteStyleSurfaceIntent;
     appliedContentFrame: ContentFrameIntent;
     appliedTransitionAfter: SiteStyleSectionTransitionIntent;
-    appliedItemSurface: SiteStyleItemSurfaceIntent;
+    /**
+     * The card role after capability gating. `null` (or absent) means no
+     * site-style card is applied; the block renders its own composition.
+     */
+    appliedCardRole?: CardRole | null;
     appliedSectionHeight: SectionHeightIntent;
     appliedHeroLegibility: HeroLegibilityStrategy;
     appliedImageSurfaceTreatment: ImageSurfaceTreatment;
     appliedImageSurfaceMotion: ImageSurfaceMotion;
-    appliedTestimonialCardTreatment: TestimonialCardTreatment;
     appliedTileTreatment: TileTreatment;
     appliedEventListTreatment: EventListTreatment;
     appliedEyebrowTreatment: EyebrowTreatment;
@@ -454,6 +484,14 @@ export type HeadingDecorationCapability = Readonly<{
     kind: 'supported';
     families: NonEmptyReadonlyArray<VisibleHeadingDecorationFamily>;
 }>;
+/**
+ * Whether a block can carry a card surface, and by which path.
+ *
+ * - `supported` — the block renders the card-role path: a Look's `cardRole`
+ *   compiles into `_cardStyles.role` and the site style owns the appearance.
+ * - `unsupported` — the block has no card surface at all.
+ */
+export type CardRoleCapability = 'supported' | 'unsupported';
 export type DesignedBlockDesignCapabilityInput = Readonly<{
     /** Looks are optional composition presets, not the baseline block design. */
     looks?: 'supported';
@@ -461,11 +499,10 @@ export type DesignedBlockDesignCapabilityInput = Readonly<{
     /** Rich backgrounds require an explicit block-level legibility contract. */
     richBackgrounds?: 'supported';
     contentFrames: FrameCapability;
-    itemSurfaces: 'supported' | 'unsupported';
+    cardRoles: CardRoleCapability;
     sectionHeights?: NonEmptyReadonlyArray<SectionHeightIntent>;
     imageSurfaceTreatments?: NonEmptyReadonlyArray<ImageSurfaceTreatmentKind>;
     imageSurfaceMotions?: NonEmptyReadonlyArray<ImageSurfaceMotion>;
-    testimonialCardTreatments?: NonEmptyReadonlyArray<TestimonialCardTreatment>;
     tileTreatments?: NonEmptyReadonlyArray<TileTreatment>;
     eventListTreatments?: NonEmptyReadonlyArray<EventListTreatment>;
     eyebrowTreatments?: NonEmptyReadonlyArray<EyebrowTreatment>;
@@ -482,11 +519,10 @@ export type DesignedBlockDesignCapability = Readonly<{
     sectionSurfaces: 'supported' | 'unsupported';
     richBackgrounds?: 'supported';
     contentFrames: FrameCapability;
-    itemSurfaces: 'supported' | 'unsupported';
+    cardRoles: CardRoleCapability;
     sectionHeights: NonEmptyReadonlyArray<SectionHeightIntent>;
     imageSurfaceTreatments: NonEmptyReadonlyArray<ImageSurfaceTreatmentKind>;
     imageSurfaceMotions: NonEmptyReadonlyArray<ImageSurfaceMotion>;
-    testimonialCardTreatments: NonEmptyReadonlyArray<TestimonialCardTreatment>;
     tileTreatments: NonEmptyReadonlyArray<TileTreatment>;
     eventListTreatments: NonEmptyReadonlyArray<EventListTreatment>;
     eyebrowTreatments: NonEmptyReadonlyArray<EyebrowTreatment>;
@@ -504,7 +540,7 @@ export type BlockDesignCapability = DesignedBlockDesignCapability | NoBlockDesig
 export type BlockDesignCapabilityMap = Readonly<Partial<Record<string, BlockDesignCapability>>>;
 export declare function defineBlockDesignCapability<const TCapability extends DesignedBlockDesignCapabilityInput>(capability: NoExtraKeys<TCapability, DesignedBlockDesignCapabilityInput>): DesignedBlockDesignCapability;
 export declare function defineNoBlockDesignCapability(reason: UnsupportedBlockDesignCapabilityReason): NoBlockDesignCapability;
-export type DesignRepairAction = 'fallback-block-design' | 'fallback-section-surface' | 'fallback-content-frame' | 'fallback-item-surface' | 'fallback-section-height' | 'fallback-image-surface-treatment' | 'fallback-image-surface-motion' | 'fallback-testimonial-card-treatment' | 'fallback-tile-treatment' | 'fallback-event-list-treatment' | 'fallback-eyebrow-treatment' | 'fallback-accordion-icon-treatment' | 'remove-composition' | 'remove-hero-legibility' | 'remove-transition' | 'fallback-hero-legibility' | 'reduce-accent-density' | 'reduce-panel-density' | 'reduce-transition-mix' | 'reduce-primary-ctas' | 'reduce-media-density' | 'reduce-decorative-repetition';
+export type DesignRepairAction = 'fallback-block-design' | 'fallback-section-surface' | 'fallback-content-frame' | 'fallback-card-role' | 'fallback-section-height' | 'fallback-image-surface-treatment' | 'fallback-image-surface-motion' | 'fallback-tile-treatment' | 'fallback-event-list-treatment' | 'fallback-eyebrow-treatment' | 'fallback-accordion-icon-treatment' | 'remove-composition' | 'remove-hero-legibility' | 'remove-transition' | 'fallback-hero-legibility' | 'reduce-accent-density' | 'reduce-panel-density' | 'reduce-transition-mix' | 'reduce-primary-ctas' | 'reduce-media-density' | 'reduce-decorative-repetition';
 export type UnsupportedSectionSurfaceIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
     kind: 'unsupported-section-surface';
     blockId: TBlockId;
@@ -527,16 +563,17 @@ export type UnsupportedContentFrameIssue<TBlockId extends string = DesignBlockId
     severity: DesignIssueSeverity;
     allowedRepairActions: readonly ['fallback-content-frame'];
 }>;
-export type UnsupportedItemSurfaceIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
-    kind: 'unsupported-item-surface';
+export type UnsupportedCardRoleIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
+    kind: 'unsupported-card-role';
     blockId: TBlockId;
     blockKind: string;
     purpose: TPurpose;
-    requested: SiteStyleItemSurfaceIntent;
-    fallback: SiteStyleItemSurfaceIntent;
+    /** The card role the block asked its site style for. */
+    requested: CardRole;
+    fallback: 'none';
     policy: DesignResolutionPolicy;
     severity: DesignIssueSeverity;
-    allowedRepairActions: readonly ['fallback-item-surface'];
+    allowedRepairActions: readonly ['fallback-card-role'];
 }>;
 export type UnsupportedSectionHeightIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
     kind: 'unsupported-section-height';
@@ -573,17 +610,6 @@ export type UnsupportedImageSurfaceMotionIssue<TBlockId extends string = DesignB
     severity: DesignIssueSeverity;
     allowedRepairActions: readonly ['fallback-image-surface-motion'];
 }>;
-export type UnsupportedTestimonialCardTreatmentIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
-    kind: 'unsupported-testimonial-card-treatment';
-    blockId: TBlockId;
-    blockKind: string;
-    purpose: TPurpose;
-    requested: TestimonialCardTreatment;
-    fallback: 'default';
-    policy: DesignResolutionPolicy;
-    severity: DesignIssueSeverity;
-    allowedRepairActions: readonly ['fallback-testimonial-card-treatment'];
-}>;
 export type UnsupportedTileTreatmentIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
     kind: 'unsupported-tile-treatment';
     blockId: TBlockId;
@@ -677,7 +703,7 @@ export type HeroLegibilityOverriddenByImageSurfaceTreatmentIssue<TBlockId extend
 export type BlockDesignCapabilityRequest = Readonly<{
     sectionSurface: SiteStyleSurfaceIntent;
     contentFrame: ContentFrameIntent;
-    itemSurface: SiteStyleItemSurfaceIntent;
+    cardRole?: CardRole;
     transitionAfter: SiteStyleSectionTransitionIntent;
     sectionHeight?: SectionHeightIntent;
     heroLegibility?: HeroLegibilityStrategy;
@@ -685,7 +711,6 @@ export type BlockDesignCapabilityRequest = Readonly<{
     heroTypographyScale?: HeroTypographyScaleIntent;
     imageSurfaceTreatment?: ImageSurfaceTreatment;
     imageSurfaceMotion?: ImageSurfaceMotion;
-    testimonialCardTreatment?: TestimonialCardTreatment;
     tileTreatment?: TileTreatment;
     eventListTreatment?: EventListTreatment;
     eyebrowTreatment?: EyebrowTreatment;
@@ -695,7 +720,6 @@ export type BlockDesignCapabilityRequest = Readonly<{
 export type BlockDesignCapabilityFallback = Readonly<{
     sectionSurface: 'base';
     contentFrame: PlainFrameIntent;
-    itemSurface: 'none';
     transitionAfter: 'none';
     sectionHeight: 'default';
     heroLegibility: 'none';
@@ -703,7 +727,6 @@ export type BlockDesignCapabilityFallback = Readonly<{
         kind: 'none';
     }>;
     imageSurfaceMotion: 'static';
-    testimonialCardTreatment: 'default';
     tileTreatment: 'default';
     eventListTreatment: 'plain';
     eyebrowTreatment: 'plain';
@@ -755,7 +778,7 @@ export type HeroImageWithoutLegibilityIssue<TBlockId extends string = DesignBloc
     severity: DesignIssueSeverity;
     allowedRepairActions: readonly ['fallback-hero-legibility'];
 }>;
-export type DesignResolutionIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = UnsupportedSectionSurfaceIssue<TBlockId, TPurpose> | UnsupportedContentFrameIssue<TBlockId, TPurpose> | UnsupportedItemSurfaceIssue<TBlockId, TPurpose> | UnsupportedSectionHeightIssue<TBlockId, TPurpose> | UnsupportedImageSurfaceTreatmentIssue<TBlockId, TPurpose> | UnsupportedImageSurfaceMotionIssue<TBlockId, TPurpose> | UnsupportedTestimonialCardTreatmentIssue<TBlockId, TPurpose> | UnsupportedTileTreatmentIssue<TBlockId, TPurpose> | UnsupportedEventListTreatmentIssue<TBlockId, TPurpose> | UnsupportedEyebrowTreatmentIssue<TBlockId, TPurpose> | UnsupportedAccordionIconTreatmentIssue<TBlockId, TPurpose> | UnsupportedBlockCompositionIssue<TBlockId, TPurpose> | ImageSurfaceTreatmentWithoutImageSurfaceIssue<TBlockId, TPurpose> | ImageSurfaceMotionWithoutImageSurfaceIssue<TBlockId, TPurpose> | HeroLegibilityOverriddenByImageSurfaceTreatmentIssue<TBlockId, TPurpose> | MissingBlockDesignCapabilityIssue<TBlockId, TPurpose> | UnsupportedBlockDesignCapabilityIssue<TBlockId, TPurpose> | RemovedTransitionForFlushFrameIssue<TBlockId, TPurpose> | HeroImageWithoutLegibilityIssue<TBlockId, TPurpose>;
+export type DesignResolutionIssue<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = UnsupportedSectionSurfaceIssue<TBlockId, TPurpose> | UnsupportedContentFrameIssue<TBlockId, TPurpose> | UnsupportedCardRoleIssue<TBlockId, TPurpose> | UnsupportedSectionHeightIssue<TBlockId, TPurpose> | UnsupportedImageSurfaceTreatmentIssue<TBlockId, TPurpose> | UnsupportedImageSurfaceMotionIssue<TBlockId, TPurpose> | UnsupportedTileTreatmentIssue<TBlockId, TPurpose> | UnsupportedEventListTreatmentIssue<TBlockId, TPurpose> | UnsupportedEyebrowTreatmentIssue<TBlockId, TPurpose> | UnsupportedAccordionIconTreatmentIssue<TBlockId, TPurpose> | UnsupportedBlockCompositionIssue<TBlockId, TPurpose> | ImageSurfaceTreatmentWithoutImageSurfaceIssue<TBlockId, TPurpose> | ImageSurfaceMotionWithoutImageSurfaceIssue<TBlockId, TPurpose> | HeroLegibilityOverriddenByImageSurfaceTreatmentIssue<TBlockId, TPurpose> | MissingBlockDesignCapabilityIssue<TBlockId, TPurpose> | UnsupportedBlockDesignCapabilityIssue<TBlockId, TPurpose> | RemovedTransitionForFlushFrameIssue<TBlockId, TPurpose> | HeroImageWithoutLegibilityIssue<TBlockId, TPurpose>;
 export type DesignRepairResultForIssue<TIssue extends DesignResolutionIssue<string, string>> = {
     [TKind in TIssue['kind']]: Readonly<{
         kind: TKind extends 'removed-transition-for-flush-frame' ? 'repaired' : 'fallbackApplied';

package/dist/_dts/theme-core/src/siteChromePlanning.d.ts

@@ -1,21 +1,21 @@
-import type { HeaderPositioning, Theme } from "./schema";
-import { type SiteChromePlacementPlan } from "./siteChromePlacement";
-import { type SiteOverlayHeaderClearancePlan } from "./siteChromeOverlayClearance";
-export type SiteTopShellBehavior = "normal-flow" | "shared-sticky-shell" | "banner-above-overlay-header";
+import type { HeaderPositioning, Theme } from './schema';
+import { type SiteChromePlacementPlan } from './siteChromePlacement';
+import { type SiteOverlayHeaderClearancePlan } from './siteChromeOverlayClearance';
+export type SiteTopShellBehavior = 'normal-flow' | 'shared-sticky-shell' | 'banner-above-overlay-header';
 export type SiteTopShellPlan = Readonly<{
-    behavior: "normal-flow";
+    behavior: 'normal-flow';
     contentStartsUnderHeader: boolean;
     requiresHeaderOffset: false;
 }> | Readonly<{
-    behavior: "shared-sticky-shell";
+    behavior: 'shared-sticky-shell';
     contentStartsUnderHeader: false;
     requiresHeaderOffset: false;
 }> | Readonly<{
-    behavior: "banner-above-overlay-header";
+    behavior: 'banner-above-overlay-header';
     contentStartsUnderHeader: true;
     requiresHeaderOffset: true;
 }>;
-export type SiteDocumentLayoutMode = "normal-flow" | "header-overlay";
+export type SiteDocumentLayoutMode = 'normal-flow' | 'header-overlay';
 export type SiteDocumentPlan = Readonly<{
     placement: SiteChromePlacementPlan;
     topShell: SiteTopShellPlan;
@@ -24,7 +24,7 @@ export type SiteDocumentPlan = Readonly<{
 }>;
 export type SiteDocumentPlanInput = Readonly<{
     headerPositioning: HeaderPositioning;
-    headerVariant?: Theme["header"]["variant"] | null;
+    headerVariant?: Theme['header']['variant'] | null;
     hasVisibleBanner: boolean;
     hasVisibleHeader?: boolean;
 }>;

package/dist/_dts/theme-core/src/status/generateStatusCss.d.ts

@@ -16,6 +16,7 @@ export interface GenerateStatusCssParams {
  * Creates scoped CSS classes for:
  * - .status-error, .status-success, .status-warning, .status-info, .status-muted (text colors)
  * - .alert, .alert-error, .alert-success, .alert-warning, .alert-info (styled containers)
+ * - .feedback-note, .feedback-note-* (the "field-note" feedback treatment)
  * - .required-marker (required field indicator)
  * - .button-link (text-styled button)
  *

package/dist/_dts/theme-core/src/surfaces/index.d.ts

@@ -1,2 +1,3 @@
 export * from './foregroundContract';
 export * from './foregroundRoles';
+export * from './resolveSurfaceForeground';

package/dist/_dts/theme-core/src/surfaces/resolveSurfaceForeground.d.ts

@@ -0,0 +1,39 @@
+import { type ThemeColorToken } from '../tokens/themeColorTokens';
+import type { SurfaceForegroundRole } from './foregroundRoles';
+export { ORDINARY_TEXT_MIN_CONTRAST_RATIO } from '../palette/utils/contrast';
+export type ResolvedSurfaceForegroundTokens = Readonly<Record<SurfaceForegroundRole, ThemeColorToken>>;
+export type ResolvedSurfaceForeground = Readonly<{
+    kind: 'known';
+    roles: ResolvedSurfaceForegroundTokens;
+}> | Readonly<{
+    kind: 'unknown';
+}>;
+export type SurfaceForegroundBackground = Readonly<{
+    type: 'color' | 'gradient' | 'image' | 'video';
+    color?: string | null;
+    textColor?: string | null;
+    headingColor?: string | null;
+    linkColor?: string | null;
+    supportingColor?: string | null;
+}>;
+export type SurfaceForegroundCandidates = Readonly<{
+    text?: string | null;
+    heading?: string | null;
+    link?: string | null;
+    supporting?: string | null;
+}>;
+export type SurfaceForegroundResolutionOptions = Readonly<{
+    /** Opaque surface underneath translucent colour backgrounds. */
+    compositeBase?: string | null;
+}>;
+type Palette = Readonly<Record<string, string>>;
+/**
+ * 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.
+ */
+export declare function resolveSurfaceForeground(background: SurfaceForegroundBackground | null, palette: Palette, candidates?: SurfaceForegroundCandidates, options?: SurfaceForegroundResolutionOptions): ResolvedSurfaceForeground;

package/dist/_dts/ui/src/navigation-tabs.d.ts

@@ -1,13 +1,16 @@
 export type NavigationTab = {
     id: string;
     label: React.ReactNode;
+    /** Stable automation hook owned by the feature composing this tab. */
+    testId?: string;
     badge?: number;
     content?: React.ReactNode;
 };
 export type NavigationTabsVariant = 'default';
 export type NavigationTabsProps = {
     tabs: NavigationTab[];
-    activeTab?: string;
+    /** `null` intentionally renders the navigation with no selected tab. */
+    activeTab?: string | null;
     onTabChange?: (tabId: string) => void;
     variant?: NavigationTabsVariant;
     urlParam?: string;
@@ -34,4 +37,4 @@ export type NavigationTabPanelsProps = {
  * Optional companion component for rendering tab content panels.
  * Use this when tabs control content visibility (not just state).
  */
-export declare function NavigationTabPanels({ tabs, activeTab, className }: NavigationTabPanelsProps): import("react").JSX.Element;
+export declare function NavigationTabPanels({ tabs, activeTab, className, }: NavigationTabPanelsProps): import("react").JSX.Element;

package/dist/client/{DiscountCodeDisclosure-Ur-Xx1U_.mjs → DiscountCodeDisclosure-DO7llLxm.mjs}

@@ -1,5 +1,5 @@
 "use client";
-import { Z as themeButtonClassName } from "./propsDecoder-CAZdhwjs.mjs";
+import { et as themeButtonClassName } from "./propsDecoder-BxmqPKdP.mjs";
 import { useId } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/api/types/discounts.ts
@@ -20,17 +20,17 @@ function getAutoAppliedDiscountPreview(availability) {
 //#endregion
 //#region ../blocks/src/system/runtime/shared/components/DiscountCodeDisclosure.tsx
 const BLOCK_DISCOUNT_CODE_DISCLOSURE_CLASSES = {
-	"course-registration": {
-		root: "cr-discount",
-		toggle: "cr-discount__toggle",
-		form: "cr-discount__form",
-		label: "cr-discount__label",
-		row: "cr-discount__row",
-		input: "cr-discount__input",
-		apply: "cr-discount__apply",
-		remove: "cr-discount__remove",
-		hint: "cr-discount__hint",
-		feedback: "cr-discount__feedback"
+	"whole-series-registration": {
+		root: "er-whole-series-discount",
+		toggle: "er-whole-series-discount__toggle",
+		form: "er-whole-series-discount__form",
+		label: "er-whole-series-discount__label",
+		row: "er-whole-series-discount__row",
+		input: "er-whole-series-discount__input",
+		apply: "er-whole-series-discount__apply",
+		remove: "er-whole-series-discount__remove",
+		hint: "er-whole-series-discount__hint",
+		feedback: "er-whole-series-discount__feedback"
 	},
 	"event-registration": {
 		root: "er-discount",

package/dist/client/{EventCombined.client-EhscD4U6.mjs → EventCombined.client-xID7zN__.mjs}

@@ -1,8 +1,8 @@
 "use client";
-import { t as clsx } from "./clsx-DgIEfj3H.mjs";
-import { B as groupEventsByDate, D as getEventRuntimeFiltersKey, E as buildEventRuntimeFilters, H as resolveEventLinkProps, I as formatEventTeacherLine, L as formatTime, P as formatEventPrice, R as getCardOrientation, W as getEventAvailability, Z as themeButtonClassName, bt as assertNever, j as formatDate, z as getContainerClass } from "./propsDecoder-CAZdhwjs.mjs";
-import { a as EventCardClient, i as EventPaginatedListView, n as useEventPagination, o as EventFilters, r as toError, t as useEventFilters } from "./useEventFilters-CULOa4nB.mjs";
-import { n as useBlockApi } from "./context-CJz1Vlsz.mjs";
+import { D as clsx } from "./colorStyles-CrxJrPjJ.mjs";
+import { A as getEventRuntimeFiltersKey, B as formatTime, G as resolveEventLinkProps, H as getContainerClass, L as formatEventPrice, P as formatDate, St as assertNever, U as groupEventsByDate, V as getCardOrientation, et as themeButtonClassName, k as buildEventRuntimeFilters, q as getEventAvailability, z as formatEventTeacherLine } from "./propsDecoder-BxmqPKdP.mjs";
+import { a as EventCardClient, i as EventPaginatedListView, n as useEventPagination, o as EventFilters, r as toError, t as useEventFilters } from "./useEventFilters-CUmhE24_.mjs";
+import { n as useBlockApi } from "./context-B83PiNzm.mjs";
 import { t as createBodyThemePortalRoot } from "./themePortalRoot-AGs4cE7t.mjs";
 import { t as ModalShell } from "./ModalShell-CqkBvBIC.mjs";
 import React, { createContext, useCallback, useContext, useEffect, useId, useMemo, useReducer, useRef, useState } from "react";
@@ -741,6 +741,30 @@ const WeekAgendaView = ({ days, events, showCapacity, emptyMessage = "No events
 	});
 };
 //#endregion
+//#region ../blocks/src/system/runtime/nodes/events/shared/EventModalCloseButton.tsx
+function EventModalCloseButton({ closeButtonRef, onClose }) {
+	return /* @__PURE__ */ jsx("button", {
+		ref: closeButtonRef,
+		type: "button",
+		className: "ec-modal-close",
+		onClick: onClose,
+		"aria-label": "Close",
+		children: /* @__PURE__ */ jsx("svg", {
+			width: "24",
+			height: "24",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "2",
+			viewBox: "0 0 24 24",
+			children: /* @__PURE__ */ jsx("path", {
+				strokeLinecap: "round",
+				strokeLinejoin: "round",
+				d: "M6 18L18 6M6 6l12 12"
+			})
+		})
+	});
+}
+//#endregion
 //#region ../blocks/src/system/runtime/nodes/events/shared/EventDetailModal.tsx
 /**
 * EventDetailModal - Modal overlay displaying full EventCard details
@@ -748,7 +772,7 @@ const WeekAgendaView = ({ days, events, showCapacity, emptyMessage = "No events
 * Reuses EventCard component directly for DRY implementation.
 * EventCard already includes the CTA button to navigate to the full event page.
 */
-function EventDetailModal({ event, showCapacity, onClose, portalRoot, cardVariant = "default", buttonVariant = "primary", buttonText, showMap = true }) {
+function EventDetailModal({ event, showCapacity, onClose, portalRoot, cardRole = "default", buttonVariant = "primary", buttonText, showMap = true }) {
 	return /* @__PURE__ */ jsx(ModalShell, {
 		title: event.title ? `${event.title}` : "Event details",
 		titleId: "ec-event-modal-title",
@@ -758,31 +782,12 @@ function EventDetailModal({ event, showCapacity, onClose, portalRoot, cardVarian
 		overlayClassName: "ec-modal-overlay",
 		modalClassName: "ec-modal ec-modal--event",
 		renderSrOnlyTitle: true,
-		renderHeader: ({ closeButtonRef, onClose }) => /* @__PURE__ */ jsx("button", {
-			ref: closeButtonRef,
-			type: "button",
-			className: "ec-modal-close",
-			onClick: onClose,
-			"aria-label": "Close",
-			children: /* @__PURE__ */ jsx("svg", {
-				width: "24",
-				height: "24",
-				fill: "none",
-				stroke: "currentColor",
-				strokeWidth: "2",
-				viewBox: "0 0 24 24",
-				children: /* @__PURE__ */ jsx("path", {
-					strokeLinecap: "round",
-					strokeLinejoin: "round",
-					d: "M6 18L18 6M6 6l12 12"
-				})
-			})
-		}),
+		renderHeader: (props) => /* @__PURE__ */ jsx(EventModalCloseButton, { ...props }),
 		children: /* @__PURE__ */ jsx("div", {
 			className: "ec-modal-content",
 			children: /* @__PURE__ */ jsx(EventCardClient, {
 				event,
-				cardVariant,
+				cardRole,
 				buttonVariant,
 				buttonText,
 				showImage: true,
@@ -814,26 +819,7 @@ function DayEventsModal({ date, events, showCapacity, onClose, onSelectEvent, po
 		portalRoot,
 		overlayClassName: "ec-modal-overlay",
 		modalClassName: "ec-modal ec-modal--day",
-		renderHeader: ({ closeButtonRef, onClose }) => /* @__PURE__ */ jsx("button", {
-			ref: closeButtonRef,
-			type: "button",
-			className: "ec-modal-close",
-			onClick: onClose,
-			"aria-label": "Close",
-			children: /* @__PURE__ */ jsx("svg", {
-				width: "24",
-				height: "24",
-				fill: "none",
-				stroke: "currentColor",
-				strokeWidth: "2",
-				viewBox: "0 0 24 24",
-				children: /* @__PURE__ */ jsx("path", {
-					strokeLinecap: "round",
-					strokeLinejoin: "round",
-					d: "M6 18L18 6M6 6l12 12"
-				})
-			})
-		}),
+		renderHeader: (props) => /* @__PURE__ */ jsx(EventModalCloseButton, { ...props }),
 		children: [/* @__PURE__ */ jsxs("div", {
 			className: "ec-modal-header",
 			children: [/* @__PURE__ */ jsx("h2", {
@@ -868,7 +854,7 @@ function DayEventsModal({ date, events, showCapacity, onClose, onSelectEvent, po
 * - EventDetailModal for single event view
 * - DayEventsModal for day events list (clicking an event switches to event modal)
 */
-function EventModals({ showCapacity, cardVariant, buttonVariant, buttonText }) {
+function EventModals({ showCapacity, cardRole, buttonVariant, buttonText }) {
 	const markerRef = React.useRef(null);
 	const [portalRoot, setPortalRoot] = React.useState(null);
 	const { modalState, openEventModal, closeModal } = useEventModal();
@@ -896,7 +882,7 @@ function EventModals({ showCapacity, cardVariant, buttonVariant, buttonText }) {
 		event: modalState.event,
 		onClose: closeModal,
 		portalRoot,
-		cardVariant,
+		cardRole,
 		buttonVariant,
 		buttonText,
 		showCapacity
@@ -960,6 +946,7 @@ function toEventCombinedControllerProps(props) {
 		showVenue: props.render.display.showVenue,
 		showMap: props.render.display.showMap,
 		showCapacity: props.render.display.showCapacity,
+		cardRole: props.render.display.cardRole,
 		buttonVariant: props.render.display.buttonVariant,
 		buttonText: props.render.display.buttonText,
 		emptyMessage: props.render.display.emptyMessage,
@@ -975,7 +962,7 @@ function toEventCombinedControllerProps(props) {
 const EventCombinedClient = ({ events: initialEvents, siteId, stage, listLayout = "stack", listColumns = "3", eventsPerPage = 12, paginationAction = {
 	kind: "loadMore",
 	label: "Load more events"
-}, startOfWeek = "monday", calendarTabViews = "both", defaultCalendarView, showFilters, showCategoryFilter = "auto", showVenueFilter, showStaffFilter, eventSurface, filterEventPresets, scheduleScope, filterCategoryIds, filterStaffMemberId, filterVenueId, showVenue, showMap, showCapacity, buttonVariant = "primary", buttonText = "Book", emptyMessage = "No upcoming events scheduled.", className }) => {
+}, startOfWeek = "monday", calendarTabViews = "both", defaultCalendarView, showFilters, showCategoryFilter = "auto", showVenueFilter, showStaffFilter, eventSurface, filterEventPresets, scheduleScope, filterCategoryIds, filterStaffMemberId, filterVenueId, showVenue, showMap, showCapacity, cardRole, buttonVariant = "primary", buttonText = "Book", emptyMessage = "No upcoming events scheduled.", className }) => {
 	const fetchInitialEventsOnMount = initialEvents == null;
 	const resolvedShowFilters = showFilters ?? true;
 	const resolvedShowVenueFilter = showVenueFilter ?? false;
@@ -1067,7 +1054,7 @@ const EventCombinedClient = ({ events: initialEvents, siteId, stage, listLayout
 		emptyMessage,
 		loadingMessage: "Loading events…",
 		containerClass,
-		cardVariant: "default",
+		cardRole,
 		buttonVariant,
 		buttonText,
 		showVenue: resolvedShowVenue,
@@ -1216,6 +1203,7 @@ const EventCombinedClient = ({ events: initialEvents, siteId, stage, listLayout
 					})
 				]
 			}), /* @__PURE__ */ jsx(EventModals, {
+				cardRole,
 				buttonVariant,
 				buttonText,
 				showCapacity: resolvedShowCapacity

package/dist/client/{EventListing.client-Bn26cFTY.mjs → EventListing.client-CriBslp0.mjs}

@@ -1,6 +1,6 @@
 "use client";
-import { E as buildEventRuntimeFilters } from "./propsDecoder-CAZdhwjs.mjs";
-import { i as EventPaginatedListView, n as useEventPagination, o as EventFilters, t as useEventFilters } from "./useEventFilters-CULOa4nB.mjs";
+import { k as buildEventRuntimeFilters } from "./propsDecoder-BxmqPKdP.mjs";
+import { i as EventPaginatedListView, n as useEventPagination, o as EventFilters, t as useEventFilters } from "./useEventFilters-CUmhE24_.mjs";
 import { useId, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/nodes/events/EventListing.client.tsx

package/dist/client/{FeedbackMessage-ByMrs3cr.mjs → FeedbackMessage-CtLvvS_d.mjs}

@@ -3,13 +3,25 @@ import { jsx, jsxs } from "react/jsx-runtime";
 function joinClasses(...parts) {
 	return parts.filter((part) => typeof part === "string" && part.length > 0).join(" ");
 }
-function FeedbackMessage({ tone, children, className, id, title, titleClassName, bodyClassName, role = "status", live }) {
+/**
+* The class each treatment contributes on top of whatever the caller passed.
+*
+* `panel` contributes nothing: its callers already pass `alert alert-*`, so
+* adopting the vocabulary changes no existing rendering. `field-note` needs a
+* single hook — its tone styling keys off `data-feedback-tone` in the
+* theme-generated CSS rather than off a second class.
+*/
+function treatmentClass(treatment) {
+	return treatment === "field-note" ? "feedback-note" : void 0;
+}
+function FeedbackMessage({ tone, treatment = "panel", children, className, id, title, titleClassName, bodyClassName, role = "status", live }) {
 	const resolvedLive = live ?? (role === "alert" ? "assertive" : "polite");
-	const shouldWrapBody = Boolean(title || bodyClassName);
+	const shouldWrapBody = Boolean(title || bodyClassName) || treatment === "field-note";
 	return /* @__PURE__ */ jsxs("div", {
 		id,
-		className,
+		className: joinClasses(className, treatmentClass(treatment)) || void 0,
 		"data-feedback-tone": tone,
+		"data-feedback-treatment": treatment,
 		role,
 		"aria-live": resolvedLive === "off" ? void 0 : resolvedLive,
 		children: [title ? /* @__PURE__ */ jsx("p", {