@riverbankcms/sdk 0.76.0 → 0.77.1

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

@@ -1,19 +1,143 @@
-import type { Theme } from '../schema';
+import type { Theme, ThemeHeader } 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 declare const headerLookIdValues: readonly ["clean-base", "brand-solid", "serif-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 PersistedHeaderLookIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderLookId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLookId(value: string): Exclude<PersistedHeaderLookIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLookId(value: string | null | undefined): PersistedHeaderLookIdParseResult;
+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", "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;
+    structure: HeaderStructureId;
+    variant: ThemeHeader['variant'];
+    defaultPositioning: ThemeHeader['positioning'];
+    shrinkOnScroll: boolean;
+    maxRecommendedNavItems?: number;
+    allowedLogoShapes?: readonly HeaderLogoShape[];
+}>;
+export type HeaderStyleNavInteraction = 'color-change' | 'underline-grow' | 'pill-background' | 'flat-block' | 'glass-backed';
+export type HeaderStyleSurface = 'neutral' | 'bordered' | 'soft' | 'brand-solid' | 'floating';
+export type HeaderStyleDefinition = Readonly<{
+    id: HeaderStyleId;
+    label: string;
+    description: string;
+    supportedLayoutIds: readonly HeaderLayoutId[];
+    navInteraction: HeaderStyleNavInteraction;
+    surface: HeaderStyleSurface;
+    navTypography: HeaderStyleNavTypography;
+}>;
+export type HeaderLayoutStyleSelection = Readonly<{
+    layoutId: HeaderLayoutId;
+    styleId: HeaderStyleId;
+}>;
+export type HeaderStyleChoiceSource = Readonly<{
+    id: HeaderStyleId;
+}>;
+export type HeaderLayoutChoiceSource = Readonly<{
+    id: HeaderLayoutId;
+}>;
+export type HeaderStyleChoicesByLayout = Readonly<Partial<Record<HeaderLayoutIdValue, readonly HeaderStyleChoiceSource[]>>>;
+export type HeaderLayoutStyleCuration = Readonly<{
+    recommendedHeaderLayoutChoices: readonly HeaderLayoutChoiceSource[];
+    recommendedHeaderStyleChoicesByLayout: HeaderStyleChoicesByLayout;
+}>;
+export type HeaderLegacyLookAlias = Readonly<{
+    lookId: HeaderLookId;
+    selection: HeaderLayoutStyleSelection;
+}>;
+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 HeaderLookVisualTreatment = 'solid-neutral' | 'solid-brand' | 'light-serif' | 'minimal-transparent' | 'transparent-overlay' | 'floating-glass';
 export type HeaderLookLayoutBehavior = 'normal-flow' | 'sticky' | 'sticky-shrink' | 'fixed-overlay' | 'fixed-floating';
+export type HeaderStructureId = 'inline-classic' | 'centered-stack' | 'floating-shell';
+export type HeaderTreatmentId = HeaderLookVisualTreatment;
+export type HeaderBehaviorId = HeaderLookLayoutBehavior;
+export type HeaderConfiguration = Readonly<{
+    structure: HeaderStructureId;
+    treatment: HeaderTreatmentId;
+    behavior: HeaderBehaviorId;
+}>;
+export type HeaderConfigurationRejectionReason = 'unsupported-structure-treatment-behavior-combination';
+export type HeaderConfigurationResolution = Readonly<{
+    kind: 'valid';
+    configuration: HeaderConfiguration;
+}> | Readonly<{
+    kind: 'rejected';
+    requested: HeaderConfiguration;
+    reasons: readonly HeaderConfigurationRejectionReason[];
+}>;
 export type HeaderLookOpeningRequirement = 'none' | 'reserved-space-ok' | 'requires-image-hero-with-contrast-overlay';
 export type HeaderLogoShape = 'none' | 'text-only' | 'horizontal' | 'square' | 'tall';
+export type HeaderStyleNavTypography = 'plain' | 'heading' | 'quiet-caps' | 'brand-caps';
 export type HeaderLookDefinition = Readonly<{
     id: HeaderLookId;
     label: string;
     visualTreatment: HeaderLookVisualTreatment;
     layoutBehavior: HeaderLookLayoutBehavior;
+    configuration: HeaderConfiguration;
     openingRequirement: HeaderLookOpeningRequirement;
     maxRecommendedNavItems?: number;
     allowedLogoShapes?: readonly HeaderLogoShape[];
@@ -25,12 +149,32 @@ export type HeaderOpeningSectionContext = Readonly<{
     canAdjust: false;
 }> | Readonly<{
     kind: 'plain';
-    canAdjust: false;
+    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: false;
+    canAdjust: boolean;
+}>;
+export type OverlayHeaderOpeningPlan = Readonly<{
+    canRender: true;
+    contrastIntent: 'theme-default' | 'light-on-dark' | 'dark-on-light';
+    topSpacing: 'preserve' | 'add';
+    legibilityFallback: 'none' | 'glass-nav-backing';
 }>;
 export type HeaderLogoContext = Readonly<{
     shape: HeaderLogoShape;
@@ -43,7 +187,6 @@ export type HeaderCtaContext = Readonly<{
 }>;
 export type HeaderBannerContext = Readonly<{
     persistentVisibility: 'none' | 'possible' | 'visible';
-    shellCanOffsetOverlayHeader: boolean;
 }>;
 export type HeaderSelectionContext = Readonly<{
     openingSection: HeaderOpeningSectionContext;
@@ -52,7 +195,7 @@ export type HeaderSelectionContext = Readonly<{
     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 RejectedHeaderLookReason = 'requires-image-hero-with-contrast-overlay' | 'too-many-nav-items' | 'logo-shape-incompatible' | 'cta-treatment-unavailable';
 export type RejectedHeaderLook = Readonly<{
     lookId: HeaderLookId;
     reasons: readonly RejectedHeaderLookReason[];
@@ -70,9 +213,212 @@ export type HeaderLookResolutionInput = Readonly<{
     context?: Partial<HeaderSelectionContext>;
 }>;
 export declare const defaultHeaderSelectionContext: HeaderSelectionContext;
+export declare function planOverlayHeaderOpening(opening: HeaderOpeningSectionContext): OverlayHeaderOpeningPlan;
+export declare const headerLayoutCatalog: readonly [{
+    readonly id: HeaderLayoutId;
+    readonly label: "Classic";
+    readonly description: "Logo and navigation in one practical horizontal row.";
+    readonly structure: "inline-classic";
+    readonly variant: "classic";
+    readonly defaultPositioning: "sticky";
+    readonly shrinkOnScroll: false;
+}, {
+    readonly id: HeaderLayoutId;
+    readonly label: "Centered";
+    readonly description: "Logo centered above a balanced navigation row.";
+    readonly structure: "centered-stack";
+    readonly variant: "centered";
+    readonly defaultPositioning: "static";
+    readonly shrinkOnScroll: false;
+    readonly maxRecommendedNavItems: 5;
+    readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal", "square"];
+}, {
+    readonly id: HeaderLayoutId;
+    readonly label: "Floating";
+    readonly description: "Detached header chrome that sits over the opening section.";
+    readonly structure: "floating-shell";
+    readonly variant: "floating";
+    readonly defaultPositioning: "fixed";
+    readonly shrinkOnScroll: true;
+    readonly maxRecommendedNavItems: 5;
+    readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal"];
+}];
+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 navInteraction: "color-change";
+    readonly surface: "neutral";
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Fine Line";
+    readonly description: "Light surface with a crisp lower rule and underline hover.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "underline-grow";
+    readonly surface: "bordered";
+    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 navInteraction: "pill-background";
+    readonly surface: "soft";
+    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 navInteraction: "pill-background";
+    readonly surface: "soft";
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Bar";
+    readonly description: "Solid brand surface with high-contrast navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "color-change";
+    readonly surface: "brand-solid";
+    readonly navTypography: "brand-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Brand Underline";
+    readonly description: "Brand surface with underline-grow navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "underline-grow";
+    readonly surface: "brand-solid";
+    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 navInteraction: "pill-background";
+    readonly surface: "brand-solid";
+    readonly navTypography: "brand-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Serif Line";
+    readonly description: "Typographic logo treatment with understated underline navigation.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "underline-grow";
+    readonly surface: "bordered";
+    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 navInteraction: "flat-block";
+    readonly surface: "bordered";
+    readonly navTypography: "quiet-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Glass";
+    readonly description: "Translucent chrome with frosted navigation backing.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "glass-backed";
+    readonly surface: "floating";
+    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 navInteraction: "color-change";
+    readonly surface: "floating";
+    readonly navTypography: "plain";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Soft Shell";
+    readonly description: "Floating rounded shell with soft pill navigation states.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "pill-background";
+    readonly surface: "floating";
+    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 navInteraction: "glass-backed";
+    readonly surface: "floating";
+    readonly navTypography: "quiet-caps";
+}, {
+    readonly id: HeaderStyleId;
+    readonly label: "Split Pill";
+    readonly description: "Logo floats independently with a soft pill-backed navigation rail.";
+    readonly supportedLayoutIds: readonly HeaderLayoutId[];
+    readonly navInteraction: "pill-background";
+    readonly surface: "floating";
+    readonly navTypography: "heading";
+}];
+export declare const legacyHeaderLookAliases: readonly [{
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}, {
+    readonly lookId: HeaderLookId;
+    readonly selection: {
+        readonly layoutId: HeaderLayoutId;
+        readonly styleId: HeaderStyleId;
+    };
+}];
+export declare function getHeaderLayout(id: HeaderLayoutId): HeaderLayoutDefinition | null;
+export declare function getHeaderStyle(id: HeaderStyleId): HeaderStyleDefinition | null;
+export declare function isHeaderStyleCompatibleWithLayout(style: HeaderStyleDefinition, layoutId: HeaderLayoutId): boolean;
+export declare function resolveLegacyHeaderLookAlias(lookId: HeaderLookId): HeaderLayoutStyleSelection | null;
+export declare function findLegacyHeaderLookIdForSelection(selection: HeaderLayoutStyleSelection): HeaderLookId | null;
+export declare function getCompatibleHeaderStyleIds(layoutId: HeaderLayoutId): readonly HeaderStyleId[];
+export declare function getOrderedHeaderLayoutIdsForCuration(curation: HeaderLayoutStyleCuration): readonly HeaderLayoutId[];
+export declare function getOrderedHeaderStyleIdsForLayout(curation: HeaderLayoutStyleCuration, layoutId: HeaderLayoutId): readonly HeaderStyleId[];
+export declare function deriveNearestCompatibleHeaderStyle(styleId: HeaderStyleId, layoutId: HeaderLayoutId): HeaderStyleId;
+export declare function resolveHeaderLayoutStyleSelection(selection: HeaderLayoutStyleSelection): HeaderLayoutStyleResolution;
+export declare function compileHeaderLayoutStyleSelection(theme: Theme, selection: HeaderLayoutStyleSelection): Theme['header'];
 declare function solidBrandHeader(theme: Theme): Theme['header'];
 declare function cleanBaseHeader(theme: Theme): Theme['header'];
-declare function editorialLineHeader(theme: Theme): Theme['header'];
+declare function serifLineHeader(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'];
@@ -83,6 +429,11 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Clean base";
     readonly visualTreatment: "solid-neutral";
     readonly layoutBehavior: "sticky";
+    readonly configuration: {
+        readonly structure: "inline-classic";
+        readonly treatment: "solid-neutral";
+        readonly behavior: "sticky";
+    };
     readonly openingRequirement: "none";
     readonly compile: typeof cleanBaseHeader;
 }, {
@@ -90,21 +441,36 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Brand solid";
     readonly visualTreatment: "solid-brand";
     readonly layoutBehavior: "sticky-shrink";
+    readonly configuration: {
+        readonly structure: "inline-classic";
+        readonly treatment: "solid-brand";
+        readonly behavior: "sticky-shrink";
+    };
     readonly openingRequirement: "none";
     readonly compile: typeof solidBrandHeader;
 }, {
     readonly id: HeaderLookId;
-    readonly label: "Editorial line";
-    readonly visualTreatment: "light-editorial";
+    readonly label: "Serif line";
+    readonly visualTreatment: "light-serif";
     readonly layoutBehavior: "sticky";
+    readonly configuration: {
+        readonly structure: "centered-stack";
+        readonly treatment: "light-serif";
+        readonly behavior: "sticky";
+    };
     readonly openingRequirement: "none";
     readonly maxRecommendedNavItems: 6;
-    readonly compile: typeof editorialLineHeader;
+    readonly compile: typeof serifLineHeader;
 }, {
     readonly id: HeaderLookId;
     readonly label: "Centered calm";
-    readonly visualTreatment: "light-editorial";
+    readonly visualTreatment: "light-serif";
     readonly layoutBehavior: "normal-flow";
+    readonly configuration: {
+        readonly structure: "centered-stack";
+        readonly treatment: "light-serif";
+        readonly behavior: "normal-flow";
+    };
     readonly openingRequirement: "none";
     readonly maxRecommendedNavItems: 5;
     readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal", "square"];
@@ -114,6 +480,11 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Practical utility";
     readonly visualTreatment: "solid-neutral";
     readonly layoutBehavior: "sticky-shrink";
+    readonly configuration: {
+        readonly structure: "inline-classic";
+        readonly treatment: "solid-neutral";
+        readonly behavior: "sticky-shrink";
+    };
     readonly openingRequirement: "none";
     readonly requiresProminentCta: true;
     readonly compile: typeof practicalUtilityHeader;
@@ -122,6 +493,11 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Minimal transparent";
     readonly visualTreatment: "minimal-transparent";
     readonly layoutBehavior: "normal-flow";
+    readonly configuration: {
+        readonly structure: "inline-classic";
+        readonly treatment: "minimal-transparent";
+        readonly behavior: "normal-flow";
+    };
     readonly openingRequirement: "reserved-space-ok";
     readonly compile: typeof minimalTransparentHeader;
 }, {
@@ -129,6 +505,11 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Transparent overlay";
     readonly visualTreatment: "transparent-overlay";
     readonly layoutBehavior: "fixed-overlay";
+    readonly configuration: {
+        readonly structure: "inline-classic";
+        readonly treatment: "transparent-overlay";
+        readonly behavior: "fixed-overlay";
+    };
     readonly openingRequirement: "requires-image-hero-with-contrast-overlay";
     readonly maxRecommendedNavItems: 5;
     readonly allowedLogoShapes: readonly ["none", "text-only", "horizontal"];
@@ -138,12 +519,20 @@ export declare const headerLookCatalog: readonly [{
     readonly label: "Floating glass";
     readonly visualTreatment: "floating-glass";
     readonly layoutBehavior: "fixed-floating";
+    readonly configuration: {
+        readonly structure: "floating-shell";
+        readonly treatment: "floating-glass";
+        readonly behavior: "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 const guaranteedFallbackHeaderLayoutId: HeaderLayoutId;
+export declare const guaranteedFallbackHeaderStyleId: HeaderStyleId;
+export declare function resolveHeaderConfiguration(configuration: HeaderConfiguration): HeaderConfigurationResolution;
 export declare function getHeaderLook(id: HeaderLookId): HeaderLookDefinition | null;
 export declare function findHeaderLook(id: HeaderLookId): HeaderLookDefinition | undefined;
 export declare function getHeaderLookOrThrow(id: HeaderLookId): HeaderLookDefinition;

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

@@ -5,10 +5,16 @@ export type HeaderOpeningSectionPlan<TBlockId extends DesignBlockId = DesignBloc
     plan: readonly BlockDesignPlan<TBlockId>[];
     repairs: readonly HeaderOpeningSectionRepair[];
 }>;
+export type HeaderOpeningContentSnapshot = Readonly<{
+    blockKind: string | null;
+    content?: Record<string, unknown> | null;
+    canAdjust?: boolean;
+}>;
 export declare function planGeneratedHeaderOpeningSection<TBlockId extends DesignBlockId>(input: Readonly<{
     plan: readonly BlockDesignPlan<TBlockId>[];
     recommendedHeaderLookIds: readonly HeaderLookId[];
 }>): HeaderOpeningSectionPlan<TBlockId>;
+export declare function deriveHeaderOpeningSectionContextFromContent(input: HeaderOpeningContentSnapshot): HeaderOpeningSectionContext;
 export declare function deriveHeaderOpeningSectionContext(input: Readonly<{
     openingBlock: ResolvedBlockDesignPlan | null;
     openingContent?: Record<string, unknown> | null;

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

@@ -19,6 +19,7 @@ export * from './pageDesignEditorErrors';
 export * from './pageDesignEditorModel';
 export * from './pageDesignIntent';
 export * from './previewCustomization';
+export * from './persistedIdParseResult';
 export * from './rawStyleFields';
 export * from './records';
 export * from './resolver';
@@ -27,4 +28,5 @@ export * from './siteStyleBlockPolicies';
 export * from './sourceCatalogs';
 export * from './styleTags';
 export * from './tokenRecipes';
+export * from './typographyPresets';
 export * from './types';

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

@@ -0,0 +1,9 @@
+export type PersistedIdParseResult<TId extends string> = Readonly<{
+    kind: 'known';
+    id: TId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;

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

@@ -3,8 +3,9 @@ import { type Theme } from '../schema';
 import { type ButtonPersonalityId } from '../buttons/personalities';
 import { type PaletteOverrides, type PaletteVariantId } from '../palette/variants';
 import { type CuratedSiteStyle } from './curatedSiteStyles';
+import { type CompiledTypographySelection, type KnownTypographyPresetId, type TypographyPresetId, type TypographyPresetResolutionWarning, type TypographySelection } from './typographyPresets';
 import { type FooterLookId, type FooterSelectionContext, type FooterSelectionResult } from './footerLooks';
-import { type HeaderSelectionContext, type HeaderLookId, type HeaderSelectionResult } from './headerLooks';
+import { type HeaderLayoutId, type HeaderSelectionContext, type HeaderLookId, type HeaderSelectionResult, type HeaderStyleId } from './headerLooks';
 import { type CompiledBlockRuntimeFields, type CompiledPageRuntime, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing, type SurfaceResolutionContext } from './runtimeCompiler';
 import type { AppearancePresetId, DesignBlockId, SiteStyleId } from './types';
 /**
@@ -22,7 +23,8 @@ export { repairDesignIssue, resolveBlockDesignPlan } from './resolver';
 export { cycleableOptionsFromResolved, deriveDesignCustomizationScope, recommendedDesignOption, type CycleableDesignOption, type CycleableOptions, type DesignCustomizationAuthority, type DesignCustomizationScope, type DesignCustomizationSurface, type DesignCustomizationUnsupportedReason, type DesignOptionIssue, type ResolvedDesignOption, } from './previewCustomization';
 export { compileBlockRuntimeFields, compilePageRuntimeFields, compileTokenRecipes, compiledRuntimeStyleFieldNames, defaultComponentRuntimeRules, defaultDesignRuntimeRules, surfaceResolutionContextFromPalette, surfaceResolutionContextFromTheme, stripCompiledRuntimeStyleFields, type CompiledBlockRuntime, type CompiledBlockRuntimeFields, type CompiledPageRuntime, type CompileBlockRuntimeInput, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing, type SurfaceResolutionContext, } from './runtimeCompiler';
 export { defaultCuratedChoice, requireEntriesForCuratedChoices, resolveCuratedChoice, type CuratedChoice, type CuratedChoiceResolution, } from './curatedChoices';
-export { curatedSiteStyles, defaultButtonPersonalityForSiteStyle, defaultPaletteVariantForSiteStyle, getCuratedSiteStyle, type CuratedSiteStyle, } from './curatedSiteStyles';
+export { curatedSiteStyles, defaultButtonPersonalityForSiteStyle, defaultPaletteVariantForSiteStyle, defaultTypographyPresetForSiteStyle, getCuratedSiteStyle, type CuratedSiteStyle, } from './curatedSiteStyles';
+export { asTypographyPresetId, compileTypographySelection, evaluateTypographyFontSlot, findTypographyPreset, parsePersistedTypographyPresetId, typographyPresetIdValues, typographyPresets, type CompiledTypographySelection, type GoogleFontCategory, type KnownTypographyPresetId, type KnownTypographyPresetIdValue, type TypographyFontCapability, type TypographyFontSlot, type TypographyFontSlotFit, type TypographyFontSlotPolicy, type TypographyPreset, type TypographyPresetId, type TypographyPresetResolutionWarning, type TypographySelection, } from './typographyPresets';
 export { asDesignBlockId, asSiteStyleId, makeBoundaryId, type AppearancePresetId, type BoundaryOptionId, type DesignBlockId, type DesignBoundaryId, type LayoutVariantKey, type NonEmptyReadonlyArray, type PageFlowPresetId, type ResolvedPageDesignPlan, type SiteStyleId, } from './types';
 export declare const previewCustomizePurpose: "preview-customize";
 /**
@@ -48,13 +50,19 @@ export type SelectionFallbackWarning = Readonly<{
     kind: 'rejected-palette';
     requested: string;
     fellBackTo: PaletteVariantId;
-}>;
+}> | TypographyPresetResolutionWarning;
 export type SiteThemeSelectionsInput = Readonly<{
     siteStyle: CuratedSiteStyle;
     buttonPersonalityId: ButtonPersonalityId | null;
     paletteVariantId: PaletteVariantId | null;
     paletteOverrides: PaletteOverrides | null;
+    typographyPresetId?: TypographyPresetId | null;
+    typographyBodyFontOverride?: string | null;
+    typographyHeadingFontOverride?: string | null;
+    typographySelection?: TypographySelection | null;
     headerLookId?: HeaderLookId | null;
+    headerLayoutId?: HeaderLayoutId | null;
+    headerStyleId?: HeaderStyleId | null;
     footerLookId?: FooterLookId | null;
     headerSelectionContext?: Partial<HeaderSelectionContext>;
     footerSelectionContext?: Partial<FooterSelectionContext>;
@@ -63,12 +71,20 @@ export type SiteThemeSelectionsResult = Readonly<{
     theme: CuratedSiteStyleTheme;
     requestedSelections: Readonly<{
         headerLookId: HeaderLookId | null;
+        headerLayoutId: HeaderLayoutId | null;
+        headerStyleId: HeaderStyleId | null;
         footerLookId: FooterLookId | null;
     }>;
     resolvedSelections: Readonly<{
         buttonPersonalityId: ButtonPersonalityId;
         paletteVariantId: PaletteVariantId;
-        headerLookId: HeaderLookId;
+        typographySelection: CompiledTypographySelection['resolvedSelection'];
+        typographyPresetId: KnownTypographyPresetId | null;
+        typographyBodyFontOverride: string | null;
+        typographyHeadingFontOverride: string | null;
+        headerLookId: HeaderLookId | null;
+        headerLayoutId: HeaderLayoutId;
+        headerStyleId: HeaderStyleId;
         footerLookId: FooterLookId;
     }>;
     headerSelection: HeaderSelectionResult;