@riverbankcms/sdk 0.135.1 → 0.137.0

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

@@ -4,6 +4,7 @@ import type { ButtonStyleSelection } from '../buttons/styles/selection';
 import type { HeaderLayoutStyleSelection, HeaderLogoContext } from './headerLayoutStyles';
 import type { FooterLookId } from './footerLooks';
 import type { BrandDisplayMode, LogoSizePolicy } from './logoBranding';
+import type { HeaderPreferences } from './headerPreferences';
 export type HeaderBrandPreferences = Readonly<{
     brandDisplay: BrandDisplayMode;
     logoSize: LogoSizePolicy;
@@ -15,10 +16,42 @@ export type HeaderRecompileDirective = Readonly<{
     selection: HeaderLayoutStyleSelection;
     brandPresentation: ReplacementBrandPresentation;
 }>;
-export type HeaderCompilationDirective = Readonly<{
+/**
+ * "Leave the header as the user last chose it", expressed as intent rather
+ * than as bytes (#1318 Phase 4d).
+ *
+ * Until 4d this arm carried `header: Theme['header']` and the compiler returned
+ * it verbatim, which was a fourth authority over `theme.header`: bytes reached
+ * persistence without passing through a recipe. It now names the row whose
+ * intent is to be honoured, and the compiler recompiles from
+ * `(stored selection, preferences)` — the same pipeline every other write uses.
+ *
+ * `preferences` is the stored record when the caller holds one and `null` while
+ * the Phase 4c backfill has not reached the row, in which case the intent is
+ * read back out of `persistedTheme`'s own bytes by the Phase 4a reader. It is
+ * never "the defaults": a default here would be the hidden authority this slice
+ * removes.
+ */
+export type HeaderPreserveDirective = Readonly<{
     kind: 'preserve';
-    header: Theme['header'];
-}> | HeaderRecompileDirective;
+    /** The row's own persisted theme. Its intent is read; its bytes are not copied. */
+    persistedTheme: Theme;
+    preferences: HeaderPreferences | null;
+    /**
+     * Always the logo context, never `use-compiled-defaults` — which is why this
+     * is narrowed to the one arm rather than taking the whole union.
+     *
+     * The intent on this path is derived from the row's own bytes, and that
+     * derivation compares the persisted `logo` against **both** compiled
+     * candidates. Withholding the context leaves it one, so a `'recommended'` row
+     * classifies as `'plain'` and silently loses its logo treatment. Which mode
+     * then wins is `applyHeaderPreferences`'s business, from the record (D24).
+     */
+    brandPresentation: Extract<ReplacementBrandPresentation, {
+        kind: 'apply-logo-context';
+    }>;
+}>;
+export type HeaderCompilationDirective = HeaderPreserveDirective | HeaderRecompileDirective;
 export type FooterCompilationDirective = Readonly<{
     kind: 'preserve';
     footer: Theme['footer'];
@@ -69,3 +102,10 @@ export declare function replaceSiteStyleCompilationPlan(input: Readonly<{
 }>): Extract<SiteThemeCompilationPlan, {
     kind: 'replace-site-style';
 }>;
+/**
+ * Writes the brand display / logo size preference onto the header's logo style.
+ *
+ * Moved here from preview-next in #1318 Phase 4a so the header preference
+ * pipeline can be composed once, in theme-core, rather than half in the client.
+ */
+export declare function withHeaderBrandThemePreferences(theme: Theme, preferences: HeaderBrandPreferences): Theme;

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

@@ -1,8 +1,10 @@
 import { type ButtonStyleSelection } from '../buttons/styles';
 import { type KnownCuratedPaletteValueKey } from '../palette/curated';
 import type { Theme } from '../schema';
-import { type HeaderLayoutId, type HeaderLayoutStyleSelection, type HeaderStyleId } from './headerLayoutStyles';
+import { type HeaderLayoutId, type HeaderLayoutStyleSelection, type HeaderStyleId, type HeaderStyleIdValue } from './headerLayoutStyles';
 import { type FooterLookId } from './footerLooks';
+import { type HeaderStyleRecipeOverrides } from './headerStyleDefaults';
+import type { HeaderStyleRecipe } from './headerStyleRecipe';
 import { type CuratedChoice } from './curatedChoices';
 import { type AppearancePresetId, type DesignSystemTemplate, type HeadingDecoration, type NonEmptyReadonlyArray, type SiteStyleId } from './types';
 import { type SiteStyleHeroTypography } from './siteStyleTypography';
@@ -121,6 +123,16 @@ export type CuratedSiteStyle = Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -134,6 +146,16 @@ export type CuratedSiteStyle = Readonly<{
 export declare function defaultButtonStyleSelectionForSiteStyle(siteStyle: CuratedSiteStyle): ButtonStyleSelection;
 export declare function defaultPaletteForSiteStyle(siteStyle: CuratedSiteStyle): KnownCuratedPaletteValueKey;
 export declare function defaultHeaderSelectionForSiteStyle(siteStyle: CuratedSiteStyle): HeaderLayoutStyleSelection;
+/**
+ * The curated default selection together with the style choices that belong to
+ * it. Carrying the styles alongside the ids is what lets a caller fall back to
+ * the default layout without a second, nullable lookup that can never actually
+ * miss — the source of an unreachable throw before #1318 Phase 4a.
+ */
+export declare function defaultHeaderCurationForSiteStyle(siteStyle: CuratedSiteStyle): Readonly<{
+    selection: HeaderLayoutStyleSelection;
+    styles: NonEmptyReadonlyArray<HeaderStyleChoice>;
+}>;
 export declare function headerLayoutChoicesForSiteStyle(siteStyle: CuratedSiteStyle): NonEmptyReadonlyArray<HeaderLayoutChoice>;
 export declare function headerStyleChoicesForLayout(siteStyle: CuratedSiteStyle, layoutId: HeaderLayoutId): NonEmptyReadonlyArray<HeaderStyleChoice> | null;
 /**
@@ -167,6 +189,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -202,6 +234,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -237,6 +279,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -272,6 +324,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -307,6 +369,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -342,6 +414,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -377,6 +459,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -412,6 +504,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -447,6 +549,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -482,6 +594,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -517,6 +639,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -552,6 +684,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -587,6 +729,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -622,6 +774,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -657,6 +819,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -692,6 +864,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -727,6 +909,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -762,6 +954,16 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -798,6 +1000,16 @@ export declare const curatedSiteStylesById: Map<SiteStyleId, Readonly<{
     headingDecoration: HeadingDecoration;
     recommendedAppearancePresetIds: readonly AppearancePresetId[];
     headerCuration: HeaderCuration;
+    /**
+     * Header appearance this style owns outright, keyed by catalogue style id.
+     * Absent entries take `defaultHeaderStyleRecipes`; a present entry is a whole
+     * recipe, never a partial merge. Mirrors `themeOverrides.cards`.
+     *
+     * No curated style authors one yet (ledger D5): the seam ships empty and
+     * adoption follows real site work, per the "do not pre-author" rule in
+     * docs/guides/site-styles.md.
+     */
+    headerStyleRecipes?: HeaderStyleRecipeOverrides;
     recommendedFooterLookIds: readonly FooterLookId[];
     /** Authored picker choices. First item is the default/fallback. */
     buttonStyleChoices: NonEmptyReadonlyArray<ButtonStyleChoice>;
@@ -808,6 +1020,16 @@ export declare const curatedSiteStylesById: Map<SiteStyleId, Readonly<{
     /** Optional concrete hero typography applied with the site style. */
     heroTypography?: SiteStyleHeroTypography;
 }>>;
+/**
+ * The header appearance a persisted theme actually renders: the catalogue
+ * recipe unless the theme's own site style has taken that id over (#1318).
+ *
+ * Consumers that hold a theme and a selected style id — the public frontend and
+ * the chrome customiser — go through here rather than reading the style
+ * definition, so a site-style override is visible to every reader rather than
+ * only to the compiler.
+ */
+export declare function headerStyleRecipeForTheme(theme: Pick<Theme, 'siteStyleId'> | null | undefined, styleId: HeaderStyleIdValue): HeaderStyleRecipe;
 export declare function getCuratedSiteStyle(id: SiteStyleId): CuratedSiteStyle | null;
 export declare function designRuntimeRulesForSiteStyle(siteStyle: CuratedSiteStyle | null | undefined): DesignRuntimeRules;
 export declare function designRuntimeRulesForTheme(theme: Pick<Theme, 'siteStyleId'> | null | undefined): DesignRuntimeRules;

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

@@ -0,0 +1,63 @@
+import type { ThemeHeader } from '../schema';
+/**
+ * Whether the header wears a brand presentation at all (#1318 Phase 4c).
+ *
+ * `applyHeaderBrandPresentation` is unconditional today: given a logo context
+ * it always writes a `logo` object carrying a resolved display, size and
+ * accommodation. That makes "this header has no brand presentation block" —
+ * which is what several live sites persist, including one whose site *does*
+ * have a logo asset — a state the preference record could not express, so a
+ * recompile would silently give the site a logo treatment it has never
+ * rendered.
+ *
+ * This is the third field in this phase with that shape, after the interaction
+ * palette and the nav text size: the persisted bytes carry intent the reader
+ * cannot say, so the recompile "corrects" it. The fix is the same one — widen
+ * the closed vocabulary with a named member and derive it by baseline
+ * comparison — and it is a *widening*, not a restyle: `'recommended'` is the
+ * default and reproduces today's behaviour exactly, so no row whose bytes carry
+ * a presentation compiles differently for `'plain'` existing.
+ *
+ * `'plain'` is deliberately not "preserve whatever bytes are there". It is a
+ * constructive instruction — *write no presentation block* — so Phase 4e's
+ * compiler, which builds the header from nothing, can produce it.
+ */
+export declare const headerBrandPresentationValues: readonly ["recommended", "plain"];
+export type HeaderBrandPresentationPreference = (typeof headerBrandPresentationValues)[number];
+export declare const defaultHeaderBrandPresentation: HeaderBrandPresentationPreference;
+/**
+ * What the row's own bytes say about the presentation mode.
+ *
+ * `unrecognised` is its own state for the same reason it is on the interaction
+ * palette: the record has no way to represent "a logo block nobody's rule
+ * produces", and answering `'plain'` for one would drop a treatment the site
+ * renders. An unrecognised row falls back to `'recommended'` in the record and
+ * is reported by the divergence report, which blocks the Phase 4e gate.
+ */
+export type HeaderBrandPresentationBytesClassification = Readonly<{
+    kind: 'recommended';
+}> | Readonly<{
+    kind: 'plain';
+}> | Readonly<{
+    kind: 'unrecognised';
+}>;
+/**
+ * Which mode reproduces this row's persisted logo bytes.
+ *
+ * Both candidates are supplied rather than reconstructed here, because both are
+ * the compilation's own output and rebuilding either would be a second
+ * authority on what the modes mean. `'recommended'` is tested first so that a
+ * row the resolver already agrees with keeps the live mode; `'plain'` is the
+ * answer for the rows that carry no presentation — an absent block, or a block
+ * holding only the recipe's own brand typography.
+ */
+export declare function classifyHeaderBrandPresentationBytes(persisted: ThemeHeader, 
+/** The header `'recommended'` produces for this row — presentation applied. */
+recommended: ThemeHeader, 
+/** The header `'plain'` produces — the presentation step skipped. */
+plain: ThemeHeader): HeaderBrandPresentationBytesClassification;
+/**
+ * The preference the bytes express, or `null` when they express none the record
+ * can carry. `null` is the caller's cue to fall back to the default and say so.
+ */
+export declare function readHeaderBrandPresentationFromBytes(persisted: ThemeHeader, recommended: ThemeHeader, plain: ThemeHeader): HeaderBrandPresentationPreference | null;

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

@@ -0,0 +1,30 @@
+import type { ThemeHeader } from '../schema';
+export type HeaderFieldDiff = Readonly<{
+    path: string;
+    left: unknown;
+    right: unknown;
+}>;
+/**
+ * Structural diff by JSON path. Values are compared through
+ * `JSON.stringify`, so a key present with the value `undefined` and an absent
+ * key read as the same thing — which is what `jsonb` does to them anyway
+ * (#1318 Correction 5).
+ */
+export declare function diffJsonPaths(left: unknown, right: unknown, path?: string): readonly HeaderFieldDiff[];
+export type CompiledHeaderComparison = Readonly<{
+    kind: 'equal';
+}> | Readonly<{
+    kind: 'different';
+    diffs: readonly HeaderFieldDiff[];
+    differingPaths: readonly string[];
+}>;
+/**
+ * The Phase 4b equality assertion: does the header a client compiled match the
+ * one the server compiles from the same `(selection, preferences)`?
+ *
+ * Both sides go through a JSON round trip first, because the persisted form is
+ * `jsonb` and an in-memory `ctaVariant: undefined` is not a difference the
+ * database could ever store (#1318 Correction 5). Comparing the in-memory
+ * objects directly would report a mismatch that no save could produce.
+ */
+export declare function compareCompiledHeaders(left: ThemeHeader, right: ThemeHeader): CompiledHeaderComparison;

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

@@ -10,7 +10,7 @@ export declare const clearSplitInteractionPalette: Readonly<{
     id: "interaction-palette";
     label: string;
     options: readonly [HeaderInteractionPaletteOption, ...HeaderInteractionPaletteOption[]];
-    defaultOptionId: "accent" | "primary" | "secondary";
+    defaultOptionId: "accent" | "primary" | "secondary" | "quiet";
 }>;
 export type HeaderInteractionPaletteControlState = Readonly<{
     kind: 'unavailable';
@@ -30,3 +30,52 @@ export type HeaderInteractionPaletteControlState = Readonly<{
 }>;
 export declare function resolveHeaderInteractionPaletteControl(group: HeaderInteractionPaletteOptionGroup | undefined, preference: HeaderInteractionPalettePreference): HeaderInteractionPaletteControlState;
 export declare function applyHeaderInteractionPalette(header: ThemeHeader, group: HeaderInteractionPaletteOptionGroup | undefined, preference: HeaderInteractionPalettePreference): ThemeHeader;
+/**
+ * What a persisted header's nav link style says about the palette.
+ *
+ * `'unrecognised'` is the arm that matters. `'quiet'` writes nothing and is
+ * therefore a fixed point of *every* header, so a fixed-point search alone
+ * would answer `'quiet'` for a pill nobody in the group produces — and a
+ * recompile under `'quiet'` would then drop that pill. Reporting the state
+ * instead means a row like that reaches a human through the Phase 4c report
+ * rather than losing its hover treatment quietly.
+ */
+export type HeaderInteractionPaletteBytesClassification = Readonly<{
+    kind: 'derived';
+    preference: HeaderInteractionPalettePreference;
+}> | Readonly<{
+    kind: 'unrecognised';
+}> | Readonly<{
+    kind: 'no-palette';
+}>;
+/**
+ * Which option of `group` a persisted header's nav link style is the output of
+ * (#1318 Phase 4c decision 2).
+ *
+ * This is a baseline comparison rather than a pattern match on effect bytes.
+ * The palette overwrites its four fields unconditionally, so applying an option
+ * to a header leaves that header unchanged exactly when the header is already
+ * that option's output — which makes "which option produced these bytes" a
+ * fixed-point search over the closed option list.
+ *
+ * Order is load-bearing twice over:
+ *
+ * - `'recommended'` is tried first, so a row compiled from the recommendation
+ *   derives the sentinel rather than the default option's own id. As with the
+ *   structure rule, an explicit choice that happens to equal the default
+ *   collapses to the sentinel; nothing in the bytes distinguishes the two.
+ * - `'quiet'` is tried last, because it writes nothing and is therefore a fixed
+ *   point of every header. Reaching it means no pill option produced these
+ *   bytes — which is what "this row renders no pill" means, *provided the row
+ *   carries no pill*. `carriesPaletteShapedEffect` is that proviso: a
+ *   palette-shaped nav link that no option reproduces is `'unrecognised'`, not
+ *   `'quiet'`.
+ */
+export declare function classifyHeaderInteractionPaletteBytes(header: ThemeHeader, group: HeaderInteractionPaletteOptionGroup | undefined): HeaderInteractionPaletteBytesClassification;
+/**
+ * The preference `classifyHeaderInteractionPaletteBytes` derived, or `null`
+ * when the bytes express none — either because the style offers no palette or
+ * because they match no option it does offer. Callers that need to tell those
+ * two apart use the classification directly.
+ */
+export declare function readHeaderInteractionPaletteFromBytes(header: ThemeHeader, group: HeaderInteractionPaletteOptionGroup | undefined): HeaderInteractionPalettePreference | null;