@riverbankcms/sdk 0.130.0 → 0.130.2

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

@@ -0,0 +1,19 @@
+import type { PageDesignEditorBlock } from './pageDesignEditorModel';
+import { type BlockDesignCapabilityMap, type BlockDesignPlan, type CardRoleCapability, type DesignBlockId } from './types';
+export declare function cardRoleCapabilitiesByBlockKind(blocks: readonly PageDesignEditorBlock<DesignBlockId>[]): ReadonlyMap<string, CardRoleCapability>;
+/**
+ * The capability map this compiler resolves against is *synthesized from the
+ * plan itself*: every axis is set to exactly what the block already asked for,
+ * because the read model has already gated those choices against the real
+ * declared capability and re-gating them here would only re-run the same
+ * decision with less information.
+ *
+ * `cardRoles` is the exception and must be threaded through from the
+ * declaration. It does not describe a choice the plan made — it describes
+ * which card path the block's *renderer* understands. Synthesizing
+ * `'supported'` would compile `_cardStyles.role` for blocks that render no
+ * card at all, so a Look could hand a surface to a block with nowhere to put
+ * it. This compiler is not preview-only: it also serves published ordinary
+ * pages and published template/entry pages.
+ */
+export declare function runtimeCapabilitiesForBlocks(blocks: readonly BlockDesignPlan<DesignBlockId, string>[], cardRolesByBlockKind: ReadonlyMap<string, CardRoleCapability>): BlockDesignCapabilityMap;

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

@@ -1,4 +1,5 @@
 import { type BoxBackground } from '../boxBackgroundSchema';
+import { type ResolvedSurfaceForeground } from '../surfaces';
 import type { CompiledBlockRuntimeFields } from './runtimeCompiler';
 type CanonicalRuntimeBackground = Readonly<{
     kind: 'none';
@@ -20,4 +21,12 @@ export type ResolvedSectionBackground = Readonly<{
 }>;
 export declare function parseCanonicalRuntimeBackground(content: Record<string, unknown>): CanonicalRuntimeBackground;
 export declare function resolveSectionBackground(source: CanonicalRuntimeBackground, lookDefault: NonNullable<NonNullable<CompiledBlockRuntimeFields['_sectionStyles']>['background']> | null | undefined): ResolvedSectionBackground;
+export declare function resolveSectionForeground(background: ResolvedSectionBackground, palette: Readonly<Record<string, string>>): ResolvedSurfaceForeground;
+/**
+ * Read foreground authority from post-compiler block content. The preview
+ * compiler has already materialized any Look-owned background into
+ * `_sectionStyles`; raw authored content must be composed with its Look through
+ * `resolveSectionBackground` instead.
+ */
+export declare function resolveCompiledSectionForegroundFromContent(content: Record<string, unknown> | null, palette: Readonly<Record<string, string>>): ResolvedSurfaceForeground;
 export {};

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

@@ -2,7 +2,7 @@ import { type CardStylesOverride, type ContainerStylesOverride, type SectionStyl
 import { type ExpandedPalette } from '../palette/expandPalette';
 import { type ButtonStyleSelection } from '../buttons/styles';
 import { type RuntimeStyleWriteResultForFields, type StyleAuthority } from './designState';
-import { type ContentFrameIntent, type BlockCompositionIntent, type EyebrowTreatment, type FlushFrameTreatment, type DesignBoundaryId, type PanelFrameTreatment, type ResolvedBlockDesignPlan, type ResolvedPageDesignPlan, type SiteStyleItemSurfaceIntent, type SiteStyleSectionTransitionIntent, type SiteStyleSurfaceIntent, type ThemeTokenRecipes } from './types';
+import { type ContentFrameIntent, type BlockCompositionIntent, type EyebrowTreatment, type FlushFrameTreatment, type DesignBoundaryId, type PanelFrameTreatment, type ResolvedBlockDesignPlan, type ResolvedPageDesignPlan, type SiteStyleSectionTransitionIntent, type SiteStyleSurfaceIntent, type ThemeTokenRecipes } from './types';
 import { type SectionBoundaryRuntimeMetrics } from './sectionTransitions';
 import { type ThemeColorToken } from '../tokens';
 import { type GradientPresetId } from '../gradients';
@@ -44,7 +44,6 @@ export type DesignRuntimeRules = Readonly<{
 export type ComponentRuntimeRules = Readonly<{
     panelFrames: Readonly<Record<PanelFrameTreatment, ContainerStylesOverride>>;
     flushFrames: Readonly<Record<FlushFrameTreatment, ContainerStylesOverride>>;
-    itemSurfaces: Readonly<Record<SiteStyleItemSurfaceIntent, CardStylesOverride | null>>;
 }>;
 export type CompiledBlockRuntimeFields = Readonly<{
     _frameStyles: ContentFrameIntent;
@@ -241,66 +240,6 @@ export declare const defaultComponentRuntimeRules: {
             readonly raised: false;
         };
     };
-    readonly itemSurfaces: {
-        readonly none: null;
-        readonly default: {
-            readonly spacing: "medium";
-            readonly rounded: "lg";
-            readonly raised: false;
-        };
-        readonly flat: {
-            readonly spacing: "medium";
-            readonly rounded: "lg";
-            readonly raised: false;
-        };
-        readonly outlined: {
-            readonly spacing: "medium";
-            readonly rounded: "lg";
-            readonly raised: false;
-            readonly border: {
-                readonly enabled: true;
-                readonly width: "1";
-                readonly colorToken: "border";
-            };
-        };
-        readonly raised: {
-            readonly spacing: "medium";
-            readonly rounded: "xl";
-            readonly raised: true;
-        };
-        readonly inset: {
-            readonly treatment: "soft-panel";
-            readonly spacing: "comfortable";
-            readonly rounded: "xl";
-            readonly raised: false;
-            readonly border: {
-                readonly enabled: false;
-            };
-            readonly background: {
-                readonly type: "color";
-                readonly color: "surfaceAlt";
-                readonly textColor: "text";
-            };
-        };
-        readonly editorial: {
-            readonly treatment: "editorial-rule";
-            readonly spacing: "none";
-            readonly rounded: "none";
-            readonly raised: false;
-            readonly border: {
-                readonly enabled: false;
-            };
-        };
-        readonly 'color-blocked': {
-            readonly treatment: "color-blocked";
-            readonly spacing: "spacious";
-            readonly rounded: "2xl";
-            readonly raised: false;
-            readonly border: {
-                readonly enabled: false;
-            };
-        };
-    };
 };
 /** Compiles one resolved semantic block plan into legacy block runtime fields. */
 export declare function compileBlockRuntimeFields<TBlockId extends string, TPurpose extends string>(input: CompileBlockRuntimeInput<TBlockId, TPurpose>): CompiledBlockRuntime & Readonly<{

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

@@ -1,4 +1,5 @@
-import { type AdvancedBlockDesignIntent, type ContentFrameIntent, type GeneratedBlockDesignIntent, type GeneratedContentFrameIntent, type GeneratedItemSurfaceIntent, type GeneratedSectionTransitionIntent, type GeneratedSurfaceIntent, type SiteStyleEmphasis, type SiteStyleItemSurfaceIntent, type SiteStyleSectionTransitionIntent, type SiteStyleSurfaceIntent, type UserBlockDesignIntent, type UserContentFrameIntent, type UserItemSurfaceIntent, type UserSectionTransitionIntent, type UserSurfaceIntent } from './types';
+import { type CardRole } from '../cards';
+import { type AdvancedBlockDesignIntent, type ContentFrameIntent, type GeneratedBlockDesignIntent, type GeneratedContentFrameIntent, type GeneratedCardRoleIntent, type GeneratedSectionTransitionIntent, type GeneratedSurfaceIntent, type SiteStyleEmphasis, type SiteStyleSectionTransitionIntent, type SiteStyleSurfaceIntent, type UserBlockDesignIntent, type UserContentFrameIntent, type UserCardRoleIntent, type UserSectionTransitionIntent, type UserSurfaceIntent } from './types';
 /**
  * Design option catalogs are source-specific whitelists for schema builders and UI
  * controls. They describe what a choice source may express; DesignResolutionPolicy
@@ -6,18 +7,18 @@ import { type AdvancedBlockDesignIntent, type ContentFrameIntent, type Generated
  */
 export type DesignChoiceSource = GeneratedBlockDesignIntent['sectionSurface']['source'] | UserBlockDesignIntent['sectionSurface']['source'] | Exclude<AdvancedBlockDesignIntent['sectionSurface']['source'], UserBlockDesignIntent['sectionSurface']['source']>;
 export type DetachedCustomCapability<TSource extends DesignChoiceSource> = TSource extends 'advanced' ? true : false;
-export type DesignOptionCatalog<TSource extends DesignChoiceSource, TSurface extends SiteStyleSurfaceIntent, TContentFrame extends ContentFrameIntent, TItemSurface extends SiteStyleItemSurfaceIntent, TTransition extends SiteStyleSectionTransitionIntent> = Readonly<{
+export type DesignOptionCatalog<TSource extends DesignChoiceSource, TSurface extends SiteStyleSurfaceIntent, TContentFrame extends ContentFrameIntent, TCardRole extends CardRole, TTransition extends SiteStyleSectionTransitionIntent> = Readonly<{
     source: TSource;
     sectionSurfaces: readonly TSurface[];
     contentFrames: readonly TContentFrame[];
-    itemSurfaces: readonly TItemSurface[];
+    cardRoles: readonly TCardRole[];
     transitions: readonly TTransition[];
     emphases: readonly SiteStyleEmphasis[];
     detachedCustom: DetachedCustomCapability<TSource>;
 }>;
-export type GeneratedDesignOptionCatalog = DesignOptionCatalog<'generated', GeneratedSurfaceIntent, GeneratedContentFrameIntent, GeneratedItemSurfaceIntent, GeneratedSectionTransitionIntent>;
-export type UserDesignOptionCatalog = DesignOptionCatalog<'user', UserSurfaceIntent, UserContentFrameIntent, UserItemSurfaceIntent, UserSectionTransitionIntent>;
-export type AdvancedDesignOptionCatalog = DesignOptionCatalog<'advanced', SiteStyleSurfaceIntent, ContentFrameIntent, SiteStyleItemSurfaceIntent, SiteStyleSectionTransitionIntent>;
+export type GeneratedDesignOptionCatalog = DesignOptionCatalog<'generated', GeneratedSurfaceIntent, GeneratedContentFrameIntent, GeneratedCardRoleIntent, GeneratedSectionTransitionIntent>;
+export type UserDesignOptionCatalog = DesignOptionCatalog<'user', UserSurfaceIntent, UserContentFrameIntent, UserCardRoleIntent, UserSectionTransitionIntent>;
+export type AdvancedDesignOptionCatalog = DesignOptionCatalog<'advanced', SiteStyleSurfaceIntent, ContentFrameIntent, CardRole, SiteStyleSectionTransitionIntent>;
 export type DesignOptionCatalogForSource<TSource extends DesignChoiceSource> = TSource extends 'generated' ? GeneratedDesignOptionCatalog : TSource extends 'user' ? UserDesignOptionCatalog : TSource extends 'advanced' ? AdvancedDesignOptionCatalog : never;
 export declare const generatedDesignOptionCatalog: {
     readonly source: "generated";
@@ -35,7 +36,7 @@ export declare const generatedDesignOptionCatalog: {
         treatment: import("../../../blocks/src/index").FlushFrameTreatment;
         bleed: "start";
     }>];
-    readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+    readonly cardRoles: readonly ["default", "alternative", "open", "none"];
     readonly transitions: readonly ["none", "soft-fade-short", "soft-fade-long"];
     readonly emphases: readonly ["low", "medium", "high"];
     readonly detachedCustom: false;
@@ -67,7 +68,7 @@ export declare const userDesignOptionCatalog: {
         treatment: import("../../../blocks/src/index").FlushFrameTreatment;
         bleed: "both";
     }>];
-    readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+    readonly cardRoles: readonly ["default", "alternative", "open", "none"];
     readonly transitions: readonly ["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"];
     readonly emphases: readonly ["low", "medium", "high"];
     readonly detachedCustom: false;
@@ -99,7 +100,7 @@ export declare const advancedDesignOptionCatalog: {
         treatment: import("../../../blocks/src/index").FlushFrameTreatment;
         bleed: "both";
     }>];
-    readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+    readonly cardRoles: readonly ["default", "alternative", "open", "none"];
     readonly transitions: readonly ["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"];
     readonly emphases: readonly ["low", "medium", "high"];
     readonly detachedCustom: true;
@@ -121,7 +122,7 @@ export declare const designOptionCatalogs: {
             treatment: import("../../../blocks/src/index").FlushFrameTreatment;
             bleed: "start";
         }>];
-        readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+        readonly cardRoles: readonly ["default", "alternative", "open", "none"];
         readonly transitions: readonly ["none", "soft-fade-short", "soft-fade-long"];
         readonly emphases: readonly ["low", "medium", "high"];
         readonly detachedCustom: false;
@@ -153,7 +154,7 @@ export declare const designOptionCatalogs: {
             treatment: import("../../../blocks/src/index").FlushFrameTreatment;
             bleed: "both";
         }>];
-        readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+        readonly cardRoles: readonly ["default", "alternative", "open", "none"];
         readonly transitions: readonly ["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"];
         readonly emphases: readonly ["low", "medium", "high"];
         readonly detachedCustom: false;
@@ -185,7 +186,7 @@ export declare const designOptionCatalogs: {
             treatment: import("../../../blocks/src/index").FlushFrameTreatment;
             bleed: "both";
         }>];
-        readonly itemSurfaces: readonly ["none", "default", "flat", "outlined", "raised", "inset", "editorial", "color-blocked"];
+        readonly cardRoles: readonly ["default", "alternative", "open", "none"];
         readonly transitions: readonly ["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"];
         readonly emphases: readonly ["low", "medium", "high"];
         readonly detachedCustom: true;

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,8 @@ 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"];
+export type TestimonialsCompositionTreatment = (typeof testimonialsCompositionTreatmentValues)[number];
 /**
  * A closed description of structural presentation selected by a Look.
  * Concrete spacing, radii, colour, and shadow remain site-style concerns.
@@ -219,6 +220,9 @@ export type BlockCompositionIntent = Readonly<{
 }> | Readonly<{
     kind: 'feature-cards';
     treatment: FeatureCardCompositionTreatment;
+}> | Readonly<{
+    kind: 'testimonials';
+    treatment: TestimonialsCompositionTreatment;
 }>;
 export type BlockCompositionCapability = Readonly<{
     kind: 'none';
@@ -228,6 +232,9 @@ export type BlockCompositionCapability = Readonly<{
 }> | Readonly<{
     kind: 'feature-cards';
     treatments: NonEmptyReadonlyArray<FeatureCardCompositionTreatment>;
+}> | Readonly<{
+    kind: 'testimonials';
+    treatments: NonEmptyReadonlyArray<TestimonialsCompositionTreatment>;
 }>;
 export declare const eyebrowTreatmentValues: readonly ["plain", "accent", "pill", "accent-pill", "pill-bounce", "accent-pill-bounce"];
 export type EyebrowTreatment = (typeof eyebrowTreatmentValues)[number];
@@ -283,16 +290,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 +331,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 +395,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 +418,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 +432,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 +442,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 +472,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 +487,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 +507,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 +528,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 +551,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 +598,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 +691,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 +699,6 @@ export type BlockDesignCapabilityRequest = Readonly<{
     heroTypographyScale?: HeroTypographyScaleIntent;
     imageSurfaceTreatment?: ImageSurfaceTreatment;
     imageSurfaceMotion?: ImageSurfaceMotion;
-    testimonialCardTreatment?: TestimonialCardTreatment;
     tileTreatment?: TileTreatment;
     eventListTreatment?: EventListTreatment;
     eyebrowTreatment?: EyebrowTreatment;
@@ -695,7 +708,6 @@ export type BlockDesignCapabilityRequest = Readonly<{
 export type BlockDesignCapabilityFallback = Readonly<{
     sectionSurface: 'base';
     contentFrame: PlainFrameIntent;
-    itemSurface: 'none';
     transitionAfter: 'none';
     sectionHeight: 'default';
     heroLegibility: 'none';
@@ -703,7 +715,6 @@ export type BlockDesignCapabilityFallback = Readonly<{
         kind: 'none';
     }>;
     imageSurfaceMotion: 'static';
-    testimonialCardTreatment: 'default';
     tileTreatment: 'default';
     eventListTreatment: 'plain';
     eyebrowTreatment: 'plain';
@@ -755,7 +766,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

@@ -7,7 +7,8 @@ export type NavigationTab = {
 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 +35,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/{CourseRegistrationWizard-Bvtz9G9g.mjs → CourseRegistrationWizard-DGW9F0SQ.mjs}

@@ -1,12 +1,12 @@
 "use client";
-import { It as toBookingTimeZone, Kt as assertNever, Lt as toScheduledBookingDateTime, Ot as formatBookingDate, Rt as parseEventPageSurfaceSubject, Z as themeButtonClassName, bt as assertNever$1, jt as formatBookingTime } from "./propsDecoder-CAZdhwjs.mjs";
-import { n as formatCoursePriceDisplay, r as resolveCoursePricingState, t as formatCoursePriceAmount } from "./pricing-NgK7ozkg.mjs";
-import { n as useBlockApi } from "./context-CJz1Vlsz.mjs";
+import { Et as formatBookingDate, Ft as toScheduledBookingDateTime, It as parseEventPageSurfaceSubject, Pt as toBookingTimeZone, Wt as assertNever, Z as themeButtonClassName, kt as formatBookingTime, vt as assertNever$1 } from "./propsDecoder-CBPGXEYX.mjs";
+import { n as formatCoursePriceDisplay, r as resolveCoursePricingState, t as formatCoursePriceAmount } from "./pricing-BiqIMgZk.mjs";
+import { n as useBlockApi } from "./context-B83PiNzm.mjs";
 import { n as isSpamProtectionEnabled, r as AltchaWidget, t as getChallengeUrl } from "./src-B833rYRr.mjs";
-import { a as CheckIcon, i as StateIcon, n as useDiscountCodeUi, r as TerminalPanel, t as scrollToBlock } from "./scrollToBlock-DSSqVQr1.mjs";
-import { t as DiscountCodeDisclosure } from "./DiscountCodeDisclosure-Ur-Xx1U_.mjs";
-import { n as SpinnerNode, r as formatPrice, t as StepIndicator$1 } from "./StepIndicator-BfbdiVQI.mjs";
-import { t as FeedbackMessage } from "./FeedbackMessage-ByMrs3cr.mjs";
+import { a as CheckIcon, i as StateIcon, n as useDiscountCodeUi, r as TerminalPanel, t as scrollToBlock } from "./scrollToBlock-DZ73aEX6.mjs";
+import { t as DiscountCodeDisclosure } from "./DiscountCodeDisclosure-BPZ-yfGI.mjs";
+import { n as SpinnerNode, r as formatPrice, t as StepIndicator$1 } from "./StepIndicator-CLjQhkDb.mjs";
+import { t as FeedbackMessage } from "./FeedbackMessage-CtLvvS_d.mjs";
 import { n as getFieldValidationControlProps, t as FieldValidationMessage } from "./FieldValidationMessage-AYanWFb-.mjs";
 import { t as buildCheckoutReturnUrls } from "./checkoutUrls-Ct8Mxna3.mjs";
 import { t as CrossIcon } from "./CrossIcon-Dn1KRKW5.mjs";

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

@@ -1,5 +1,5 @@
 "use client";
-import { Z as themeButtonClassName } from "./propsDecoder-CAZdhwjs.mjs";
+import { Z as themeButtonClassName } from "./propsDecoder-CBPGXEYX.mjs";
 import { useId } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region ../blocks/src/system/runtime/api/types/discounts.ts