@riverbankcms/sdk 0.135.1 → 0.137.0

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

@@ -1,18 +1,57 @@
-import type { Theme } from '../schema';
-import { type HeaderBrandPresentationPlan, type HeaderBrandPresentationSelection, type LogoAccommodationOption } from './logoBranding';
-import { type HeaderLayoutId, type HeaderLogoContext, type HeaderStyleId } from './headerLayoutTypes';
+import { type HeaderBrandPresentationPlan, type HeaderBrandPresentationSelection, type BrandDisplayMode, type LogoAccommodationOption, type LogoAccommodationPattern, type LogoSizePolicy } from './logoBranding';
+import { type HeaderLayoutId, type HeaderLogoContext, type HeaderLogoDimensions, type HeaderLogoShape, type HeaderStyleId } from './headerLayoutTypes';
+export declare function logoAccommodationProvidesBacking(pattern: LogoAccommodationPattern): boolean;
+export type HeaderLogoAsset = Readonly<{
+    /** The site's stored logo, or `null` when it has none. */
+    asset: HeaderLogoDimensions | null;
+    /** The accommodation the row currently persists, if any. */
+    accommodation: LogoAccommodationPattern | undefined;
+}>;
+/**
+ * The single answer to "what shape is this site's logo" (#1318 Phase 4b).
+ *
+ * The server and the public frontend each had their own copy of this, and they
+ * disagreed on the one case that matters: a logo whose dimensions are unknown.
+ * The server assumed `horizontal`; the frontend asked whether the persisted
+ * accommodation brings its own backing and answered `square` if it does. The
+ * richer rule is the correct one — a badge or masthead accommodation is
+ * evidence about the asset that raw dimensions would otherwise supply — and it
+ * reduces to `horizontal` whenever there is no backing, so it subsumes the
+ * server's rule rather than contradicting it. The backing question goes through
+ * `logoAccommodationProvidesBacking`, so the pattern list has one home.
+ */
+export declare function deriveHeaderLogoShape({ asset, accommodation, }: HeaderLogoAsset): HeaderLogoShape;
+/**
+ * The site's logo as the header pipeline sees it, from the two database values
+ * that describe it: the asset (or its absence) and the accommodation the row
+ * currently persists, which is evidence about the asset when its dimensions are
+ * missing.
+ *
+ * One definition, shared by every shell that has to answer it — the dashboard's
+ * `loadHeaderLogoContextForSite`, the public frontend, and the Phase 4c repair
+ * generator — because a second copy is a second answer to "what shape is this
+ * site's logo", and the two former copies disagreed on exactly the case this
+ * one is careful about (#1318 Phase 4b/4c).
+ */
+export declare function headerLogoShapeContext(input: HeaderLogoAsset & Readonly<{
+    /**
+     * The brand half of the preference record, when the caller holds one.
+     * Both members are optional because the public frontend reads them off
+     * the persisted header, where either can be absent; an absent one is left
+     * off the context rather than written as `undefined`, so the resolver's
+     * own `?? 'auto'` still decides.
+     */
+    brand?: Readonly<{
+        brandDisplay?: BrandDisplayMode;
+        logoSize?: LogoSizePolicy;
+    }>;
+}>): HeaderLogoContext;
 export declare function resolveHeaderBrandPresentation(input: Readonly<{
     logo: HeaderLogoContext;
     accommodations: readonly LogoAccommodationOption[];
     allowDisplayFallback?: boolean;
 }>): HeaderBrandPresentationPlan;
 export declare function requireHeaderBrandPresentationSelection(plan: HeaderBrandPresentationPlan): HeaderBrandPresentationSelection;
-/**
- * Starts each compilation from the generated theme's header branch, then
- * clears optional nested styling fields that would otherwise leak from a
- * different header selection.
- */
-export declare function baseHeader(theme: Theme): Theme['header'];
 export declare const headerLayoutCatalog: readonly [{
     readonly id: HeaderLayoutId;
     readonly label: "Classic";
@@ -141,101 +180,76 @@ export declare const headerStyleCatalog: readonly [{
     readonly label: "Minimal";
     readonly description: "Quiet surface with simple color-change navigation.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Seamless";
     readonly description: "Borderless surface with underline hover for a quieter page transition.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Soft Bar";
     readonly description: "Soft tinted surface with gentle pill hover states.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Pill Nav";
     readonly description: "A calm pill navigation rail over a neutral header.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Brand Bar";
     readonly description: "Solid brand surface with high-contrast navigation.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "brand-caps";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Brand Underline";
     readonly description: "Brand surface with underline-grow navigation.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "brand-caps";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Brand Pill";
     readonly description: "Solid brand surface with rounded active and hover states.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "brand-caps";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Brand Capsule";
     readonly description: "Solid brand chrome designed as a floating capsule, with quiet-caps nav, a soft pill active state, and an inverted CTA pill.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "quiet-caps";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Serif Line";
     readonly description: "Typographic logo treatment with understated underline navigation.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "heading";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Flat Tabs";
     readonly description: "Flat block hover and active states with a Swiss utility feel.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "quiet-caps";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Glass";
     readonly description: "Translucent chrome with frosted navigation backing.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Clear Split";
     readonly description: "Floating logo with transparent navigation and no shared shell.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
-    readonly openingForegroundTarget: "all";
-    readonly scrollTreatment: "contrast-glass";
-    readonly interactionPalette: Readonly<{
-        id: "interaction-palette";
-        label: string;
-        options: readonly [import("../../../blocks/src/index").HeaderInteractionPaletteOption, ...import("../../../blocks/src/index").HeaderInteractionPaletteOption[]];
-        defaultOptionId: "accent" | "primary" | "secondary";
-    }>;
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Soft Shell";
     readonly description: "Floating rounded shell with soft pill navigation states.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "plain";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Split Glass";
     readonly description: "Logo floats independently while the navigation sits in a glass rail.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "quiet-caps";
-    readonly openingForegroundTarget: "brand-only";
 }, {
     readonly id: HeaderStyleId;
     readonly label: "Split Pill";
     readonly description: "Logo floats independently with a soft pill-backed navigation rail.";
     readonly supportedLayoutIds: readonly HeaderLayoutId[];
-    readonly navTypography: "heading";
-    readonly openingForegroundTarget: "brand-only";
 }];
 export declare const headerLayoutsById: Map<HeaderLayoutId, Readonly<{
     id: HeaderLayoutId;
@@ -252,10 +266,6 @@ export declare const headerStylesById: Map<HeaderStyleId, Readonly<{
     label: string;
     description: string;
     supportedLayoutIds: readonly HeaderLayoutId[];
-    navTypography: import("../../../blocks/src/index").HeaderStyleNavTypography;
-    openingForegroundTarget?: "brand-only" | "all";
-    scrollTreatment?: "contrast-glass";
-    interactionPalette?: import("../../../blocks/src/index").HeaderInteractionPaletteOptionGroup;
 }>>;
 export declare const headerStyleCompatibilityOrder: {
     readonly classic: readonly ["minimal", "fine-line", "soft-bar", "pill-nav", "brand-bar", "brand-underline", "brand-pill", "brand-capsule", "serif-line", "flat-tabs"];

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

@@ -2,5 +2,15 @@ export * from './headerLayoutTypes';
 export * from './headerLayoutCatalog';
 export * from './headerLayoutResolution';
 export * from './headerStyleCompiler';
+/**
+ * The recipe modules are re-exported by name rather than with `export *`.
+ * `compileHeaderRecipe` and `headerForLayout` are deliberately absent: the only
+ * supported way to compile a header is `compileHeaderLayoutStyleSelection`,
+ * which resolves the recipe and applies the interaction palette. A consumer
+ * reaching the interpreter directly would be a second compilation authority,
+ * which is the thing #1318 removes.
+ */
+export { type HeaderStyleRecipe, type HeaderStyleRecipeCore, type HeaderToneRecipe, type HeaderBackgroundRecipe, type HeaderNavRecipe, type HeaderShadowRecipe, type HeaderFrameRecipe, } from './headerStyleRecipe';
+export { defaultHeaderStyleRecipes, resolveHeaderStyleRecipe, type HeaderStyleRecipeOverrides, type HeaderStyleRecipeOwner, } from './headerStyleDefaults';
 export declare const guaranteedFallbackHeaderLayoutId: import("../../../blocks/src/index").HeaderLayoutId;
 export declare const guaranteedFallbackHeaderStyleId: import("../../../blocks/src/index").HeaderStyleId;

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

@@ -1,5 +1,4 @@
 import type { ThemeHeader } from '../schema';
-import type { HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
 import type { ResolvedSurfaceForeground } from '../surfaces';
 import { type BrandDisplayMode, type LogoAccommodationOption, type LogoFacts, type LogoSizePolicy } from './logoBranding';
 import { type Brand } from './types';
@@ -47,15 +46,19 @@ export type HeaderLayoutDefinition = Readonly<{
     logoAccommodations: readonly LogoAccommodationOption[];
     openingRequirement: HeaderOpeningRequirement;
 }>;
+/**
+ * Metadata only: what a style is called and where it may be used. Never what it
+ * looks like — every appearance field moved to `HeaderStyleRecipe` in #1318
+ * (`navTypography` under ledger D7, then `openingForegroundTarget`,
+ * `scrollTreatment` and `interactionPalette` under D19), so a site style can own
+ * all of it. If a field here ever answers "what does this look like", it is in
+ * the wrong file.
+ */
 export type HeaderStyleDefinition = Readonly<{
     id: HeaderStyleId;
     label: string;
     description: string;
     supportedLayoutIds: readonly HeaderLayoutId[];
-    navTypography: HeaderStyleNavTypography;
-    openingForegroundTarget?: 'brand-only' | 'all';
-    scrollTreatment?: 'contrast-glass';
-    interactionPalette?: HeaderInteractionPaletteOptionGroup;
 }>;
 export type HeaderLayoutStyleSelection = Readonly<{
     layoutId: HeaderLayoutId;

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

@@ -1,6 +1,6 @@
 import type { Theme } from '../schema';
 import type { ResolvedSurfaceForeground } from '../surfaces';
-import type { HeaderStyleDefinition } from './headerLayoutTypes';
+import type { HeaderStyleRecipe } from './headerStyleRecipe';
 export type HeaderOpeningForegroundContext = Readonly<{
     openingForeground: ResolvedSurfaceForeground;
 }>;
@@ -10,9 +10,9 @@ export type HeaderStyleAvailability = Readonly<{
     kind: 'unavailable';
     reason: 'requires-known-opening-foreground';
 }>;
-export declare function headerStyleAvailability(style: HeaderStyleDefinition, context: Partial<HeaderOpeningForegroundContext> | undefined): HeaderStyleAvailability;
+export declare function headerStyleAvailability(recipe: HeaderStyleRecipe, context: Partial<HeaderOpeningForegroundContext> | undefined): HeaderStyleAvailability;
 export declare function headerStyleAvailabilityReasonLabel(reason: Extract<HeaderStyleAvailability, {
     kind: 'unavailable';
 }>['reason']): string;
-export declare function applyOpeningForeground(theme: Theme, header: Theme['header'], style: HeaderStyleDefinition, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme['header'];
-export declare function applyPageOpeningForegroundToTheme(theme: Theme, style: HeaderStyleDefinition | null | undefined, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme;
+export declare function applyOpeningForeground(theme: Theme, header: Theme['header'], recipe: HeaderStyleRecipe, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme['header'];
+export declare function applyPageOpeningForegroundToTheme(theme: Theme, recipe: HeaderStyleRecipe | null | undefined, context: Partial<HeaderOpeningForegroundContext> | undefined): Theme;

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

@@ -0,0 +1,162 @@
+import type { Theme, ThemeHeader } from '../schema';
+import { type SiteChromeBackgroundOverride } from './siteChromeBackgrounds';
+import { type HeaderNavFontSizePreference, type HeaderNavTypographyPreference } from './siteChromeNavPreferences';
+import type { HeaderInteractionPalettePreference } from '../header/interactionPalette';
+import { type HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
+import { type HeaderBrandPresentationPreference } from './headerBrandPresentation';
+import type { BrandDisplayMode, HeaderBrandPresentationSelection, LogoSizePolicy } from './logoBranding';
+export type HeaderLogoTextIntent = NonNullable<ThemeHeader['logoText']>;
+/**
+ * Site-agnostic overrides of the layout's structural defaults (#1318 D15).
+ *
+ * `'inherit'` means "take whatever the row's own (layout, recipe) compiles". It
+ * is a sentinel rather than an absent field so that "the user has not chosen"
+ * stays distinguishable from "the user chose the value that happens to equal
+ * the layout default" — the distinction an optional field cannot carry.
+ *
+ * `logoText` has a third state because the classic layout compiles a value and
+ * a row can legitimately carry none: `'none'` is an explicit "no logo text
+ * accommodation", which `'inherit'` would silently turn back into the layout's.
+ */
+export type HeaderStructurePreferences = Readonly<{
+    positioning: 'inherit' | ThemeHeader['positioning'];
+    shrinkOnScroll: 'inherit' | boolean;
+    logoText: 'inherit' | 'none' | HeaderLogoTextIntent;
+}>;
+/**
+ * Everything a user can express about a header, as intent rather than as
+ * compiled bytes. The first six fields already persist inside `theme.header`
+ * today and have readers; `structure` is new (D15).
+ */
+export type HeaderPreferences = Readonly<{
+    /**
+     * Whether the header wears a brand presentation at all. `'plain'` is the
+     * state several live rows persist — no `logo` block — which the record could
+     * not express before (#1318 Phase 4c decision 5b, D24).
+     */
+    brandPresentation: HeaderBrandPresentationPreference;
+    brandDisplay: BrandDisplayMode;
+    logoSize: LogoSizePolicy;
+    navFontRole: HeaderNavTypographyPreference;
+    navTextSize: HeaderNavFontSizePreference;
+    interactionPalette: HeaderInteractionPalettePreference;
+    background: SiteChromeBackgroundOverride;
+    structure: HeaderStructurePreferences;
+}>;
+export declare const defaultHeaderStructurePreferences: HeaderStructurePreferences;
+export declare const defaultHeaderPreferences: HeaderPreferences;
+/**
+ * The written-down backfill rule (#1318 Phase 4a): compare the persisted value
+ * against the value the row's own (layout, recipe) compiles, and emit
+ * `'inherit'` when they are equal, the explicit value when they are not.
+ *
+ * Equal-to-default therefore collapses to `'inherit'`. Nothing in the data
+ * distinguishes a deliberate "sticky, same as the default" from an untouched
+ * row, so the backfill does not pretend to recover it; going forward the editor
+ * records what the user picks and the distinction is real for new intent.
+ *
+ * Two qualifications on "the value it compiles", both of which keep the rule
+ * from inventing intent:
+ *
+ * 1. A value that no vocabulary accepts expresses nothing, so it derives to
+ *    `'inherit'` rather than to whatever a fallback would have picked.
+ * 2. A field a later pipeline step overwrites unconditionally cannot carry
+ *    intent at all. That is `shrinkOnScroll` on a display-logo row — see
+ *    `headerBrandPresentationForcesShrink`.
+ */
+export declare function readHeaderStructurePreferences(persisted: ThemeHeader, compiled: ThemeHeader): HeaderStructurePreferences;
+/**
+ * Total over any persisted theme, including a malformed one: every field goes
+ * through a reader that closes over the vocabulary rather than trusting the
+ * stored value.
+ *
+ * `compiledHeader` is the structure baseline — the header this row's own
+ * (layout, recipe) compiles. It is a required parameter rather than something
+ * derived inside, because a `Theme` alone does not carry the selection ids the
+ * baseline needs; asking the caller for it keeps the rule single-valued.
+ *
+ * `navTextSize` is derived against that same baseline rather than read off
+ * `header.navTextSize` (#1318 Phase 4c decision 1). It is the one nav field a
+ * pre-preferences row could express only through the compiled bytes, so
+ * reading the marker alone loses it — see
+ * `readHeaderNavFontSizeAgainstBaseline`. `navFontRole` stays a marker read:
+ * unlike size, `navLinkStyle.typography` is written by the recipe's own
+ * treatment on every row, so a baseline comparison there would report the
+ * treatment's default role as user intent.
+ *
+ * `interactionPaletteGroup` is the palette the row's resolved recipe offers,
+ * and the same reasoning applies to it (#1318 Phase 4c decision 2): a row that
+ * predates the palette carries its hover treatment in the compiled bytes and
+ * nothing in `header.interactionPalette`. `undefined` means the caller does not
+ * know which palette applies — it is not "the style has none" — and the marker
+ * read stands.
+ *
+ * `brandPresentationCandidates` are the two headers the two presentation modes
+ * produce for this row. The mode is derived by comparing the persisted `logo`
+ * against both, so a row that carries no presentation block keeps having none
+ * instead of being given one it has never rendered (#1318 Phase 4c decision
+ * 5b). They are supplied rather than rebuilt here because they are the
+ * compilation's own output, and a second construction of them would be a second
+ * authority on what the modes mean — `headerBrandPresentationCandidates` builds
+ * them with the real appliers.
+ */
+export declare function readHeaderPreferences(theme: Theme, compiledHeader: ThemeHeader, interactionPaletteGroup: HeaderInteractionPaletteOptionGroup | undefined, brandPresentationCandidates: HeaderBrandPresentationCandidates): HeaderPreferences;
+/** The header each brand-presentation mode compiles to, for one row. */
+export type HeaderBrandPresentationCandidates = Readonly<{
+    recommended: ThemeHeader;
+    plain: ThemeHeader;
+}>;
+/**
+ * Both candidates, built with the same two appliers the pipeline uses.
+ *
+ * There is no circularity to resolve: the only record fields that reach
+ * `header.logo` are `brandDisplay` and `logoSize`, and those are read straight
+ * off the persisted theme rather than derived. The structure preferences run
+ * before the presentation in the named order but touch `positioning`,
+ * `shrinkOnScroll` and `logoText` — never `logo` — so leaving them out here
+ * cannot change either answer.
+ *
+ * One known over-specification, recorded rather than fixed because it changes
+ * no bytes. `applyHeaderBrandPresentation` reads `positioning` when it decides
+ * whether to force `shrinkOnScroll` for a display logo, and it sees the
+ * *structure-adjusted* value at apply time while it sees the layout default
+ * here. On a `'recommended'` row that overrides positioning to `'static'` the
+ * candidate can therefore carry a forced `shrinkOnScroll` the applied header
+ * will not, which makes `readHeaderStructurePreferences` emit an explicit
+ * `shrinkOnScroll` where `'inherit'` would have done. The record is more
+ * specific than it needs to be; the compiled bytes are identical either way,
+ * because the explicit value it writes is the one the row already has. Fixing
+ * it means deriving `positioning` before the candidates, which is a second
+ * derivation pass for no byte change (#1318 Phase 4c review round 2, item 10).
+ */
+export declare function headerBrandPresentationCandidates(theme: Theme, compiledBaseline: ThemeHeader, presentation: HeaderBrandPresentationSelection | null): HeaderBrandPresentationCandidates;
+export declare function applyHeaderStructurePreferences(header: ThemeHeader, preferences: HeaderStructurePreferences): ThemeHeader;
+/**
+ * The brand presentation step, which sits between the structure preferences and
+ * the nav/logo/background ones because it reads `positioning` and can force
+ * `shrinkOnScroll` for a display logo (`previewCompiler.ts`).
+ */
+/**
+ * Writes a resolved brand presentation onto the header. Lives here rather than
+ * in `previewCompiler` so the pipeline step has one definition: it sits between
+ * the structure preferences and the nav/logo/background ones, and it is the
+ * reason that position is load-bearing — it reads `positioning` and can force
+ * `shrinkOnScroll` for a display logo that brings its own backing.
+ */
+export declare function applyHeaderBrandPresentation(header: ThemeHeader, presentation: HeaderBrandPresentationSelection): ThemeHeader;
+/**
+ * The preference half of the header pipeline, composed once so that no caller
+ * assembles its own order. Named order, tail of the recompile:
+ *
+ *   structure preferences → brand presentation → brand display/logo size
+ *   → nav preferences → header background override
+ *
+ * `brandPresentation` is data rather than a callback so the step is inspectable
+ * and cannot vary by caller; `null` is "this caller has no logo context".
+ *
+ * The background applier is the header-only one on purpose: the header+footer
+ * pair function would clobber footer intent (#1318 Correction 20).
+ */
+export declare function applyHeaderPreferences(theme: Theme, preferences: HeaderPreferences, brandPresentation: HeaderBrandPresentationSelection | null): Theme;
+/** The fields authored by header quick controls; structure and presentation belong to the row. */
+export type HeaderQuickControlPreferences = Pick<HeaderPreferences, 'brandDisplay' | 'logoSize' | 'navFontRole' | 'navTextSize' | 'interactionPalette' | 'background'>;

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

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { type SiteChromeBackgroundColorToken } from './siteChromeBackgrounds';
+import type { HeaderPreferences } from './headerPreferences';
+/**
+ * The persisted shape of `HeaderPreferences`, closed at every field.
+ *
+ * `.strict()` throughout is deliberate: an unknown key in the stored blob means
+ * the writer knew about a field this reader does not, and silently dropping it
+ * would let a save round-trip away someone else's intent. Every field is
+ * required for the same reason a default would be a hidden authority: a stored
+ * record that omits one is not a record this reader may complete.
+ */
+export declare const headerPreferencesSchema: z.ZodType<HeaderPreferences>;
+/** Only controls the client can edit may cross the write boundary. */
+export declare const headerPreferencesWireSchema: z.ZodObject<{
+    background: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"default">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"color">;
+        token: z.ZodType<SiteChromeBackgroundColorToken, unknown, z.core.$ZodTypeInternals<SiteChromeBackgroundColorToken, unknown>>;
+    }, z.core.$strict>], "kind">;
+    navTextSize: z.ZodEnum<{
+        base: "base";
+        sm: "sm";
+        lg: "lg";
+        xl: "xl";
+        inherit: "inherit";
+    }>;
+    navFontRole: z.ZodEnum<{
+        heading: "heading";
+        body: "body";
+        inherit: "inherit";
+    }>;
+    interactionPalette: z.ZodUnion<readonly [z.ZodLiteral<"recommended">, z.ZodEnum<{
+        accent: "accent";
+        primary: "primary";
+        secondary: "secondary";
+        quiet: "quiet";
+    }>]>;
+    brandDisplay: z.ZodEnum<{
+        auto: "auto";
+        "logo-only": "logo-only";
+        "logo-plus-title": "logo-plus-title";
+        "title-only": "title-only";
+    }>;
+    logoSize: z.ZodEnum<{
+        auto: "auto";
+        display: "display";
+        standard: "standard";
+        compact: "compact";
+        generous: "generous";
+    }>;
+}, z.core.$strict>;
+/**
+ * The read boundary for `site_theme_selections.header_preferences`.
+ *
+ * Three outcomes, never a throw and never a silent default: the column is
+ * nullable while the Phase 4c backfill is outstanding, so "absent" is a real
+ * and expected state that a caller must handle by deriving from the legacy
+ * theme with `readHeaderPreferences`. "Invalid" is separate from "absent"
+ * because the two want different responses — one is a backlog item, the other
+ * is a bug or a hand-edited row.
+ */
+export type PersistedHeaderPreferences = Readonly<{
+    kind: 'present';
+    preferences: HeaderPreferences;
+}> | Readonly<{
+    kind: 'absent';
+}> | Readonly<{
+    kind: 'invalid';
+    issues: readonly string[];
+}>;
+export declare function parsePersistedHeaderPreferences(value: unknown): PersistedHeaderPreferences;

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

@@ -0,0 +1,118 @@
+import type { Theme, ThemeHeader } from '../schema';
+import { type CuratedSiteStyle } from './curatedSiteStyles';
+import { type HeaderLayoutStyleResolution, type HeaderLayoutStyleSelection } from './headerLayoutStyles';
+import { type HeaderPreferences } from './headerPreferences';
+import { type HeaderInteractionPaletteBytesClassification, type HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
+import { type HeaderBrandPresentationBytesClassification } from './headerBrandPresentation';
+import type { HeaderInteractionPalettePreference } from '../header/interactionPalette';
+import type { HeaderBrandPresentationSelection } from './logoBranding';
+import type { ReplacementBrandPresentation } from './compilationPlan';
+export type CuratedHeaderSelectionRepair = Readonly<{
+    kind: 'exact';
+}> | Readonly<{
+    kind: 'repaired';
+    reason: 'style-not-curated-for-layout' | 'layout-not-curated-for-site-style';
+}>;
+export type CuratedHeaderSelectionResolution = Readonly<{
+    resolution: HeaderLayoutStyleResolution;
+    repair: CuratedHeaderSelectionRepair;
+}>;
+/**
+ * Curated repair followed by catalogue repair — the first two steps of the
+ * header compilation pipeline, in one place so no caller re-derives them.
+ */
+export declare function resolveCuratedHeaderSelection(siteStyle: CuratedSiteStyle, requested: HeaderLayoutStyleSelection): CuratedHeaderSelectionResolution;
+/**
+ * Which interaction palette a compilation should use.
+ *
+ * `derive-from-persisted-bytes` is the backfill's answer, and it is a request
+ * rather than a value because the derivation needs the option list the resolved
+ * recipe offers, which only the compilation knows. It mirrors
+ * `ReplacementBrandPresentation`: the caller states what it wants, the
+ * composition resolves it.
+ */
+export type HeaderInteractionPaletteRequest = Readonly<{
+    kind: 'preference';
+    preference: HeaderInteractionPalettePreference;
+}> | Readonly<{
+    kind: 'derive-from-persisted-bytes';
+}>;
+export type CompiledCuratedHeader = Readonly<{
+    /** Recipe and interaction palette only — the structure-derivation baseline. */
+    baseline: ThemeHeader;
+    /** `baseline` with the brand presentation applied, when there is one. */
+    header: ThemeHeader;
+    /** The presentation the request resolved to against the chosen layout. */
+    brandPresentation: HeaderBrandPresentationSelection | null;
+    /**
+     * The palette the resolved recipe offers, so a caller deriving intent from
+     * persisted bytes has the option list without re-resolving the recipe or
+     * guessing at it (#1318 Phase 4c decision 2).
+     */
+    interactionPalette: HeaderInteractionPaletteOptionGroup | undefined;
+    resolution: HeaderLayoutStyleResolution;
+    repair: CuratedHeaderSelectionRepair;
+}>;
+/**
+ * Curated repair → catalogue repair → recipe → interaction palette → brand
+ * presentation. Everything that runs before the preference record, in one
+ * place: `previewCompiler.compileHeaderDirective` and the recompile below are
+ * both callers, so the middle of the pipeline has a single composition.
+ *
+ * `baseline` and `header` are both returned because they answer different
+ * questions. `header` is what a preview wants to render. `baseline` is what
+ * `readHeaderPreferences` compares the persisted bytes against for every field
+ * the presentation does not touch.
+ *
+ * The interaction-palette preference is threaded in through `theme.header`
+ * because that is where `compileHeaderLayoutStyleSelection` reads it from
+ * today; 4b can pass it explicitly once the preferences column exists.
+ */
+export declare function compileHeaderForCuratedSelection(theme: Theme, siteStyle: CuratedSiteStyle, requested: HeaderLayoutStyleSelection, requestedBrandPresentation: ReplacementBrandPresentation, requestedInteractionPalette: HeaderInteractionPaletteRequest): CompiledCuratedHeader;
+export type RecompileSiteChromeHeaderInput = Readonly<{
+    theme: Theme;
+    siteStyle: CuratedSiteStyle;
+    requested: HeaderLayoutStyleSelection;
+    preferences: HeaderPreferences;
+    brandPresentation: ReplacementBrandPresentation;
+}>;
+export type RecompiledSiteChromeHeader = Readonly<{
+    header: ThemeHeader;
+    resolution: HeaderLayoutStyleResolution;
+    repair: CuratedHeaderSelectionRepair;
+}>;
+/**
+ * The whole header pipeline, in one named function so 4b, 4c and 4d cannot
+ * drift into three orders (#1318 Phase 4):
+ *
+ *   curated repair → catalogue repair → recipe → layout defaults
+ *   → interaction palette → structure preferences → brand presentation
+ *   → nav/logo/background preferences
+ */
+export declare function recompileSiteChromeHeader(input: RecompileSiteChromeHeaderInput): RecompiledSiteChromeHeader;
+/**
+ * The read-then-recompile round trip: derive the row's intent from its own
+ * persisted bytes, then rebuild the header from that intent. On a row whose
+ * bytes are compiler output this returns the persisted header unchanged, which
+ * is what the Phase 4c divergence report measures.
+ */
+export declare function recompileSiteChromeHeaderFromPersistedIntent(theme: Theme, siteStyle: CuratedSiteStyle, requested: HeaderLayoutStyleSelection, brandPresentation: ReplacementBrandPresentation): Readonly<{
+    recompiled: RecompiledSiteChromeHeader;
+    preferences: HeaderPreferences;
+    /**
+     * How the row's own bytes answered the interaction-palette question. Reported
+     * rather than folded into `preferences`, because `'unrecognised'` has no
+     * representation there: the record falls back to the marker field, and a
+     * caller that cares — the Phase 4c divergence report — needs to say so rather
+     * than let a pill nobody recognises be dropped on the next recompile.
+     */
+    interactionPaletteBytes: HeaderInteractionPaletteBytesClassification;
+    /**
+     * How the row's own bytes answered the brand-presentation question, reported
+     * for the same reason as the palette: `'unrecognised'` has no representation
+     * in the record, and a caller that cares — the Phase 4c divergence report and
+     * the repair generator — must be able to say so rather than let a logo
+     * treatment nobody recognises be written or dropped.
+     */
+    brandPresentationBytes: HeaderBrandPresentationBytesClassification;
+}>;

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

@@ -1,3 +1,26 @@
 import type { Theme } from '../schema';
-import { type HeaderLayoutStyleResolution } from './headerLayoutTypes';
-export declare function compileHeaderLayoutStyleSelection(theme: Theme, resolution: HeaderLayoutStyleResolution): Theme['header'];
+import type { HeaderInteractionPalettePreference } from '../header/interactionPalette';
+import type { HeaderLayoutStyleResolution } from './headerLayoutTypes';
+import { type HeaderStyleRecipeOwner } from './headerStyleDefaults';
+/**
+ * The header compilation pipeline: pick the recipe, interpret it, then apply
+ * the user's interaction-palette preference.
+ *
+ * Appearance decisions live in `headerStyleDefaults.ts` (data), optionally
+ * taken over per site style, and `headerStyleRecipe.ts` (one pure interpreter).
+ * Nothing here switches on a header style id.
+ *
+ * `siteStyle` is required rather than optional: a caller that has no resolved
+ * site style has to say so, because silently falling back to the catalogue
+ * default is exactly the ownership leak this slice closes. Pass `null` when
+ * there genuinely is no site style (initial site provisioning).
+ *
+ * `interactionPalette` is a parameter rather than a read off
+ * `theme.header.interactionPalette` (#1318 Phase 4c). The marker field on the
+ * header is where the preference is *persisted*, but taking it from there made
+ * the palette the one preference the compiler could not be told about — which
+ * is invisible while the marker always equals what was compiled and wrong the
+ * moment a backfill supplies a different one. The caller that owns the
+ * preference record now says which palette to compile.
+ */
+export declare function compileHeaderLayoutStyleSelection(theme: Theme, resolution: HeaderLayoutStyleResolution, siteStyle: HeaderStyleRecipeOwner | null, interactionPalette: HeaderInteractionPalettePreference): Theme['header'];