@riverbankcms/sdk 0.62.2 → 0.64.0

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

@@ -12,7 +12,7 @@ export * from "./responsive/breakpoints";
 export { ThemeFontLoader, ThemeFontLoaderFromTheme, getThemeFontLoadingOptions, type ThemeFontLoadingOptions, type ThemeFontLoaderFromThemeProps, } from "./ThemeFontLoader";
 export { ThemeScopeCore, type ThemeScopeCoreProps } from "./ThemeScopeCore";
 export { type ThemeDataAttrs } from "./themeScopeUtils";
-export { getStandaloneHeaderShellClassName, renderSiteTopChrome, type SiteChromeLayoutNodes, type SiteTopShellBehavior, } from "./siteChrome";
+export { getStandaloneHeaderShellClassName, planSiteTopShell, renderSiteTopChrome, type SiteChromeLayoutNodes, type SiteTopShellPlan, type SiteTopShellBehavior, } from "./siteChrome";
 export { buildThemeRuntime } from "./runtime/buildThemeRuntime";
 export { buildThemeRuntimeFromBridge, type ThemeBridgeConfigMinimal, } from "./runtime/buildThemeRuntimeFromBridge";
 export type { CornerStyle, ShadowSize, TextTransform, FontWeight, HoverTransform, HoverColor, GradientStyle, GradientSharpness, GradientDirection, ButtonVariant, ButtonSystem, } from "./buttons/types";

package/dist/_dts/theme-core/src/palette/variants/types.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { type StyleTags } from '../../site-styles/styleTags';
+import { PALETTE_TOKEN_NAMES, paletteTokenNameSchema, type PaletteTokenName } from '../../tokens/themeColorTokens';
+export { PALETTE_TOKEN_NAMES, paletteTokenNameSchema, type PaletteTokenName, };
 /**
  * Branded ID for a palette variant in the curated library. Shape matches the
  * `Brand<T, TBrand>` convention in `site-styles/types.ts`. Use the helper at
@@ -10,27 +12,6 @@ export type PaletteVariantId<T extends string = string> = T & {
 };
 export declare function asPaletteVariantId<const T extends string>(value: T): PaletteVariantId<T>;
 export declare const paletteVariantIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<PaletteVariantId<string>, string>>;
-/**
- * Known palette role token names. Closed union so unknown tokens can't be
- * persisted via `paletteOverrides`. Add a new role here intentionally.
- */
-export declare const PALETTE_TOKEN_NAMES: readonly ["primary", "primaryForeground", "secondary", "accent", "success", "warning", "destructive", "background", "surface", "surfaceAlt", "muted", "text", "border"];
-export type PaletteTokenName = (typeof PALETTE_TOKEN_NAMES)[number];
-export declare const paletteTokenNameSchema: z.ZodEnum<{
-    success: "success";
-    text: "text";
-    surface: "surface";
-    warning: "warning";
-    border: "border";
-    background: "background";
-    primary: "primary";
-    secondary: "secondary";
-    primaryForeground: "primaryForeground";
-    accent: "accent";
-    destructive: "destructive";
-    surfaceAlt: "surfaceAlt";
-    muted: "muted";
-}>;
 export type HexColor = string & {
     readonly __brand: 'HexColor';
 };

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

@@ -1,4 +1,4 @@
-import type { BlockAppearancePreset, BlockAppearancePresetTarget, SiteChromeAppearancePreset, SiteChromeAppearancePresetTarget } from './appearancePresetTypes';
+import type { AppearancePresetTarget, BlockAppearancePreset } from './appearancePresetTypes';
 export declare const appearancePresets: readonly [{
     readonly kind: "block-design";
     readonly id: "hero-immersive-image";
@@ -446,70 +446,6 @@ export declare const appearancePresets: readonly [{
         readonly transitionAfter: "none";
         readonly emphasis: "high";
     };
-}, {
-    readonly kind: "site-chrome";
-    readonly id: "header-clean-base";
-    readonly target: "site-header";
-    readonly label: "Clean base header";
-    readonly header: {
-        readonly surface: {
-            readonly kind: "neutral-solid";
-            readonly token: "surface";
-            readonly textColorToken: "text";
-        };
-        readonly navTreatment: "minimal";
-        readonly dropdownTreatment: "surface";
-        readonly ctaTreatment: "default";
-        readonly behavior: "default";
-    };
-}, {
-    readonly kind: "site-chrome";
-    readonly id: "site-header-brand-solid-inverted-cta";
-    readonly target: "site-header";
-    readonly label: "Brand solid header with inverted CTA";
-    readonly header: {
-        readonly surface: {
-            readonly kind: "brand-solid";
-            readonly token: "primary";
-            readonly textColorToken: "primaryForeground";
-        };
-        readonly navTreatment: "uppercase-underline";
-        readonly dropdownTreatment: "matched-solid";
-        readonly ctaTreatment: "inverted";
-        readonly behavior: "sticky-shrink";
-    };
-}, {
-    readonly kind: "site-chrome";
-    readonly id: "footer-muted-grounding";
-    readonly target: "site-footer";
-    readonly label: "Muted grounding footer";
-    readonly footer: {
-        readonly kind: "grounding";
-        readonly surface: "muted-band";
-        readonly emphasis: "low";
-    };
-}, {
-    readonly kind: "site-chrome";
-    readonly id: "site-footer-brand-two-band";
-    readonly target: "site-footer";
-    readonly label: "Two-band brand footer";
-    readonly footer: {
-        readonly kind: "brand-two-band";
-        readonly surface: {
-            readonly token: "primary";
-            readonly shade: "800";
-            readonly textColorToken: "primaryForeground";
-        };
-        readonly bottomBand: {
-            readonly token: "primary";
-            readonly shade: "900";
-            readonly textColorToken: "primaryForeground";
-        };
-        readonly emphasis: "high";
-    };
 }];
-export type BlockAppearancePresetBlockKind = Extract<(typeof appearancePresets)[number], {
-    kind: 'block-design';
-}>['blockKinds'][number];
-export declare function getAppearancePresetsForTarget(target: SiteChromeAppearancePresetTarget): readonly SiteChromeAppearancePreset[];
-export declare function getAppearancePresetsForTarget(target: BlockAppearancePresetTarget): readonly BlockAppearancePreset[];
+export type BlockAppearancePresetBlockKind = (typeof appearancePresets)[number]['blockKinds'][number];
+export declare function getAppearancePresetsForTarget(target: AppearancePresetTarget): readonly BlockAppearancePreset[];

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

@@ -1,6 +1,6 @@
 import type { BlockLayoutFamily } from './blockFlow';
 import type { ContentFrameIntent, EyebrowTreatment, HeroLegibilityStrategy, ImageSurfaceMotion, ImageSurfaceTreatment, NonEmptyReadonlyArray, SectionHeightIntent, SiteStyleEmphasis, SiteStyleItemSurfaceIntent, SiteStyleSectionTransitionIntent, SiteStyleSurfaceIntent, TestimonialCardTreatment, TileTreatment } from './types';
-export type AppearancePresetTarget = 'hero' | 'body-text' | 'offerings' | 'events' | 'media-text' | 'testimonials' | 'faq' | 'contact-form' | 'cta' | 'site-header' | 'site-footer';
+export type AppearancePresetTarget = 'hero' | 'body-text' | 'offerings' | 'events' | 'media-text' | 'testimonials' | 'faq' | 'contact-form' | 'cta';
 export type BlockAppearanceDesign = Readonly<{
     sectionSurface: SiteStyleSurfaceIntent;
     contentFrame: ContentFrameIntent;
@@ -39,7 +39,7 @@ export type BlockAppearanceLayoutPatch = Readonly<{
 export type BlockAppearancePreset = Readonly<{
     kind: 'block-design';
     id: string;
-    target: Exclude<AppearancePresetTarget, 'site-header' | 'site-footer'>;
+    target: AppearancePresetTarget;
     label: string;
     blockKinds: readonly string[];
     constraints?: BlockAppearancePresetConstraints;
@@ -56,64 +56,6 @@ export type BlockAppearancePreset = Readonly<{
     layoutPatches?: readonly BlockAppearanceLayoutPatch[];
     design: BlockAppearanceDesign;
 }>;
-export type HeaderSurfaceToken = 'primary' | 'secondary' | 'accent';
-export type HeaderTextColorToken = 'primaryForeground' | 'background' | 'surface' | 'text';
-export type HeaderNavTreatment = 'minimal' | 'uppercase-underline';
-export type HeaderDropdownTreatment = 'surface' | 'matched-solid';
-export type HeaderCtaTreatment = 'default' | 'primary' | 'secondary' | 'inverted' | 'outline' | 'ghost';
-export type HeaderBehavior = 'default' | 'sticky-shrink';
-export type FooterSurfaceToken = 'primary' | 'secondary' | 'accent';
-export type FooterBrandShade = 'base' | '800' | '900';
-export type FooterTextColorToken = 'primaryForeground' | 'secondaryForeground' | 'accentForeground' | 'background' | 'surface' | 'text';
-export type SiteHeaderAppearance = Readonly<{
-    surface: Readonly<{
-        kind: 'brand-solid';
-        token: HeaderSurfaceToken;
-        textColorToken: HeaderTextColorToken;
-    }> | Readonly<{
-        kind: 'neutral-solid';
-        token: 'surface' | 'background';
-        textColorToken: 'text';
-    }>;
-    navTreatment: HeaderNavTreatment;
-    dropdownTreatment: HeaderDropdownTreatment;
-    ctaTreatment: HeaderCtaTreatment;
-    behavior: HeaderBehavior;
-}>;
-export type SiteFooterAppearance = Readonly<{
-    kind: 'grounding';
-    surface: Extract<SiteStyleSurfaceIntent, 'base' | 'muted-band' | 'accent-band'>;
-    emphasis: SiteStyleEmphasis;
-}> | Readonly<{
-    kind: 'brand-two-band';
-    surface: Readonly<{
-        token: FooterSurfaceToken;
-        shade: FooterBrandShade;
-        textColorToken: FooterTextColorToken;
-    }>;
-    bottomBand: Readonly<{
-        token: FooterSurfaceToken;
-        shade: FooterBrandShade;
-        textColorToken: FooterTextColorToken;
-    }>;
-    emphasis: SiteStyleEmphasis;
-}>;
-export type SiteHeaderAppearancePreset = Readonly<{
-    kind: 'site-chrome';
-    id: string;
-    target: 'site-header';
-    label: string;
-    header: SiteHeaderAppearance;
-}>;
-export type SiteFooterAppearancePreset = Readonly<{
-    kind: 'site-chrome';
-    id: string;
-    target: 'site-footer';
-    label: string;
-    footer: SiteFooterAppearance;
-}>;
-export type SiteChromeAppearancePreset = SiteHeaderAppearancePreset | SiteFooterAppearancePreset;
-export type AppearancePreset = BlockAppearancePreset | SiteChromeAppearancePreset;
-export type SiteChromeAppearancePresetTarget = SiteChromeAppearancePreset['target'];
+export type AppearancePreset = BlockAppearancePreset;
 export type BlockAppearancePresetTarget = BlockAppearancePreset['target'];
-export declare const appearancePresetTargets: readonly ["hero", "body-text", "offerings", "events", "media-text", "testimonials", "faq", "contact-form", "cta", "site-header", "site-footer"];
+export declare const appearancePresetTargets: readonly ["hero", "body-text", "offerings", "events", "media-text", "testimonials", "faq", "contact-form", "cta"];

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

@@ -2,4 +2,4 @@ export * from './appearancePresetCatalog';
 export * from './appearancePresetResolution';
 export * from './appearancePresetTypes';
 export * from './blockAppearancePresets';
-export * from './siteChromeAppearancePresets';
+export * from './headerCtaVariants';

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

@@ -1,6 +1,8 @@
 import { type ButtonPersonalityId, type KnownButtonPersonalityId } from '../buttons/personalities';
 import { type KnownPaletteVariantId, type PaletteVariantId } from '../palette/variants';
 import type { Theme } from '../schema';
+import { type HeaderLookId } from './headerLooks';
+import { type FooterLookId } from './footerLooks';
 import { type CuratedChoice } from './curatedChoices';
 import { type AppearancePresetId, type DesignSystemTemplate, type NonEmptyReadonlyArray, type SiteStyleId } from './types';
 export declare const curatedSiteStyleIdValues: readonly ["site-style:calm-studio", "site-style:clear-professional", "site-style:warm-editorial", "site-style:bright-community", "site-style:quiet-luxury", "site-style:practical-services", "site-style:modern-wellness", "site-style:bold-launch", "site-style:south-west-twerk-school"];
@@ -39,6 +41,8 @@ export type CuratedSiteStyle = Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -60,6 +64,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -73,6 +79,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -86,6 +94,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -99,6 +109,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -112,6 +124,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -125,6 +139,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -138,6 +154,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -151,6 +169,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -164,6 +184,8 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
@@ -178,6 +200,8 @@ export declare const curatedSiteStylesById: Map<SiteStyleId, Readonly<{
     template: DesignSystemTemplate;
     themeOverrides?: CuratedSiteStyleThemeOverrides;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+    recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */

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

@@ -0,0 +1,94 @@
+import { type DesignBlockId } from './types';
+export type SiteChromeCustomizableSurface = Readonly<{
+    kind: 'site-header';
+}> | Readonly<{
+    kind: 'site-footer';
+}>;
+export type BlockCustomizableSurface = Readonly<{
+    kind: 'block';
+    blockId: DesignBlockId;
+    blockKind: string;
+}>;
+export type CustomizableSurface = BlockCustomizableSurface | SiteChromeCustomizableSurface;
+export type SiteChromePersistenceSurface = 'header' | 'footer';
+export type LookPersistenceTarget = Readonly<{
+    kind: 'page-design';
+    blockId: DesignBlockId;
+}> | Readonly<{
+    kind: 'site-chrome';
+    surface: SiteChromePersistenceSurface;
+}>;
+export type PreviewLookCustomizationCommand<TLookId> = Readonly<{
+    kind: 'inspect';
+    surface: CustomizableSurface;
+}> | Readonly<{
+    kind: 'cycle';
+    surface: CustomizableSurface;
+    direction: 'previous' | 'next';
+}> | Readonly<{
+    kind: 'select';
+    surface: CustomizableSurface;
+    lookId: TLookId;
+}> | Readonly<{
+    kind: 'clear';
+    surface: CustomizableSurface;
+}>;
+export type LookCustomizationWritePlan<TLookId> = Readonly<{
+    kind: 'no-write';
+    command: 'inspect' | 'cycle';
+}> | Readonly<{
+    kind: 'write-selection';
+    target: LookPersistenceTarget;
+    lookId: TLookId;
+}> | Readonly<{
+    kind: 'clear-selection';
+    target: LookPersistenceTarget;
+}>;
+export type SiteChromeLookRejection<TLookId, TReason> = Readonly<{
+    lookId: TLookId;
+    reasons: readonly TReason[];
+}>;
+export type SiteChromeLookDiagnostics<TLookId, TReason> = Readonly<{
+    surface: SiteChromeCustomizableSurface;
+    selectedLookId: TLookId;
+    rejected: readonly SiteChromeLookRejection<TLookId, TReason>[];
+}>;
+export type LookCustomizationOption<TLookId, TIssue> = Readonly<{
+    kind: 'available';
+    lookId: TLookId;
+    label: string;
+}> | Readonly<{
+    kind: 'selected';
+    lookId: TLookId;
+    label: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    lookId: TLookId;
+    label: string;
+    issue: TIssue;
+}>;
+export type LookCustomizationAdapterSnapshot<TSurface extends CustomizableSurface, TLookId, TIssue> = Readonly<{
+    surface: TSurface;
+    selectedLookId: TLookId | null;
+    options: readonly LookCustomizationOption<TLookId, TIssue>[];
+}>;
+export declare function uniqueLookIds<TLookId>(ids: readonly TLookId[]): readonly TLookId[];
+export type ResolvedLook<TLookId, TLook, TReason, TCompiled> = Readonly<{
+    selectedLookId: TLookId;
+    selectedLook: TLook;
+    compiled: TCompiled;
+    rejected: readonly SiteChromeLookRejection<TLookId, TReason>[];
+}>;
+export declare function resolveLook<TLookId, TLook extends Readonly<{
+    id: TLookId;
+}>, TContext, TReason, TCompiled>(input: Readonly<{
+    recommendedLookIds: readonly TLookId[];
+    guaranteedFallbackLookId: TLookId;
+    getLookOrThrow: (lookId: TLookId) => TLook;
+    context: TContext;
+    rejectReasonsForLook: (look: TLook, context: TContext) => readonly TReason[];
+    compileLook: (look: TLook) => TCompiled;
+}>): ResolvedLook<TLookId, TLook, TReason, TCompiled>;
+export declare function mergeWithDefaults<TValue extends Readonly<Record<string, unknown>>>(defaults: TValue, partial: Partial<TValue> | undefined): TValue;
+export declare function persistenceTargetForSurface(surface: CustomizableSurface): LookPersistenceTarget;
+export declare function writePlanForLookCustomizationCommand<TLookId>(command: PreviewLookCustomizationCommand<TLookId>): LookCustomizationWritePlan<TLookId>;

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

@@ -0,0 +1,59 @@
+import type { Theme } from '../schema';
+import { type SiteChromeLookDiagnostics } from './customizableSurfaces';
+import { type Brand } from './types';
+export declare const footerLookIdValues: readonly ["footer-muted-grounding", "site-footer-brand-two-band"];
+export type FooterLookIdValue = typeof footerLookIdValues[number];
+export type FooterLookId = Brand<FooterLookIdValue, 'FooterLookId'>;
+export declare function asFooterLookId(value: FooterLookIdValue): FooterLookId;
+export type FooterLookDefinition = Readonly<{
+    id: FooterLookId;
+    label: string;
+    maxRecommendedNavDensity?: Extract<FooterSelectionContext['navDensity'], 'sparse' | 'balanced'>;
+    allowedContentPresence?: readonly Exclude<FooterSelectionContext['contentPresence'], 'unknown'>[];
+    compile: (theme: Theme) => Theme['footer'];
+}>;
+export type FooterSelectionContext = Readonly<{
+    navDensity: 'unknown' | 'sparse' | 'balanced' | 'dense';
+    contentPresence: 'unknown' | 'default-footer' | 'footer-blocks' | 'default-and-blocks';
+}>;
+export type RejectedFooterLookReason = 'footer-nav-too-dense' | 'footer-content-incompatible';
+export type RejectedFooterLook = Readonly<{
+    lookId: FooterLookId;
+    reasons: readonly RejectedFooterLookReason[];
+}>;
+export type FooterSelectionResult = Readonly<{
+    selectedLookId: FooterLookId;
+    selectedLook: FooterLookDefinition;
+    footer: Theme['footer'];
+    rejected: readonly RejectedFooterLook[];
+}>;
+export type FooterLookDiagnostics = SiteChromeLookDiagnostics<FooterLookId, RejectedFooterLookReason>;
+export type FooterLookResolutionInput = Readonly<{
+    theme: Theme;
+    recommendedLookIds: readonly FooterLookId[];
+    context?: Partial<FooterSelectionContext>;
+}>;
+export declare const defaultFooterSelectionContext: FooterSelectionContext;
+export declare const guaranteedFallbackFooterLookId: FooterLookId;
+/** Uses the generated theme's footer branch as-is: the canonical calm Look. */
+declare function mutedGroundingFooter(theme: Theme): Theme['footer'];
+/** Applies a high-contrast brand band with a darker full-bleed bottom bar. */
+declare function brandTwoBandFooter(theme: Theme): Theme['footer'];
+export declare const footerLookCatalog: readonly [{
+    readonly id: FooterLookId;
+    readonly label: "Muted grounding footer";
+    readonly compile: typeof mutedGroundingFooter;
+}, {
+    readonly id: FooterLookId;
+    readonly label: "Two-band brand footer";
+    readonly maxRecommendedNavDensity: "balanced";
+    readonly allowedContentPresence: readonly ["default-footer", "default-and-blocks"];
+    readonly compile: typeof brandTwoBandFooter;
+}];
+export declare function getFooterLook(id: FooterLookId): FooterLookDefinition | null;
+export declare function findFooterLook(id: FooterLookId): FooterLookDefinition | undefined;
+export declare function getFooterLookOrThrow(id: FooterLookId): FooterLookDefinition;
+export declare function resolveFooterLook(input: FooterLookResolutionInput): FooterSelectionResult;
+export declare function footerLookDiagnosticsFromSelectionResult(result: FooterSelectionResult): FooterLookDiagnostics;
+export declare function footerLookRejectionReasonLabel(reason: RejectedFooterLookReason): string;
+export {};

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

@@ -1,6 +1,8 @@
 import { type CompositionBudgetIssue } from './compositionBudget';
 import { type ThemeV2StyleAuthority } from './designState';
 import { type PageDesignIntent } from './pageDesignIntent';
+import { type HeaderOpeningSectionRepair } from './headerOpeningSection';
+import type { HeaderOpeningSectionContext } from './headerLooks';
 import { type CompiledPageRuntime } from './runtimeCompiler';
 import { type BlockDesignCapabilityMap, type BlockDesignPlan, type DesignBlockId, type DesignRepairResult, type DesignResolutionIssue, type GeneratedPageDesignIntent, type ResolvedPageDesignPlan, type SiteStyleId } from './types';
 import type { CuratedSiteStyle } from './curatedSiteStyles';
@@ -41,6 +43,8 @@ export type GeneratedDesignPipelineSuccess<TBlockId extends DesignBlockId = Desi
     intent: GeneratedPageDesignIntent<TBlockId>;
     plan: readonly BlockDesignPlan<TBlockId>[];
     resolved: ResolvedPageDesignPlan<TBlockId>;
+    headerOpeningSectionContext: HeaderOpeningSectionContext;
+    headerOpeningSectionRepairs: readonly HeaderOpeningSectionRepair[];
     repairs: readonly DesignRepairResult<TBlockId>[];
     compositionIssues: readonly [];
     compiledRuntime: CompiledPageRuntime<TBlockId>;

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

@@ -0,0 +1,3 @@
+import type { Theme } from '../schema';
+export type HeaderCtaTreatment = 'default' | 'primary' | 'secondary' | 'inverted' | 'outline' | 'ghost';
+export declare function resolveHeaderCtaVariant(theme: Theme, treatment: HeaderCtaTreatment): string | undefined;

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

@@ -0,0 +1,155 @@
+import type { Theme } from '../schema';
+import { type SiteChromeLookDiagnostics } from './customizableSurfaces';
+import { type Brand } from './types';
+export declare const headerLookIdValues: readonly ["clean-base", "brand-solid", "editorial-line", "centered-calm", "practical-utility", "minimal-transparent", "transparent-overlay", "floating-glass"];
+export type HeaderLookIdValue = typeof headerLookIdValues[number];
+export type HeaderLookId = Brand<HeaderLookIdValue, 'HeaderLookId'>;
+export declare function asHeaderLookId(value: HeaderLookIdValue): HeaderLookId;
+export type HeaderLookVisualTreatment = 'solid-neutral' | 'solid-brand' | 'light-editorial' | 'minimal-transparent' | 'transparent-overlay' | 'floating-glass';
+export type HeaderLookLayoutBehavior = 'normal-flow' | 'sticky' | 'sticky-shrink' | 'fixed-overlay' | 'fixed-floating';
+export type HeaderLookOpeningRequirement = 'none' | 'reserved-space-ok' | 'requires-image-hero-with-contrast-overlay';
+export type HeaderLogoShape = 'none' | 'text-only' | 'horizontal' | 'square' | 'tall';
+export type HeaderLookDefinition = Readonly<{
+    id: HeaderLookId;
+    label: string;
+    visualTreatment: HeaderLookVisualTreatment;
+    layoutBehavior: HeaderLookLayoutBehavior;
+    openingRequirement: HeaderLookOpeningRequirement;
+    maxRecommendedNavItems?: number;
+    allowedLogoShapes?: readonly HeaderLogoShape[];
+    requiresProminentCta?: boolean;
+    compile: (theme: Theme) => Theme['header'];
+}>;
+export type HeaderOpeningSectionContext = Readonly<{
+    kind: 'unknown';
+    canAdjust: false;
+}> | Readonly<{
+    kind: 'plain';
+    canAdjust: false;
+}> | Readonly<{
+    kind: 'image-hero';
+    hasContrastOverlay: boolean;
+    hasTopSpacing: boolean;
+    canAdjust: false;
+}>;
+export type HeaderLogoContext = Readonly<{
+    shape: HeaderLogoShape;
+}>;
+export type HeaderNavigationContext = Readonly<{
+    itemCount: number;
+}>;
+export type HeaderCtaContext = Readonly<{
+    importance: 'low' | 'medium' | 'high';
+}>;
+export type HeaderBannerContext = Readonly<{
+    persistentVisibility: 'none' | 'possible' | 'visible';
+    shellCanOffsetOverlayHeader: boolean;
+}>;
+export type HeaderSelectionContext = Readonly<{
+    openingSection: HeaderOpeningSectionContext;
+    logo: HeaderLogoContext;
+    navigation: HeaderNavigationContext;
+    cta: HeaderCtaContext;
+    banner: HeaderBannerContext;
+}>;
+export type RejectedHeaderLookReason = 'requires-image-hero-with-contrast-overlay' | 'requires-opening-section-top-spacing' | 'requires-banner-offset-shell' | 'too-many-nav-items' | 'logo-shape-incompatible' | 'cta-treatment-unavailable';
+export type RejectedHeaderLook = Readonly<{
+    lookId: HeaderLookId;
+    reasons: readonly RejectedHeaderLookReason[];
+}>;
+export type HeaderSelectionResult = Readonly<{
+    selectedLookId: HeaderLookId;
+    selectedLook: HeaderLookDefinition;
+    header: Theme['header'];
+    rejected: readonly RejectedHeaderLook[];
+}>;
+export type HeaderLookDiagnostics = SiteChromeLookDiagnostics<HeaderLookId, RejectedHeaderLookReason>;
+export type HeaderLookResolutionInput = Readonly<{
+    theme: Theme;
+    recommendedLookIds: readonly HeaderLookId[];
+    context?: Partial<HeaderSelectionContext>;
+}>;
+export declare const defaultHeaderSelectionContext: HeaderSelectionContext;
+declare function solidBrandHeader(theme: Theme): Theme['header'];
+declare function cleanBaseHeader(theme: Theme): Theme['header'];
+declare function editorialLineHeader(theme: Theme): Theme['header'];
+declare function centeredCalmHeader(theme: Theme): Theme['header'];
+declare function practicalUtilityHeader(theme: Theme): Theme['header'];
+declare function minimalTransparentHeader(theme: Theme): Theme['header'];
+declare function transparentOverlayHeader(theme: Theme): Theme['header'];
+declare function floatingGlassHeader(theme: Theme): Theme['header'];
+export declare const headerLookCatalog: readonly [{
+    readonly id: HeaderLookId;
+    readonly label: "Clean base";
+    readonly visualTreatment: "solid-neutral";
+    readonly layoutBehavior: "sticky";
+    readonly openingRequirement: "none";
+    readonly compile: typeof cleanBaseHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Brand solid";
+    readonly visualTreatment: "solid-brand";
+    readonly layoutBehavior: "sticky-shrink";
+    readonly openingRequirement: "none";
+    readonly compile: typeof solidBrandHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Editorial line";
+    readonly visualTreatment: "light-editorial";
+    readonly layoutBehavior: "sticky";
+    readonly openingRequirement: "none";
+    readonly maxRecommendedNavItems: 6;
+    readonly compile: typeof editorialLineHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Centered calm";
+    readonly visualTreatment: "light-editorial";
+    readonly layoutBehavior: "normal-flow";
+    readonly openingRequirement: "none";
+    readonly maxRecommendedNavItems: 5;
+    readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal", "square"];
+    readonly compile: typeof centeredCalmHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Practical utility";
+    readonly visualTreatment: "solid-neutral";
+    readonly layoutBehavior: "sticky-shrink";
+    readonly openingRequirement: "none";
+    readonly requiresProminentCta: true;
+    readonly compile: typeof practicalUtilityHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Minimal transparent";
+    readonly visualTreatment: "minimal-transparent";
+    readonly layoutBehavior: "normal-flow";
+    readonly openingRequirement: "reserved-space-ok";
+    readonly compile: typeof minimalTransparentHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Transparent overlay";
+    readonly visualTreatment: "transparent-overlay";
+    readonly layoutBehavior: "fixed-overlay";
+    readonly openingRequirement: "requires-image-hero-with-contrast-overlay";
+    readonly maxRecommendedNavItems: 5;
+    readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal"];
+    readonly compile: typeof transparentOverlayHeader;
+}, {
+    readonly id: HeaderLookId;
+    readonly label: "Floating glass";
+    readonly visualTreatment: "floating-glass";
+    readonly layoutBehavior: "fixed-floating";
+    readonly openingRequirement: "requires-image-hero-with-contrast-overlay";
+    readonly maxRecommendedNavItems: 5;
+    readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal"];
+    readonly compile: typeof floatingGlassHeader;
+}];
+export declare const guaranteedFallbackHeaderLookId: HeaderLookId;
+export declare function getHeaderLook(id: HeaderLookId): HeaderLookDefinition | null;
+export declare function findHeaderLook(id: HeaderLookId): HeaderLookDefinition | undefined;
+export declare function getHeaderLookOrThrow(id: HeaderLookId): HeaderLookDefinition;
+export declare function headerLookRequiresImageHeroOpening(look: HeaderLookDefinition): boolean;
+export declare function headerLookUsesOverlayLayout(look: HeaderLookDefinition): boolean;
+export declare function resolveHeaderLook(input: HeaderLookResolutionInput): HeaderSelectionResult;
+export declare function headerLookDiagnosticsFromSelectionResult(result: HeaderSelectionResult): HeaderLookDiagnostics;
+export declare function headerLookRejectionReasonLabel(reason: RejectedHeaderLookReason): string;
+export {};