@riverbankcms/sdk 0.136.0 → 0.138.0

package/dist/_dts/theme-core/src/shared/componentStyles.d.ts

@@ -16,8 +16,8 @@ import { z } from 'zod';
  */
 export declare const componentBorderSchema: z.ZodObject<{
     width: z.ZodDefault<z.ZodEnum<{
-        medium: "medium";
         none: "none";
+        medium: "medium";
         thin: "thin";
         thick: "thick";
         hairline: "hairline";

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

@@ -2,6 +2,6 @@ import { type ThemeColorToken } from '../tokens';
 export declare const backgroundAppearanceQuickColorTokenNames: readonly ["background", "surface", "muted", "primary", "secondary", "accent"];
 export declare const backgroundAppearanceBaseColorTokenNames: readonly ["background", "surface", "surfaceAlt", "muted", "primary", "secondary", "accent", "neutral"];
 export declare const backgroundAppearanceShadeableColorTokenNames: readonly ["primary", "secondary", "accent", "neutral"];
-export declare const backgroundAppearanceColorTokenNames: readonly ("surface" | "background" | "accent" | "muted" | "primary" | "secondary" | "surfaceAlt" | "neutral" | "neutral-600" | "neutral-500" | "neutral-800" | "neutral-700" | "neutral-900" | "primary-500" | "primary-400" | "neutral-950" | "primary-300" | "primary-600" | "secondary-600" | "accent-600" | "secondary-500" | "accent-400" | "neutral-50" | "neutral-100" | "neutral-200" | "neutral-300" | "secondary-400" | "neutral-400" | "primary-100" | "primary-50" | "primary-900" | "secondary-50" | "secondary-900" | "accent-50" | "accent-500" | "accent-900" | "primary-800" | "primary-700" | "accent-100" | "accent-200" | "accent-300" | "accent-700" | "accent-800" | "accent-950" | "primary-200" | "primary-950" | "secondary-100" | "secondary-200" | "secondary-300" | "secondary-700" | "secondary-800" | "secondary-950")[];
-export declare const backgroundAppearanceAdvancedColorTokenNames: ("surface" | "background" | "accent" | "muted" | "primary" | "secondary" | "surfaceAlt" | "neutral" | "neutral-600" | "neutral-500" | "neutral-800" | "neutral-700" | "neutral-900" | "primary-500" | "primary-400" | "neutral-950" | "primary-300" | "primary-600" | "secondary-600" | "accent-600" | "secondary-500" | "accent-400" | "neutral-50" | "neutral-100" | "neutral-200" | "neutral-300" | "secondary-400" | "neutral-400" | "primary-100" | "primary-50" | "primary-900" | "secondary-50" | "secondary-900" | "accent-50" | "accent-500" | "accent-900" | "primary-800" | "primary-700" | "accent-100" | "accent-200" | "accent-300" | "accent-700" | "accent-800" | "accent-950" | "primary-200" | "primary-950" | "secondary-100" | "secondary-200" | "secondary-300" | "secondary-700" | "secondary-800" | "secondary-950")[];
+export declare const backgroundAppearanceColorTokenNames: readonly ("surface" | "background" | "primary" | "secondary" | "accent" | "surfaceAlt" | "muted" | "neutral" | "neutral-600" | "neutral-500" | "neutral-800" | "neutral-700" | "neutral-900" | "primary-500" | "primary-400" | "neutral-950" | "primary-300" | "primary-600" | "secondary-600" | "accent-600" | "secondary-500" | "accent-400" | "neutral-50" | "neutral-100" | "neutral-200" | "neutral-300" | "secondary-400" | "neutral-400" | "primary-100" | "primary-800" | "primary-900" | "primary-700" | "primary-50" | "secondary-50" | "secondary-900" | "accent-50" | "accent-500" | "accent-900" | "primary-200" | "primary-950" | "secondary-100" | "secondary-200" | "secondary-300" | "secondary-700" | "secondary-800" | "secondary-950" | "accent-100" | "accent-200" | "accent-300" | "accent-700" | "accent-800" | "accent-950")[];
+export declare const backgroundAppearanceAdvancedColorTokenNames: ("surface" | "background" | "primary" | "secondary" | "accent" | "surfaceAlt" | "muted" | "neutral" | "neutral-600" | "neutral-500" | "neutral-800" | "neutral-700" | "neutral-900" | "primary-500" | "primary-400" | "neutral-950" | "primary-300" | "primary-600" | "secondary-600" | "accent-600" | "secondary-500" | "accent-400" | "neutral-50" | "neutral-100" | "neutral-200" | "neutral-300" | "secondary-400" | "neutral-400" | "primary-100" | "primary-800" | "primary-900" | "primary-700" | "primary-50" | "secondary-50" | "secondary-900" | "accent-50" | "accent-500" | "accent-900" | "primary-200" | "primary-950" | "secondary-100" | "secondary-200" | "secondary-300" | "secondary-700" | "secondary-800" | "secondary-950" | "accent-100" | "accent-200" | "accent-300" | "accent-700" | "accent-800" | "accent-950")[];
 export declare function parseBackgroundAppearanceColorToken(value: unknown): ThemeColorToken | null;

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

@@ -41,8 +41,8 @@ export declare function cardRoleFromLegacyVocabulary(value: unknown): CardRole |
  * the role they meant, everything else fails the parse.
  */
 export declare const cardRoleWithLegacyAliasSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
-    open: "open";
     none: "none";
+    open: "open";
     default: "default";
     alternative: "alternative";
 }>>;

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/designState.d.ts

@@ -85,10 +85,10 @@ export type PageStyleAuthoritySummary<TBlockId extends string = DesignBlockId> =
 export declare const styleAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"theme-v2">;
     source: z.ZodEnum<{
-        admin: "admin";
-        sdk: "sdk";
         generated: "generated";
         user: "user";
+        admin: "admin";
+        sdk: "sdk";
     }>;
     siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
     templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;
@@ -118,10 +118,10 @@ export declare const blockRuntimeStyleAuthoritySchema: z.ZodObject<{
     authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"theme-v2">;
         source: z.ZodEnum<{
-            admin: "admin";
-            sdk: "sdk";
             generated: "generated";
             user: "user";
+            admin: "admin";
+            sdk: "sdk";
         }>;
         siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
         templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;

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

@@ -83,8 +83,8 @@ export declare const generatedBlockDesignIntentSchema: z.ZodObject<{
         source: z.ZodLiteral<"generated">;
         kind: z.ZodLiteral<"explicit">;
         value: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
-            open: "open";
             none: "none";
+            open: "open";
             default: "default";
             alternative: "alternative";
         }>>;
@@ -234,8 +234,8 @@ export declare const generatedPageDesignIntentSchema: z.ZodObject<{
                 source: z.ZodLiteral<"generated">;
                 kind: z.ZodLiteral<"explicit">;
                 value: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
-                    open: "open";
                     none: "none";
+                    open: "open";
                     default: "default";
                     alternative: "alternative";
                 }>>;

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: "primary" | "secondary" | "accent" | "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'>;

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<{
+        primary: "primary";
+        secondary: "secondary";
+        accent: "accent";
+        quiet: "quiet";
+    }>]>;
+    brandDisplay: z.ZodEnum<{
+        auto: "auto";
+        "logo-only": "logo-only";
+        "logo-plus-title": "logo-plus-title";
+        "title-only": "title-only";
+    }>;
+    logoSize: z.ZodEnum<{
+        display: "display";
+        auto: "auto";
+        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;