@riverbankcms/sdk 0.129.0 → 0.130.0

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

@@ -0,0 +1,281 @@
+import type { Theme } from '../schema';
+import { type HeaderBrandPresentationPlan, type HeaderBrandPresentationSelection, type LogoAccommodationOption } from './logoBranding';
+import { type HeaderLayoutId, type HeaderLogoContext, type HeaderStyleId } from './headerLayoutTypes';
+export declare function resolveHeaderBrandPresentation(input: Readonly<{
+    logo: HeaderLogoContext;
+    accommodations: readonly LogoAccommodationOption[];
+    allowDisplayFallback?: boolean;
+}>): HeaderBrandPresentationPlan;
+export declare function requireHeaderBrandPresentationSelection(plan: HeaderBrandPresentationPlan): HeaderBrandPresentationSelection;
+/**
+ * Starts each compilation from the generated theme's header branch, then
+ * clears optional nested styling fields that would otherwise leak from a
+ * different header selection.
+ */
+export declare function baseHeader(theme: Theme): Theme['header'];
+export declare const headerLayoutCatalog: readonly [{
+    readonly id: HeaderLayoutId;
+    readonly label: "Classic";
+    readonly description: "Logo and navigation in one practical horizontal row.";
+    readonly variant: "classic";
+    readonly defaultPositioning: "sticky";
+    readonly shrinkOnScroll: false;
+    readonly logoAccommodations: readonly [{
+        readonly pattern: "title-only";
+        readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["title-only"];
+        readonly size: "compact";
+    }, {
+        readonly pattern: "inline-wordmark";
+        readonly supportedShapes: readonly ["horizontal"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "standard";
+        readonly maxDensity: "detailed";
+    }, {
+        readonly pattern: "inline-mark-with-title";
+        readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["no-text"];
+        readonly supportedDisplayModes: readonly ["logo-plus-title"];
+        readonly size: "compact";
+        readonly maxDensity: "simple";
+    }, {
+        readonly pattern: "popout-badge";
+        readonly supportedShapes: readonly ["square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "display";
+        readonly providesBacking: true;
+    }, {
+        readonly pattern: "logo-plate";
+        readonly supportedShapes: readonly ["square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "display";
+        readonly providesBacking: true;
+    }];
+    readonly openingRequirement: "none";
+}, {
+    readonly id: HeaderLayoutId;
+    readonly label: "Centered";
+    readonly description: "Logo centered above a balanced navigation row.";
+    readonly variant: "centered";
+    readonly defaultPositioning: "static";
+    readonly shrinkOnScroll: false;
+    readonly logoAccommodations: readonly [{
+        readonly pattern: "title-only";
+        readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["title-only"];
+        readonly size: "compact";
+    }, {
+        readonly pattern: "inline-wordmark";
+        readonly supportedShapes: readonly ["horizontal"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "standard";
+        readonly maxDensity: "detailed";
+    }, {
+        readonly pattern: "inline-mark-with-title";
+        readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["no-text"];
+        readonly supportedDisplayModes: readonly ["logo-plus-title"];
+        readonly size: "compact";
+        readonly maxDensity: "simple";
+    }, {
+        readonly pattern: "centered-masthead";
+        readonly supportedShapes: readonly ["square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "display";
+        readonly providesBacking: true;
+    }, {
+        readonly pattern: "centered-badge";
+        readonly supportedShapes: readonly ["square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "display";
+        readonly providesBacking: true;
+    }];
+    readonly openingRequirement: "none";
+}, {
+    readonly id: HeaderLayoutId;
+    readonly label: "Floating";
+    readonly description: "Detached header chrome that sits over the opening section.";
+    readonly variant: "floating";
+    readonly defaultPositioning: "sticky";
+    readonly shrinkOnScroll: true;
+    readonly logoAccommodations: readonly [{
+        readonly pattern: "title-only";
+        readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["title-only"];
+        readonly size: "compact";
+    }, {
+        readonly pattern: "inline-wordmark";
+        readonly supportedShapes: readonly ["horizontal"];
+        readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "standard";
+        readonly maxDensity: "detailed";
+    }, {
+        readonly pattern: "inline-mark-with-title";
+        readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+        readonly supportedTextPresence: readonly ["no-text"];
+        readonly supportedDisplayModes: readonly ["logo-plus-title"];
+        readonly size: "compact";
+        readonly maxDensity: "simple";
+    }, {
+        readonly pattern: "inline-logo-only";
+        readonly supportedShapes: readonly ["square"];
+        readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+        readonly supportedDisplayModes: readonly ["logo-only"];
+        readonly size: "compact";
+        readonly providesBacking: false;
+    }];
+    readonly openingRequirement: "requires-image-hero-with-contrast-overlay";
+}];
+export declare const headerStyleCatalog: readonly [{
+    readonly id: HeaderStyleId;
+    readonly label: "Minimal";
+    readonly description: "Quiet surface with simple color-change navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Seamless";
+    readonly description: "Borderless surface with underline hover for a quieter page transition.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Soft Bar";
+    readonly description: "Soft tinted surface with gentle pill hover states.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Pill Nav";
+    readonly description: "A calm pill navigation rail over a neutral header.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Bar";
+    readonly description: "Solid brand surface with high-contrast navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "brand-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Underline";
+    readonly description: "Brand surface with underline-grow navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "brand-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Pill";
+    readonly description: "Solid brand surface with rounded active and hover states.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "brand-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Capsule";
+    readonly description: "Solid brand chrome designed as a floating capsule, with quiet-caps nav, a soft pill active state, and an inverted CTA pill.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "quiet-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Serif Line";
+    readonly description: "Typographic logo treatment with understated underline navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "heading";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Flat Tabs";
+    readonly description: "Flat block hover and active states with a Swiss utility feel.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "quiet-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Glass";
+    readonly description: "Translucent chrome with frosted navigation backing.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Clear Split";
+    readonly description: "Floating logo with transparent navigation and no shared shell.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+    readonly openingForegroundTarget: "all";
+    readonly scrollTreatment: "contrast-glass";
+    readonly interactionPalette: Readonly<{
+        id: "interaction-palette";
+        label: string;
+        options: readonly [import("../../../blocks/src/index").HeaderInteractionPaletteOption, ...import("../../../blocks/src/index").HeaderInteractionPaletteOption[]];
+        defaultOptionId: "accent" | "primary" | "secondary";
+    }>;
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Soft Shell";
+    readonly description: "Floating rounded shell with soft pill navigation states.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Split Glass";
+    readonly description: "Logo floats independently while the navigation sits in a glass rail.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "quiet-caps";
+    readonly openingForegroundTarget: "brand-only";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Split Pill";
+    readonly description: "Logo floats independently with a soft pill-backed navigation rail.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navTypography: "heading";
+    readonly openingForegroundTarget: "brand-only";
+}];
+export declare const headerLayoutsById: Map<HeaderLayoutId, Readonly<{
+    id: HeaderLayoutId;
+    label: string;
+    description: string;
+    variant: import("../../../blocks/src/index").ThemeHeader["variant"];
+    defaultPositioning: import("../../../blocks/src/index").ThemeHeader["positioning"];
+    shrinkOnScroll: boolean;
+    logoAccommodations: readonly LogoAccommodationOption[];
+    openingRequirement: import("../../../blocks/src/index").HeaderOpeningRequirement;
+}>>;
+export declare const headerStylesById: Map<HeaderStyleId, Readonly<{
+    id: HeaderStyleId;
+    label: string;
+    description: string;
+    supportedLayoutIds: readonly HeaderLayoutId[];
+    navTypography: import("../../../blocks/src/index").HeaderStyleNavTypography;
+    openingForegroundTarget?: "brand-only" | "all";
+    scrollTreatment?: "contrast-glass";
+    interactionPalette?: import("../../../blocks/src/index").HeaderInteractionPaletteOptionGroup;
+}>>;
+export declare const headerStyleCompatibilityOrder: {
+    readonly classic: readonly ["minimal", "fine-line", "soft-bar", "pill-nav", "brand-bar", "brand-underline", "brand-pill", "brand-capsule", "serif-line", "flat-tabs"];
+    readonly centered: readonly ["minimal", "fine-line", "soft-bar", "pill-nav", "brand-bar", "brand-pill", "serif-line", "flat-tabs"];
+    readonly floating: readonly ["glass", "minimal-surface", "split-glass", "split-pill", "soft-shell", "brand-pill"];
+};
+export declare const headerStyleRepairOrder: {
+    readonly 'brand-bar': readonly ["brand-bar", "brand-pill", "minimal"];
+    readonly 'brand-underline': readonly ["brand-underline", "serif-line", "fine-line", "minimal"];
+    readonly 'brand-pill': readonly ["brand-pill", "brand-bar", "minimal"];
+    readonly 'brand-capsule': readonly ["brand-capsule", "brand-pill", "brand-bar", "minimal"];
+    readonly 'pill-nav': readonly ["pill-nav", "soft-bar", "minimal"];
+    readonly 'flat-tabs': readonly ["flat-tabs", "pill-nav", "minimal"];
+    readonly 'serif-line': readonly ["serif-line", "fine-line", "minimal"];
+    readonly glass: readonly ["glass", "soft-shell", "fine-line", "minimal-surface", "minimal"];
+    readonly 'soft-shell': readonly ["soft-shell", "soft-bar", "minimal"];
+    readonly 'minimal-surface': readonly ["minimal-surface", "minimal"];
+    readonly 'split-glass': readonly ["split-glass", "glass", "minimal-surface"];
+    readonly 'split-pill': readonly ["split-pill", "soft-shell", "brand-pill"];
+    readonly 'fine-line': readonly ["fine-line", "minimal"];
+    readonly 'soft-bar': readonly ["soft-bar", "minimal"];
+    readonly minimal: readonly ["minimal"];
+};

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

@@ -0,0 +1,13 @@
+import type { HeaderBrandPresentationSelection } from './logoBranding';
+import { type HeaderLayoutDefinition, type HeaderLayoutId, type HeaderLayoutStyleResolution, type HeaderLayoutStyleSelection, type HeaderLogoContext, type HeaderStyleDefinition, type HeaderStyleId } from './headerLayoutTypes';
+export declare function getHeaderLayout(id: HeaderLayoutId): HeaderLayoutDefinition;
+export declare function headerLayoutRequiresImageHeroOpening(layout: HeaderLayoutDefinition): boolean;
+export declare function resolveHeaderBrandPresentationForLayout(input: Readonly<{
+    layout: HeaderLayoutDefinition;
+    logo: HeaderLogoContext;
+}>): HeaderBrandPresentationSelection;
+export declare function getHeaderStyle(id: HeaderStyleId): HeaderStyleDefinition;
+export declare function isHeaderStyleCompatibleWithLayout(style: HeaderStyleDefinition, layoutId: HeaderLayoutId): boolean;
+export declare function getCompatibleHeaderStyleIds(layoutId: HeaderLayoutId): readonly HeaderStyleId[];
+export declare function deriveNearestCompatibleHeaderStyle(styleId: HeaderStyleId, layoutId: HeaderLayoutId, allowedStyleIds?: readonly HeaderStyleId[]): HeaderStyleId;
+export declare function resolveHeaderLayoutStyleSelection(selection: HeaderLayoutStyleSelection): HeaderLayoutStyleResolution;

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

@@ -0,0 +1,6 @@
+export * from './headerLayoutTypes';
+export * from './headerLayoutCatalog';
+export * from './headerLayoutResolution';
+export * from './headerStyleCompiler';
+export declare const guaranteedFallbackHeaderLayoutId: import("../../../blocks/src/index").HeaderLayoutId;
+export declare const guaranteedFallbackHeaderStyleId: import("../../../blocks/src/index").HeaderStyleId;

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

@@ -0,0 +1,142 @@
+import type { ThemeHeader } from '../schema';
+import type { HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
+import type { HeaderOpeningForeground } from './headerOpeningForeground';
+import { type BrandDisplayMode, type LogoAccommodationOption, type LogoFacts, type LogoSizePolicy } from './logoBranding';
+import { type Brand } from './types';
+export declare const headerLayoutIdValues: readonly ["classic", "centered", "floating"];
+export type HeaderLayoutIdValue = (typeof headerLayoutIdValues)[number];
+export type HeaderLayoutId = Brand<HeaderLayoutIdValue, 'HeaderLayoutId'>;
+export declare function asHeaderLayoutId(value: HeaderLayoutIdValue): HeaderLayoutId;
+export type PersistedHeaderLayoutIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderLayoutId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLayoutId(value: string): Exclude<PersistedHeaderLayoutIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLayoutId(value: string | null | undefined): PersistedHeaderLayoutIdParseResult;
+export declare const headerStyleIdValues: readonly ["minimal", "fine-line", "soft-bar", "pill-nav", "brand-bar", "brand-underline", "brand-pill", "brand-capsule", "serif-line", "flat-tabs", "glass", "minimal-surface", "soft-shell", "split-glass", "split-pill"];
+export type HeaderStyleIdValue = (typeof headerStyleIdValues)[number];
+export type HeaderStyleId = Brand<HeaderStyleIdValue, 'HeaderStyleId'>;
+export declare function asHeaderStyleId(value: HeaderStyleIdValue): HeaderStyleId;
+export type PersistedHeaderStyleIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderStyleId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderStyleId(value: string): Exclude<PersistedHeaderStyleIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderStyleId(value: string | null | undefined): PersistedHeaderStyleIdParseResult;
+export type HeaderLayoutDefinition = Readonly<{
+    id: HeaderLayoutId;
+    label: string;
+    description: string;
+    variant: ThemeHeader['variant'];
+    defaultPositioning: ThemeHeader['positioning'];
+    shrinkOnScroll: boolean;
+    logoAccommodations: readonly LogoAccommodationOption[];
+    openingRequirement: HeaderOpeningRequirement;
+}>;
+export type HeaderStyleDefinition = Readonly<{
+    id: HeaderStyleId;
+    label: string;
+    description: string;
+    supportedLayoutIds: readonly HeaderLayoutId[];
+    navTypography: HeaderStyleNavTypography;
+    openingForegroundTarget?: 'brand-only' | 'all';
+    scrollTreatment?: 'contrast-glass';
+    interactionPalette?: HeaderInteractionPaletteOptionGroup;
+}>;
+export type HeaderLayoutStyleSelection = Readonly<{
+    layoutId: HeaderLayoutId;
+    styleId: HeaderStyleId;
+}>;
+export type HeaderLayoutStyleRepair = Readonly<{
+    requested: HeaderLayoutStyleSelection;
+    resolved: HeaderLayoutStyleSelection;
+    reason: 'style-incompatible-with-layout';
+}>;
+export type HeaderLayoutStyleResolution = Readonly<{
+    kind: 'valid';
+    selection: HeaderLayoutStyleSelection;
+    layout: HeaderLayoutDefinition;
+    style: HeaderStyleDefinition;
+}> | Readonly<{
+    kind: 'repaired';
+    selection: HeaderLayoutStyleSelection;
+    layout: HeaderLayoutDefinition;
+    style: HeaderStyleDefinition;
+    repair: HeaderLayoutStyleRepair;
+}>;
+export type HeaderOpeningRequirement = 'none' | 'reserved-space-ok' | 'requires-image-hero-with-contrast-overlay';
+export type HeaderLogoShape = 'none' | 'text-only' | 'horizontal' | 'square' | 'tall';
+export type HeaderLogoDimensions = Readonly<{
+    width: number | null;
+    height: number | null;
+}>;
+export declare function deriveHeaderLogoShapeFromDimensions({ width, height, }: HeaderLogoDimensions): HeaderLogoShape;
+export type HeaderStyleNavTypography = 'plain' | 'heading' | 'quiet-caps' | 'brand-caps';
+export type HeaderOpeningSectionContext = Readonly<{
+    kind: 'unknown';
+    canAdjust: false;
+}> | Readonly<{
+    kind: 'plain';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'page-background';
+    canAdjust: true;
+}> | Readonly<{
+    kind: 'color-section';
+    contrast: 'light' | 'dark' | 'unknown';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'gradient-section';
+    contrast: 'light' | 'dark' | 'unknown';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'dynamic-media';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'image-hero';
+    hasContrastOverlay: boolean;
+    hasTopSpacing: boolean;
+    canAdjust: boolean;
+}>;
+export type HeaderLogoPreferences = Readonly<{
+    brandDisplayMode?: BrandDisplayMode;
+    sizePolicy?: LogoSizePolicy;
+}>;
+export type HeaderLogoShapeContext = HeaderLogoPreferences & Readonly<{
+    kind?: 'shape';
+    shape: HeaderLogoShape;
+}>;
+export type HeaderLogoFactsContext = HeaderLogoPreferences & Readonly<{
+    kind: 'facts';
+    facts: LogoFacts;
+}>;
+export type HeaderLogoContext = HeaderLogoShapeContext | HeaderLogoFactsContext;
+export declare const defaultHeaderLogoContext: HeaderLogoContext;
+export type HeaderSelectionContext = Readonly<{
+    openingSection: HeaderOpeningSectionContext;
+    openingForeground: HeaderOpeningForeground;
+    logo: HeaderLogoContext;
+    navigation: Readonly<{
+        itemCount: number;
+    }>;
+    cta: Readonly<{
+        importance: 'low' | 'medium' | 'high';
+    }>;
+    banner: Readonly<{
+        persistentVisibility: 'none' | 'possible' | 'visible';
+    }>;
+}>;

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

@@ -0,0 +1,6 @@
+import type { NavLinkStyle } from '../navigation/types';
+import type { HeaderStyleNavTypography } from './headerLayoutTypes';
+export declare function minimalNavLinkStyle(colorToken: string, hoverColorToken?: string, typography?: HeaderStyleNavTypography): NavLinkStyle;
+export declare function underlineNavLinkStyle(colorToken: string, underlineColorToken?: string, typography?: HeaderStyleNavTypography): NavLinkStyle;
+export declare function pillNavLinkStyle(colorToken: string, backgroundToken?: string, opacity?: number, typography?: HeaderStyleNavTypography): NavLinkStyle;
+export declare function flatTabNavLinkStyle(colorToken: string, typography?: HeaderStyleNavTypography): NavLinkStyle;

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

@@ -1,6 +1,6 @@
 import type { Theme } from '../schema';
 import { type ThemeColorToken } from '../tokens';
-import type { HeaderSelectionContext, HeaderStyleDefinition } from './headerLooks';
+import type { HeaderStyleDefinition } from './headerLayoutTypes';
 export type HeaderOpeningForeground = Readonly<{
     kind: 'known';
     token: ThemeColorToken;
@@ -8,15 +8,18 @@ export type HeaderOpeningForeground = Readonly<{
 }> | Readonly<{
     kind: 'unknown';
 }>;
+export type HeaderOpeningForegroundContext = Readonly<{
+    openingForeground: HeaderOpeningForeground;
+}>;
 export type HeaderStyleAvailability = Readonly<{
     kind: 'available';
 }> | Readonly<{
     kind: 'unavailable';
     reason: 'requires-known-opening-foreground';
 }>;
-export declare function headerStyleAvailability(style: HeaderStyleDefinition, context: Partial<HeaderSelectionContext> | undefined): HeaderStyleAvailability;
+export declare function headerStyleAvailability(style: HeaderStyleDefinition, context: Partial<HeaderOpeningForegroundContext> | undefined): HeaderStyleAvailability;
 export declare function headerStyleAvailabilityReasonLabel(reason: Extract<HeaderStyleAvailability, {
     kind: 'unavailable';
 }>['reason']): string;
-export declare function applyOpeningForeground(theme: Theme, header: Theme['header'], style: HeaderStyleDefinition, context: Partial<HeaderSelectionContext> | undefined): Theme['header'];
-export declare function applyPageOpeningForegroundToTheme(theme: Theme, style: HeaderStyleDefinition | null | undefined, context: Partial<HeaderSelectionContext> | undefined): Theme;
+export declare function applyOpeningForeground(theme: Theme, header: Theme['header'], style: HeaderStyleDefinition, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme['header'];
+export declare function applyPageOpeningForegroundToTheme(theme: Theme, style: HeaderStyleDefinition | null | undefined, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme;

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

@@ -1,5 +1,5 @@
 import type { BlockDesignPlan, DesignBlockId, ResolvedBlockDesignPlan } from './types';
-import type { HeaderLookId, HeaderOpeningSectionContext } from './headerLooks';
+import type { HeaderLayoutStyleSelection, HeaderOpeningSectionContext } from './headerLayoutStyles';
 import type { HeaderOpeningForeground } from './headerOpeningForeground';
 export type HeaderOpeningSectionRepair = 'promote-opening-hero-surface' | 'add-opening-contrast-overlay' | 'add-opening-top-spacing';
 export type HeaderOpeningSectionPlan<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
@@ -13,7 +13,7 @@ export type HeaderOpeningContentSnapshot = Readonly<{
 }>;
 export declare function planGeneratedHeaderOpeningSection<TBlockId extends DesignBlockId>(input: Readonly<{
     plan: readonly BlockDesignPlan<TBlockId>[];
-    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedHeaderSelections: readonly HeaderLayoutStyleSelection[];
 }>): HeaderOpeningSectionPlan<TBlockId>;
 export declare function deriveHeaderOpeningSectionContextFromContent(input: HeaderOpeningContentSnapshot): HeaderOpeningSectionContext;
 export declare function deriveHeaderOpeningForegroundFromContent(input: HeaderOpeningContentSnapshot): HeaderOpeningForeground;

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

@@ -0,0 +1,3 @@
+import type { Theme } from '../schema';
+import { type HeaderLayoutStyleResolution } from './headerLayoutTypes';
+export declare function compileHeaderLayoutStyleSelection(theme: Theme, resolution: HeaderLayoutStyleResolution): Theme['header'];

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

@@ -0,0 +1,14 @@
+import type { SectionStylesOverride } from '../schema';
+import { type ImageSurfaceMotion, type ImageSurfaceTreatment } from './types';
+type ImageBackground = Extract<NonNullable<SectionStylesOverride['background']>, {
+    type: 'image';
+}>;
+type Foreground = Readonly<{
+    textColor: NonNullable<ImageBackground['textColor']>;
+    headingColor: NonNullable<ImageBackground['headingColor']>;
+    linkColor: NonNullable<ImageBackground['linkColor']>;
+    supportingColor: NonNullable<ImageBackground['supportingColor']>;
+}>;
+export declare function withImageSurfaceMotion(background: ImageBackground, motion: ImageSurfaceMotion): ImageBackground;
+export declare function compileImageSurfaceTreatmentBackground(background: ImageBackground, treatment: ImageSurfaceTreatment, foreground: Partial<Foreground> | undefined): ImageBackground | null;
+export {};

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

@@ -13,7 +13,7 @@ export * from './designState';
 export * from './footerLooks';
 export * from './generatedSchemas';
 export * from './generatedDesignPipeline';
-export * from './headerLooks';
+export * from './headerLayoutStyles';
 export * from './headerInteractionPalette';
 export * from './headerOpeningForeground';
 export * from './headerOpeningSection';

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

@@ -2,9 +2,9 @@ import type { PageDesignEditorReadModel } from './pageDesignEditorModel';
 import { type Theme } from '../schema';
 import { type ButtonStyleSelection } from '../buttons/styles';
 import { type CuratedSiteStyle } from './curatedSiteStyles';
-import { type FooterLookId, type FooterSelectionResult } from './footerLooks';
-import { type HeaderSelectionIdentity, type SiteThemeCompilationPlan } from './compilationPlan';
-import { type HeaderLayoutId, type HeaderLookId, type HeaderSelectionResult, type HeaderStyleId } from './headerLooks';
+import { type FooterLookId } from './footerLooks';
+import type { SiteThemeCompilationPlan } from './compilationPlan';
+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';
@@ -30,7 +30,7 @@ export declare const previewCustomizePurpose: "preview-customize";
 /**
  * Compiles a curated Site Style into a persisted Theme payload using the site
  * style's defaults for the Style configurator selections. Thin wrapper around
- * `compileSiteThemeFromSelections` with the style's default curated palette.
+ * `compileReplacementSiteThemeFromSelections` with the style's default curated palette.
  */
 export declare function compileCuratedSiteStyleTheme(siteStyle: CuratedSiteStyle): CuratedSiteStyleTheme;
 export declare function defaultConcretePaletteForSiteStyle(siteStyle: CuratedSiteStyle): Theme['palette'];
@@ -39,6 +39,11 @@ 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;
@@ -55,62 +60,30 @@ export type UpdateSiteThemeSelectionsInput = SiteThemeSelectionsCommonInput & Re
     compilationPlan: Extract<SiteThemeCompilationPlan, {
         kind: 'update-selection';
     }>;
-}>;
-export type SiteThemeSelectionsInput = SiteThemeSelectionsCommonInput & Readonly<{
-    compilationPlan: SiteThemeCompilationPlan;
+    currentHeaderSelection: HeaderLayoutStyleSelection;
 }>;
 type ResolvedSiteThemeSelections = Readonly<{
     buttonStyleSelection: ButtonStyleSelection;
-    headerLookId: HeaderLookId | null;
-    headerLayoutId: HeaderLayoutId | null;
-    headerStyleId: HeaderStyleId | null;
+    headerSelection: HeaderLayoutStyleSelection;
     footerLookId: FooterLookId | null;
 }>;
 type ReplacementResolvedSiteThemeSelections = ResolvedSiteThemeSelections & Readonly<{
-    headerLayoutId: HeaderLayoutId;
-    headerStyleId: HeaderStyleId;
     footerLookId: FooterLookId;
 }>;
 type SiteThemeSelectionsBaseResult<TResolvedSelections extends ResolvedSiteThemeSelections> = Readonly<{
     theme: CuratedSiteStyleTheme;
     requestedSelections: Readonly<{
-        headerLookId: HeaderLookId | null;
-        headerLayoutId: HeaderLayoutId | null;
-        headerStyleId: HeaderStyleId | null;
+        headerSelection: HeaderLayoutStyleSelection | null;
         footerLookId: FooterLookId | null;
     }>;
     resolvedSelections: TResolvedSelections;
-    headerCompilation: Readonly<{
-        kind: 'preserved';
-        selection: HeaderSelectionIdentity;
-    }> | Readonly<{
-        kind: 'recompiled';
-        result: HeaderSelectionResult;
-    }>;
-    footerCompilation: Readonly<{
-        kind: 'preserved';
-        footerLookId: FooterLookId | null;
-    }> | Readonly<{
-        kind: 'applied-look';
-        result: FooterSelectionResult;
-    }>;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
 }>;
 export type ReplacementSiteThemeSelectionsResult = SiteThemeSelectionsBaseResult<ReplacementResolvedSiteThemeSelections>;
 export type UpdateSiteThemeSelectionsResult = SiteThemeSelectionsBaseResult<ResolvedSiteThemeSelections>;
 export type SiteThemeSelectionsResult = ReplacementSiteThemeSelectionsResult | UpdateSiteThemeSelectionsResult;
-/**
- * High-level, site-style-aware compiler. Resolves the user's button style and
- * palette values into theme tokens. Palette authority is always supplied as a
- * complete concrete value.
- *
- * Returns the resolved IDs so the caller can persist auto-pick decisions, plus
- * any fallback warnings the UI can surface as "we changed your selection"
- * notices.
- */
-export declare function compileSiteThemeFromSelections(input: ReplacementSiteThemeSelectionsInput): ReplacementSiteThemeSelectionsResult;
-export declare function compileSiteThemeFromSelections(input: UpdateSiteThemeSelectionsInput): UpdateSiteThemeSelectionsResult;
-export declare function compileSiteThemeFromSelections(input: SiteThemeSelectionsInput): SiteThemeSelectionsResult;
+export declare function compileReplacementSiteThemeFromSelections(input: ReplacementSiteThemeSelectionsInput): ReplacementSiteThemeSelectionsResult;
+export declare function compileUpdatedSiteThemeFromSelections(input: UpdateSiteThemeSelectionsInput): UpdateSiteThemeSelectionsResult;
 export declare function siteStyleIdFromTheme(theme: Pick<Theme, 'siteStyleId'> | null | undefined): SiteStyleId | null;
 export type EditorModelRuntimeLookOverride<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
     kind: 'pinned';