@riverbankcms/sdk 0.130.0 → 0.132.0

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

@@ -2,6 +2,7 @@ export * from './accessibleSurfaces';
 export * from './appearancePresets';
 export * from './blockFlow';
 export * from './backgroundAppearance';
+export * from './cardRoleVocabulary';
 export * from './compositionBudget';
 export * from './compilationPlan';
 export * from './contentTemplateDesignIntent';
@@ -22,14 +23,18 @@ export * from './lookOptionGroups';
 export * from './logoBranding';
 export * from './pageDesignAuthority';
 export * from './pageDesignEditorErrors';
+export * from './pageDesignEditorCapabilities';
 export * from './pageDesignEditorModel';
+export * from './pageDesignAppearanceAvailability';
 export * from './pageDesignIntent';
+export * from './pageDesignIntentEquality';
 export * from './previewCustomization';
 export * from './persistedIdParseResult';
 export * from './rawStyleFields';
 export * from './records';
 export * from './resolver';
 export * from './runtimeCompiler';
+export * from './runtimeBackgroundResolution';
 export * from './sectionTransitions';
 export * from './siteChromeBackgrounds';
 export * from './siteChromeNavPreferences';

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

@@ -0,0 +1,3 @@
+import type { PageDesignEditorBlock } from './pageDesignEditorModel';
+import type { AppearancePresetId } from './types';
+export declare function isPageDesignAppearancePresetAvailable(block: Pick<PageDesignEditorBlock, 'lookAvailability' | 'availableLooks'>, appearancePresetId: AppearancePresetId): boolean;

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

@@ -0,0 +1,22 @@
+import { type BlockDesignCapability, type CardRoleCapability, type UnsupportedBlockDesignCapabilityReason } from './types';
+/**
+ * How a block's declared design capability reads to the page-design editor and
+ * to everything compiled from its read model.
+ */
+export type PageDesignEditorBackgroundSupport = Readonly<{
+    kind: 'supported';
+    richBackgrounds: 'supported' | 'unsupported';
+}> | Readonly<{
+    kind: 'unsupported';
+    reason: UnsupportedBlockDesignCapabilityReason | 'section-surfaces-unsupported' | 'missing-design-capability';
+}>;
+export declare function cardRoleCapabilityOf(capability: BlockDesignCapability | null): CardRoleCapability;
+export declare function backgroundSupportForCapability(capability: BlockDesignCapability | null): PageDesignEditorBackgroundSupport;
+/**
+ * The capability-derived half of a block's editor read model, in one call so
+ * the read-model builder does not grow a projection per axis.
+ */
+export declare function capabilitySupportFor(capability: BlockDesignCapability | null): Readonly<{
+    backgroundSupport: PageDesignEditorBackgroundSupport;
+    cardRoles: CardRoleCapability;
+}>;

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

@@ -1,6 +1,7 @@
+import { type PageDesignEditorBackgroundSupport } from './pageDesignEditorCapabilities';
 import type { BlockDesignMetadata } from './blockFlow';
 import { type PageDesignDecisions } from './pageDesignIntent';
-import { type AppearancePresetId, type BlockDesignCapability, type BoundaryOptionId, type DesignBlockId, type DesignBoundaryId, type LayoutVariantKey, type NonEmptyReadonlyArray, type PageFlowPresetId, type SiteStyleId, type UnsupportedBlockDesignCapabilityReason } from './types';
+import { type AppearancePresetId, type BlockDesignCapability, type CardRoleCapability, type BoundaryOptionId, type DesignBlockId, type DesignBoundaryId, type LayoutVariantKey, type NonEmptyReadonlyArray, type PageFlowPresetId, type SiteStyleId } from './types';
 import { type BoundaryOption } from './sectionTransitions';
 import type { PageDesignEditorBlockContentRevision, PageDesignEditorLayoutOption, PageDesignEditorLookOption, PageDesignEditorLooksForLayout } from './pageDesignEditorOptions';
 export { boundaryOptions, type BoundaryOption } from './sectionTransitions';
@@ -21,13 +22,6 @@ export type PageDesignEditorBlockInput<TBlockId extends DesignBlockId = DesignBl
     designCapability?: BlockDesignCapability | null;
     layoutOptionLabels?: Readonly<Record<string, string>>;
 }>;
-export type PageDesignEditorBackgroundSupport = Readonly<{
-    kind: 'supported';
-    richBackgrounds: 'supported' | 'unsupported';
-}> | Readonly<{
-    kind: 'unsupported';
-    reason: UnsupportedBlockDesignCapabilityReason | 'section-surfaces-unsupported' | 'missing-design-capability';
-}>;
 export type PageDesignEditorChoice<TValue> = Readonly<{
     kind: 'auto';
     effectiveValue: TValue | null;
@@ -61,6 +55,13 @@ export type PageDesignEditorBlock<TBlockId extends DesignBlockId = DesignBlockId
     blockId: TBlockId;
     blockKind: string;
     backgroundSupport: PageDesignEditorBackgroundSupport;
+    /**
+     * Which card path this block renders, carried from its declared capability.
+     * The runtime compiler cannot re-derive it — it only sees design plans — and
+     * compiling a role for a block that still renders the legacy recipe would
+     * swap its card surface at render time.
+     */
+    cardRoles: CardRoleCapability;
     contentRevision?: PageDesignEditorBlockContentRevision;
     layout: PageDesignEditorSelection<LayoutVariantKey> | null;
     availableLayouts: readonly PageDesignEditorLayoutOption[];

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

@@ -0,0 +1,3 @@
+import type { PageDesignIntent } from './pageDesignIntent';
+import type { DesignBlockId } from './types';
+export declare function pageDesignIntentsEqual<TBlockId extends DesignBlockId>(left: PageDesignIntent<TBlockId>, right: PageDesignIntent<TBlockId>): boolean;

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

@@ -8,6 +8,8 @@ import { type HeaderLayoutStyleSelection } from './headerLayoutStyles';
 import { type CompiledBlockRuntimeFields, type CompiledBoundaryRuntime, type CompiledPageRuntime, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing, type SurfaceResolutionContext } from './runtimeCompiler';
 import { type AppearancePresetId, type DesignBlockId, type SiteStyleId } from './types';
 import { type CuratedSiteStyleTheme } from './siteStyleThemeCompiler';
+import type { SelectionFallbackWarning } from './selectionFallbackWarning';
+export type { SelectionFallbackWarning } from './selectionFallbackWarning';
 export type { CuratedSiteStyleTheme } from './siteStyleThemeCompiler';
 /**
  * Browser-safe public API for Theme V2 live preview compilation.
@@ -35,19 +37,8 @@ export declare const previewCustomizePurpose: "preview-customize";
 export declare function compileCuratedSiteStyleTheme(siteStyle: CuratedSiteStyle): CuratedSiteStyleTheme;
 export declare function defaultConcretePaletteForSiteStyle(siteStyle: CuratedSiteStyle): Theme['palette'];
 export declare function compileCuratedSiteStyleThemeById(siteStyleId: SiteStyleId): CuratedSiteStyleTheme | null;
-export type SelectionFallbackWarning = Readonly<{
-    kind: 'rejected-button-style';
-    requested: string;
-    fellBackTo: ButtonStyleSelection;
-}> | Readonly<{
-    kind: 'repaired-header-selection';
-    requested: HeaderLayoutStyleSelection;
-    resolved: HeaderLayoutStyleSelection;
-    reason: 'style-not-curated-for-layout' | 'layout-not-curated-for-site-style';
-}>;
 type SiteThemeSelectionsCommonInput = Readonly<{
     siteStyle: CuratedSiteStyle;
-    buttonStyleSelection: ButtonStyleSelection | null;
     typography?: Theme['typography'];
     palette: Theme['palette'];
 }>;

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/selectionFallbackWarning.d.ts

@@ -0,0 +1,15 @@
+import type { ButtonStyleSelection } from '../buttons/styles';
+import type { HeaderLayoutStyleSelection } from './headerLayoutStyles';
+export type SelectionFallbackWarning = Readonly<{
+    kind: 'rejected-button-style';
+    requested: string;
+    fellBackTo: ButtonStyleSelection;
+}> | Readonly<{
+    kind: 'recompiled-missing-button-system';
+    selection: ButtonStyleSelection;
+}> | Readonly<{
+    kind: 'repaired-header-selection';
+    requested: HeaderLayoutStyleSelection;
+    resolved: HeaderLayoutStyleSelection;
+    reason: 'style-not-curated-for-layout' | 'layout-not-curated-for-site-style';
+}>;

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;