@riverbankcms/sdk 0.136.0 → 0.137.0

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

@@ -50,3 +50,8 @@ export declare const gradientConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GradientConfig = z.infer<typeof gradientConfigSchema>;
+export declare const gradientsSchema: z.ZodObject<{
+    button: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hero: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    background: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;

package/dist/_dts/theme-core/src/header/interactionPalette.d.ts

@@ -1,9 +1,27 @@
 import { z } from 'zod';
-export declare const headerInteractionPaletteValues: readonly ["primary", "secondary", "accent"];
+/**
+ * The palettes that fill the nav link with a colour on hover and focus. Each
+ * one names a background/foreground token pair.
+ */
+export declare const headerInteractionPillPaletteValues: readonly ["primary", "secondary", "accent"];
+export type HeaderInteractionPillPalette = (typeof headerInteractionPillPaletteValues)[number];
+/**
+ * "No pill": the nav link keeps whatever hover treatment its recipe compiled,
+ * and the palette step writes nothing at all (#1318 Phase 4c decision 2).
+ *
+ * It exists because "a colour change on hover, no filled background" was not
+ * expressible in the vocabulary, and it is what
+ * `anna-raven-therapy-and-yoga` and `kirtan-lucy` have rendered since before
+ * the palette existed. Without it those two rows can only be classified as a
+ * conscious visual change.
+ */
+export declare const headerInteractionQuietPalette = "quiet";
+export declare const headerInteractionPaletteValues: readonly ["primary", "secondary", "accent", "quiet"];
 export declare const headerInteractionPaletteSchema: z.ZodEnum<{
     accent: "accent";
     primary: "primary";
     secondary: "secondary";
+    quiet: "quiet";
 }>;
 export type HeaderInteractionPalette = z.infer<typeof headerInteractionPaletteSchema>;
 export type HeaderInteractionPalettePreference = 'recommended' | HeaderInteractionPalette;
@@ -11,4 +29,9 @@ export type HeaderInteractionPalettePair = Readonly<{
     backgroundToken: 'primary' | 'secondary' | 'accent';
     foregroundToken: 'onPrimary' | 'onSecondary' | 'onAccent';
 }>;
-export declare function headerInteractionPalettePair(palette: HeaderInteractionPalette): HeaderInteractionPalettePair;
+/**
+ * Narrowed to the pill palettes on purpose: `'quiet'` has no token pair, and a
+ * caller that reaches this function without excluding it first is a type error
+ * rather than a runtime surprise.
+ */
+export declare function headerInteractionPalettePair(palette: HeaderInteractionPillPalette): HeaderInteractionPalettePair;

package/dist/_dts/theme-core/src/mock-themes/all.d.ts

@@ -419,7 +419,7 @@ export declare const mockThemes: {
                 navColor?: string | null | undefined;
                 navFontRole?: "heading" | "body" | undefined;
                 navTextSize?: "base" | "sm" | "lg" | "xl" | "xs" | undefined;
-                interactionPalette?: "accent" | "primary" | "secondary" | undefined;
+                interactionPalette?: "accent" | "primary" | "secondary" | "quiet" | undefined;
                 container?: {
                     rounded: "none" | "sm" | "md" | "lg" | "xl" | "2xl";
                     border: boolean;
@@ -2702,7 +2702,7 @@ export declare const mockThemes: {
                 navColor?: string | null | undefined;
                 navFontRole?: "heading" | "body" | undefined;
                 navTextSize?: "base" | "sm" | "lg" | "xl" | "xs" | undefined;
-                interactionPalette?: "accent" | "primary" | "secondary" | undefined;
+                interactionPalette?: "accent" | "primary" | "secondary" | "quiet" | undefined;
                 container?: {
                     rounded: "none" | "sm" | "md" | "lg" | "xl" | "2xl";
                     border: boolean;
@@ -4985,7 +4985,7 @@ export declare const mockThemes: {
                 navColor?: string | null | undefined;
                 navFontRole?: "heading" | "body" | undefined;
                 navTextSize?: "base" | "sm" | "lg" | "xl" | "xs" | undefined;
-                interactionPalette?: "accent" | "primary" | "secondary" | undefined;
+                interactionPalette?: "accent" | "primary" | "secondary" | "quiet" | undefined;
                 container?: {
                     rounded: "none" | "sm" | "md" | "lg" | "xl" | "2xl";
                     border: boolean;

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

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { mediaIdentifierSchema, imageMediaSchema, mediaSchema, mediaTypeDiscriminants, persistableMediaSchema, videoMediaSchema } from './lib/media';
 import type { ExpandedPalette } from './palette/expandPalette';
 import { paletteSchema, type paletteMetaSchema } from './palette/schema';
+import { gradientsSchema } from './gradients/types';
+export { gradientsSchema } from './gradients/types';
 import { headerVariantValues, type headerVariantSchema } from './header/legacyHeaderVariant';
 import { headerContainerSchema } from './header/containerSchema';
 import { boxBackgroundOverlaySchema, boxBackgroundSchema } from './boxBackgroundSchema';
@@ -2463,6 +2465,7 @@ export declare const inputStyle: z.ZodObject<{
         inside: "inside";
     }>;
 }, z.core.$strip>;
+export declare const headerPositioningValues: readonly ["static", "sticky", "fixed"];
 declare const headerPositioning: z.ZodEnum<{
     fixed: "fixed";
     static: "static";
@@ -2905,10 +2908,10 @@ export declare const headerSchema: z.ZodObject<{
         sticky: "sticky";
     }>;
     shrinkOnScroll: z.ZodBoolean;
-    maxWidth: z.ZodEnum<{
+    maxWidth: z.ZodDefault<z.ZodEnum<{
         full: "full";
         container: "container";
-    }>;
+    }>>;
     scrollTreatment: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"contrast-glass">;
         backgroundTone: z.ZodEnum<{
@@ -3234,6 +3237,7 @@ export declare const headerSchema: z.ZodObject<{
         accent: "accent";
         primary: "primary";
         secondary: "secondary";
+        quiet: "quiet";
     }>>;
     container: z.ZodOptional<z.ZodObject<{
         rounded: z.ZodDefault<z.ZodEnum<{
@@ -4455,11 +4459,6 @@ declare const bodyTextSchema: z.ZodOptional<z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>>;
-export declare const gradientsSchema: z.ZodObject<{
-    button: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    hero: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    background: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, z.core.$strip>;
 /**
  * Testimonial quote-mark treatment, owned by the site style (analogous to the
  * accordion icon). `style` is the coarse selector; the optional fields fine-tune
@@ -5110,10 +5109,10 @@ export declare const themeSchema: z.ZodObject<{
             sticky: "sticky";
         }>;
         shrinkOnScroll: z.ZodBoolean;
-        maxWidth: z.ZodEnum<{
+        maxWidth: z.ZodDefault<z.ZodEnum<{
             full: "full";
             container: "container";
-        }>;
+        }>>;
         scrollTreatment: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"contrast-glass">;
             backgroundTone: z.ZodEnum<{
@@ -5439,6 +5438,7 @@ export declare const themeSchema: z.ZodObject<{
             accent: "accent";
             primary: "primary";
             secondary: "secondary";
+            quiet: "quiet";
         }>>;
         container: z.ZodOptional<z.ZodObject<{
             rounded: z.ZodDefault<z.ZodEnum<{
@@ -9020,10 +9020,10 @@ export declare const themesTurnSchema: z.ZodObject<{
                 sticky: "sticky";
             }>;
             shrinkOnScroll: z.ZodBoolean;
-            maxWidth: z.ZodEnum<{
+            maxWidth: z.ZodDefault<z.ZodEnum<{
                 full: "full";
                 container: "container";
-            }>;
+            }>>;
             scrollTreatment: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"contrast-glass">;
                 backgroundTone: z.ZodEnum<{
@@ -9349,6 +9349,7 @@ export declare const themesTurnSchema: z.ZodObject<{
                 accent: "accent";
                 primary: "primary";
                 secondary: "secondary";
+                quiet: "quiet";
             }>>;
             container: z.ZodOptional<z.ZodObject<{
                 rounded: z.ZodDefault<z.ZodEnum<{

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

@@ -146,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;
 /**

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;

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";

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'>;