@riverbankcms/sdk 0.149.0 → 0.150.0

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

@@ -516,18 +516,6 @@ export declare const blockAppearancePresets: readonly [import("../../../blocks/s
             readonly treatment: "framed-programme";
         };
     };
-}>, import("../../../blocks/src/index").WithResolvedCardRole<{
-    readonly id: "feature-cards-soft-panels";
-    readonly target: "feature-cards";
-    readonly label: "Soft tinted panels";
-    readonly blockKinds: readonly ["block.feature-cards"];
-    readonly design: {
-        readonly sectionSurface: "base";
-        readonly contentFrame: {
-            readonly kind: "plain";
-        };
-        readonly cardRole: "alternative";
-    };
 }>, import("../../../blocks/src/index").WithResolvedCardRole<{
     readonly id: "feature-cards-editorial-diptych";
     readonly target: "feature-cards";
@@ -543,33 +531,6 @@ export declare const blockAppearancePresets: readonly [import("../../../blocks/s
         };
         readonly cardRole: "default";
     };
-}>, import("../../../blocks/src/index").WithResolvedCardRole<{
-    readonly id: "feature-cards-editorial-pathways";
-    readonly target: "feature-cards";
-    readonly label: "Editorial pathways";
-    readonly blockKinds: readonly ["block.feature-cards"];
-    readonly constraints: {
-        readonly layoutVariantKeys: readonly ["editorial-pathways"];
-    };
-    readonly design: {
-        readonly sectionSurface: "base";
-        readonly contentFrame: {
-            readonly kind: "plain";
-        };
-        readonly cardRole: "default";
-    };
-}>, import("../../../blocks/src/index").WithResolvedCardRole<{
-    readonly id: "feature-cards-photo-tiles";
-    readonly target: "feature-cards";
-    readonly label: "Photo tiles";
-    readonly blockKinds: readonly ["block.feature-cards"];
-    readonly design: {
-        readonly sectionSurface: "base";
-        readonly contentFrame: {
-            readonly kind: "plain";
-        };
-        readonly cardRole: "default";
-    };
 }>, import("../../../blocks/src/index").WithResolvedCardRole<{
     readonly id: "events-lined-panel";
     readonly target: "events";
@@ -681,18 +642,6 @@ export declare const blockAppearancePresets: readonly [import("../../../blocks/s
         }>;
         readonly cardRole: "default";
     };
-}>, import("../../../blocks/src/index").WithResolvedCardRole<{
-    readonly id: "testimonials-default-cards";
-    readonly target: "testimonials";
-    readonly label: "Default cards";
-    readonly blockKinds: readonly ["block.testimonials"];
-    readonly design: {
-        readonly sectionSurface: "base";
-        readonly contentFrame: {
-            readonly kind: "plain";
-        };
-        readonly cardRole: "default";
-    };
 }>, import("../../../blocks/src/index").WithResolvedCardRole<{
     readonly id: "testimonials-statement-cards";
     readonly target: "testimonials";

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

@@ -12,6 +12,17 @@ export declare function blockAppearancePresetSupportsLayoutProfile(preset: Block
     allowLayoutConstrainedPresetWithoutProfile?: boolean;
 }>): boolean;
 export declare function resolveBlockAppearancePreset(preset: BlockAppearancePreset, layoutProfile?: BlockLayoutDesignProfile | null): ResolvedBlockAppearancePreset;
+/**
+ * Whether a site style can draw what a Look asks of it. A Look names a card
+ * role and leaves the surface to the site style, so a Look whose role the
+ * style only reaches by fallback (see `cardSystemDefinesRole`) would render as
+ * a different Look under a misleading name. Such Looks are not offered.
+ *
+ * This is the one availability rule derived from style capability; the
+ * catalogue and `recommendedAppearancePresetIds` never list per-style
+ * exceptions by hand.
+ */
+export declare function siteStyleSupportsLookDesign(siteStyle: CuratedSiteStyle, design: Pick<BlockAppearanceDesign, 'cardRole'>): boolean;
 export declare function getCompatibleBlockAppearancePresets(input: Readonly<{
     blockKind: string;
     layoutProfile?: BlockLayoutDesignProfile | null;

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

@@ -1,4 +1,4 @@
-import { type BlockDesignCapability, type CardRoleCapability, type UnsupportedBlockDesignCapabilityReason } from './types';
+import { type BlockDesignCapability, type CardRoleCapability, type SectionBackgroundPaint, 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.
@@ -11,6 +11,11 @@ export type PageDesignEditorBackgroundSupport = Readonly<{
     reason: UnsupportedBlockDesignCapabilityReason | 'section-surfaces-unsupported' | 'missing-design-capability';
 }>;
 export declare function cardRoleCapabilityOf(capability: BlockDesignCapability | null): CardRoleCapability;
+/**
+ * The section background paints a block admits. A block with no designed
+ * capability (a custom or SDK block) is not gated: it admits every paint.
+ */
+export declare function sectionBackgroundPaintsOf(capability: BlockDesignCapability | null): readonly SectionBackgroundPaint[];
 export declare function backgroundSupportForCapability(capability: BlockDesignCapability | null): PageDesignEditorBackgroundSupport;
 /**
  * The capability-derived half of a block's editor read model, in one call so
@@ -19,4 +24,5 @@ export declare function backgroundSupportForCapability(capability: BlockDesignCa
 export declare function capabilitySupportFor(capability: BlockDesignCapability | null): Readonly<{
     backgroundSupport: PageDesignEditorBackgroundSupport;
     cardRoles: CardRoleCapability;
+    sectionBackgroundPaints: readonly SectionBackgroundPaint[];
 }>;

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

@@ -1,7 +1,7 @@
 import { type PageDesignEditorBackgroundSupport } from './pageDesignEditorCapabilities';
 import type { BlockDesignMetadata } from './blockFlow';
 import { type PageDesignDecisions } from './pageDesignIntent';
-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 AppearancePresetId, type BlockDesignCapability, type CardRoleCapability, type SectionBackgroundPaint, type BoundaryOptionId, type DesignBlockId, type DesignBoundaryId, type LayoutVariantKey, type NonEmptyReadonlyArray, type PageFlowPresetId, type SiteStyleId } from './types';
 import type { BoundaryOption } from './sectionTransitions';
 import { type PageFlowPreset } from './pageFlowPresets';
 import type { PageDesignDefaultJoinSource } from './joinTreatment';
@@ -61,6 +61,12 @@ export type PageDesignEditorBlock<TBlockId extends DesignBlockId = DesignBlockId
      * swap its card surface at render time.
      */
     cardRoles: CardRoleCapability;
+    /**
+     * The section background paints the block's own `_sectionStyles` admits,
+     * carried from its declared capability for the same reason as `cardRoles`.
+     * Absent means every paint (older fixtures and SDK read models).
+     */
+    sectionBackgroundPaints?: readonly SectionBackgroundPaint[];
     contentRevision?: PageDesignEditorBlockContentRevision;
     layout: PageDesignEditorSelection<LayoutVariantKey> | null;
     availableLayouts: readonly PageDesignEditorLayoutOption[];

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

@@ -1,6 +1,11 @@
 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>;
+import { type BlockDesignCapabilityMap, type BlockDesignPlan, type CardRoleCapability, type DesignBlockId, type SectionBackgroundPaint } from './types';
+/** What a block's renderer can take, which the design plan alone cannot say. */
+export type RendererCapability = Readonly<{
+    cardRoles: CardRoleCapability;
+    sectionBackgroundPaints?: readonly SectionBackgroundPaint[];
+}>;
+export declare function rendererCapabilitiesByBlockKind(blocks: readonly PageDesignEditorBlock<DesignBlockId>[]): ReadonlyMap<string, RendererCapability>;
 /**
  * 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,
@@ -8,12 +13,13 @@ export declare function cardRoleCapabilitiesByBlockKind(blocks: readonly PageDes
  * 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
+ * `cardRoles` and `sectionBackgroundPaints` are the exceptions and must be
+ * threaded through from the declaration. They do not describe a choice the
+ * plan made — they describe which card path and which section background
+ * paints the block's *renderer* accepts. 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;
+export declare function runtimeCapabilitiesForBlocks(blocks: readonly BlockDesignPlan<DesignBlockId, string>[], rendererCapabilitiesByKind: ReadonlyMap<string, RendererCapability>): BlockDesignCapabilityMap;

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

@@ -5,10 +5,10 @@ import { type RuntimeStyleWriteResultForFields, type StyleAuthority } from './de
 import { type ContentFrameIntent, type BlockCompositionIntent, type EyebrowTreatment, type FlushFrameTreatment, type DesignBlockId, type PanelFrameTreatment, type ResolvedBlockDesignPlan, type ResolvedPageDesignPlan, type SiteStyleSurfaceIntent, type ThemeTokenRecipes } from './types';
 import { type PageRuntimeJoin } from './joinTreatment';
 import { type ThemeColorToken } from '../tokens';
-import { type GradientPresetId } from '../gradients';
+import type { GradientPresetId } from '../gradients';
 export type SemanticSpacing = 'none' | 'compact' | 'cozy' | 'medium' | 'comfortable' | 'spacious';
 export type SectionPaddingX = 'normal' | 'none';
-type SectionBackgroundOverride = NonNullable<SectionStylesOverride['background']>;
+export type SectionBackgroundOverride = NonNullable<SectionStylesOverride['background']>;
 type ColorSectionBackgroundOverride = Extract<SectionBackgroundOverride, {
     type: 'color';
 }>;
@@ -19,9 +19,12 @@ type SectionForegroundRuntimeTokenKey = 'textColor' | 'headingColor' | 'linkColo
 export type SectionForegroundRuntimeTokens = {
     readonly [TKey in SectionForegroundRuntimeTokenKey]: ThemeColorToken;
 };
+export type CompiledSectionForegroundTokens = {
+    readonly [TKey in SectionForegroundRuntimeTokenKey]: NonNullable<SectionBackgroundOverride[TKey]>;
+};
 export declare function defineSectionForegroundRuntimeTokens(input: Readonly<Record<SectionForegroundRuntimeTokenKey, unknown>>): SectionForegroundRuntimeTokens;
-type NonGradientSectionRuntimeBackground = ColorSectionBackgroundOverride | ImageSectionBackgroundOverride;
-type GradientSectionRuntimeBackground = Readonly<{
+export type NonGradientSectionRuntimeBackground = ColorSectionBackgroundOverride | ImageSectionBackgroundOverride;
+export type GradientSectionRuntimeBackground = Readonly<{
     type: 'gradient';
     gradientPresetId: GradientPresetId;
     opacity?: number;

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

@@ -0,0 +1,65 @@
+import type { ExpandedPalette } from '../palette/expandPalette';
+import type { DesignRuntimeRules, GradientSectionRuntimeBackground, NonGradientSectionRuntimeBackground, SectionBackgroundOverride, SectionForegroundRuntimeTokens, SectionSurfaceRuntimeRule, SurfaceResolutionContext } from './runtimeCompiler';
+import type { SectionBackgroundPaint, SiteStyleSurfaceIntent } from './types';
+/**
+ * Section surface backgrounds, compiled so their text stays legible whatever
+ * actually paints: the paint the block can admit, the site style's foreground
+ * checked against that paint, and the scrim the surface becomes when authored
+ * media replaces it.
+ */
+type ForegroundRole = 'textColor' | 'headingColor' | 'linkColor' | 'supportingColor';
+type SectionForeground = Readonly<Record<ForegroundRole, string>>;
+export declare function compileGradientSectionBackground(background: GradientSectionRuntimeBackground, foreground: SectionForegroundRuntimeTokens, palette: ExpandedPalette): SectionBackgroundOverride;
+export declare function compileColorSectionBackground(surface: SiteStyleSurfaceIntent, background: NonGradientSectionRuntimeBackground | undefined, foreground: Partial<SectionForegroundRuntimeTokens> | undefined, surfaceResolutionContext: SurfaceResolutionContext): SectionBackgroundOverride | undefined;
+/**
+ * The surface rule the block can actually paint. A site style may dress a
+ * surface in a gradient or a photo, but a block whose own section background
+ * field refuses that paint would be dropped at render admission, so it gets
+ * the surface's plain colour rule instead: the same band, resolved through
+ * the accessible-surface contract. A surface with no admissible paint at all
+ * compiles no background and inherits the page's.
+ */
+export declare function admissibleSurfaceRule(input: Readonly<{
+    surface: SiteStyleSurfaceIntent;
+    rules: DesignRuntimeRules;
+    plainRules: DesignRuntimeRules;
+    admitted: readonly SectionBackgroundPaint[] | undefined;
+}>): SectionSurfaceRuntimeRule;
+/**
+ * A site style's foreground tokens for a colour surface are candidates, not
+ * authority: they go through the surface contract the renderer applies
+ * (`resolveSurfaceForeground`), so the compiled tokens are the ones that
+ * actually render — and the ones that must stay legible if the band becomes a
+ * scrim over media.
+ */
+export declare function validatedSectionForeground(backgroundToken: string, candidates: SectionForeground, palette: ExpandedPalette): SectionForeground;
+/**
+ * The scrim a colour surface needs when authored media replaces it: the
+ * surface colour itself, at the smallest opacity that keeps every foreground
+ * role at body-text AA over any pixel. The surface's text is legible on the
+ * band colour, so an opaque scrim always passes; the solver only finds how
+ * much of the photo can still show.
+ */
+export declare function mediaScrimForColorSurface(backgroundToken: string, foreground: Readonly<Partial<Record<ForegroundRole, unknown>>>, palette: ExpandedPalette): Readonly<{
+    type: 'color';
+    color: string;
+    opacity: number;
+}> | null;
+/**
+ * Over media a gradient band is its own scrim, at the opacity its weakest stop
+ * needs to keep the foreground legible over any pixel. When any stop has no
+ * legible scrim (the foreground clashes with that stop even fully opaque) the
+ * band cannot back the foreground, so there is no scrim and authored media
+ * keeps its own presentation.
+ */
+export declare function gradientMediaScrim(input: Readonly<{
+    gradient: string;
+    stopTokens: readonly string[];
+    foreground: Readonly<Partial<Record<ForegroundRole, unknown>>>;
+    palette: ExpandedPalette;
+}>): Readonly<{
+    type: 'gradient';
+    gradient: string;
+    opacity: number;
+}> | null;
+export {};

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

@@ -100,6 +100,15 @@ 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';
+/**
+ * What a block's own section background field admits, read from its manifest.
+ * A site style's surface rule may paint a gradient or a photo; a block whose
+ * `_sectionStyles.background` refuses that paint would be dropped at render
+ * admission, so the runtime compiler paints the surface's colour equivalent
+ * instead (see `compileSectionBackground`).
+ */
+export declare const sectionBackgroundPaintValues: readonly ["color", "gradient", "image"];
+export type SectionBackgroundPaint = (typeof sectionBackgroundPaintValues)[number];
 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';
@@ -457,6 +466,11 @@ export type ResolvedBlockDesignPlan<TBlockId extends string = DesignBlockId, TPu
      * site-style card is applied; the block renders its own composition.
      */
     appliedCardRole?: CardRole | null;
+    /**
+     * The section background paints the block admits, carried from its
+     * capability. Absent (legacy JS-shaped plans) means every paint.
+     */
+    appliedSectionBackgroundPaints?: readonly SectionBackgroundPaint[];
     appliedSectionHeight: SectionHeightIntent;
     appliedHeroLegibility: HeroLegibilityStrategy;
     appliedImageSurfaceTreatment: ImageSurfaceTreatment;
@@ -496,6 +510,8 @@ export type DesignedBlockDesignCapabilityInput = Readonly<{
     sectionSurfaces: 'supported' | 'unsupported';
     /** Rich backgrounds require an explicit block-level legibility contract. */
     richBackgrounds?: 'supported';
+    /** Section background paints the block admits; absent means all of them. */
+    sectionBackgroundPaints?: readonly SectionBackgroundPaint[];
     contentFrames: FrameCapability;
     cardRoles: CardRoleCapability;
     sectionHeights?: NonEmptyReadonlyArray<SectionHeightIntent>;
@@ -516,6 +532,7 @@ export type DesignedBlockDesignCapability = Readonly<{
     looks: 'supported' | 'not-applicable';
     sectionSurfaces: 'supported' | 'unsupported';
     richBackgrounds?: 'supported';
+    sectionBackgroundPaints: readonly SectionBackgroundPaint[];
     contentFrames: FrameCapability;
     cardRoles: CardRoleCapability;
     sectionHeights: NonEmptyReadonlyArray<SectionHeightIntent>;

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

@@ -0,0 +1,43 @@
+import type { Theme } from '../schema';
+import type { ButtonSystem } from '../buttons/types';
+/**
+ * What an element paints behind its own content.
+ *
+ * - `solid`: a palette token. The element is a surface: it publishes the
+ *   foreground contract and the button context resolved against that token.
+ * - `gradient`: a surface whose colour cannot be proven for buttons; it still
+ *   publishes its foreground and resets the button context.
+ * - `transparent`: the element paints nothing, so it hands back whatever the
+ *   surrounding surface published (used where a treatment turns a card class
+ *   into a boxless row).
+ */
+export type OpaqueSurfacePaint = Readonly<{
+    kind: 'solid';
+    token: string;
+    foregroundToken?: string;
+}> | Readonly<{
+    kind: 'gradient';
+    foregroundToken?: string;
+}> | Readonly<{
+    kind: 'transparent';
+}>;
+/**
+ * What a surface needs from its theme to publish its contract. Both the full
+ * theme runtime and the SDK theme bridge build one, so every runtime publishes
+ * the same contract for the same paint.
+ */
+export type OpaqueSurfaceContext = Readonly<{
+    /** Token name → opaque hex. */
+    palette: Readonly<Record<string, string>>;
+    /** Without one, nested surfaces reset the band's button context. */
+    buttonSystem: ButtonSystem | undefined;
+    linkHoverToken?: string;
+}>;
+export declare function opaqueSurfaceContextFromTheme(theme: Theme): OpaqueSurfaceContext;
+/**
+ * The declarations that make an element own its surface: `color`, every
+ * `--rb-surface-*` role and every `--rb-action-*` variable. Card roles and
+ * opaque block panels both publish through this, so a nested surface can never
+ * inherit a band's light text or its band-resolved buttons.
+ */
+export declare function opaqueSurfaceDeclarations(paint: OpaqueSurfacePaint, context: OpaqueSurfaceContext): readonly string[];