@riverbankcms/sdk 0.130.0 → 0.132.0

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { type CardRole } from '../cards';
+/**
+ * The legacy `itemSurface` treatment vocabulary, and how it reads as a card
+ * role.
+ *
+ * `itemSurface` named a *treatment* ("raised", "inset"); a role names *which
+ * card* a Look wants and defers the appearance to the site style. Phase 3
+ * deleted the treatment vocabulary and the recipe table it fed, so this map is
+ * no longer a migration coexistence device — it is the one parse boundary where
+ * persisted design plans written before the cutover still load, normalizing to
+ * the role they meant.
+ *
+ * Per-value rationale is recorded in
+ * `.project/plans/1297-card-role-contract-site-styles-own-card-surfaces/mapping-table.md`.
+ */
+export declare const legacyItemSurfaceCardRoles: {
+    readonly none: "none";
+    readonly flat: "default";
+    readonly default: "default";
+    readonly outlined: "default";
+    readonly raised: "default";
+    readonly inset: "alternative";
+    readonly editorial: "open";
+    readonly 'color-blocked': "alternative";
+};
+export type LegacyItemSurfaceValue = keyof typeof legacyItemSurfaceCardRoles;
+/**
+ * The enum form of the legacy vocabulary, for schemas that still parse it.
+ * Derived from the map so the two cannot drift.
+ */
+export declare const legacyItemSurfaceValues: [LegacyItemSurfaceValue, ...LegacyItemSurfaceValue[]];
+/**
+ * Read a card role from untrusted input, accepting the legacy `itemSurface`
+ * vocabulary as aliases. Returns `null` for anything else.
+ */
+export declare function cardRoleFromLegacyVocabulary(value: unknown): CardRole | null;
+/**
+ * The parse boundary for card roles reaching design intents and persisted
+ * design plans: roles pass through, legacy `itemSurface` values normalize to
+ * the role they meant, everything else fails the parse.
+ */
+export declare const cardRoleWithLegacyAliasSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+    open: "open";
+    default: "default";
+    none: "none";
+    alternative: "alternative";
+}>>;

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

@@ -1,4 +1,6 @@
 import type { Theme } from '../schema';
+import type { ButtonSystem } from '../buttons/types';
+import type { ButtonStyleSelection } from '../buttons/styles/selection';
 import type { HeaderLayoutStyleSelection, HeaderLogoContext } from './headerLayoutStyles';
 import type { FooterLookId } from './footerLooks';
 import type { BrandDisplayMode, LogoSizePolicy } from './logoBranding';
@@ -26,6 +28,22 @@ export type FooterCompilationDirective = Readonly<{
     footer: Theme['footer'];
     footerLookId: FooterLookId | null;
 }>;
+export type ButtonUpdateRecompileReason = 'selection-change' | 'missing-applied-buttons';
+export type ButtonRecompileDirective<TReason extends ButtonUpdateRecompileReason = ButtonUpdateRecompileReason> = Readonly<{
+    kind: 'recompile';
+    selection: ButtonStyleSelection;
+    reason: TReason;
+}>;
+export type ReplacementButtonRecompileDirective = Readonly<{
+    kind: 'recompile';
+    selection: ButtonStyleSelection | null;
+    reason: 'site-style-replacement';
+}>;
+export type ButtonCompilationDirective = Readonly<{
+    kind: 'preserve';
+    buttons: ButtonSystem;
+    selection: ButtonStyleSelection;
+}> | ButtonRecompileDirective;
 export type ReplacementBrandPresentation = Readonly<{
     kind: 'apply-logo-context';
     logo: HeaderLogoContext;
@@ -34,15 +52,18 @@ export type ReplacementBrandPresentation = Readonly<{
 }>;
 export type SiteThemeCompilationPlan = Readonly<{
     kind: 'replace-site-style';
+    buttons: ReplacementButtonRecompileDirective;
     header: HeaderRecompileDirective;
     footerLookId: FooterLookId | null;
 }> | Readonly<{
     kind: 'update-selection';
+    buttons: ButtonCompilationDirective;
     header: HeaderCompilationDirective;
     footer: FooterCompilationDirective;
 }>;
 export declare function replaceSiteStyleCompilationPlan(input: Readonly<{
     headerSelection: HeaderLayoutStyleSelection;
+    buttonStyleSelection?: ButtonStyleSelection | null;
     footerLookId?: FooterLookId | null;
     headerLogo?: HeaderLogoContext;
 }>): Extract<SiteThemeCompilationPlan, {

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

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import { type DesignBlockId, type DesignResolutionPolicy, type DesignSystemTemplateId, type PageDesignState, type SiteStyleId } from './types';
-import { type SchemaVersionedJsonParseIssue } from './schemaVersionedJson';
+import { type DesignBlockId, type DesignResolutionPolicy, type DesignSystemTemplateId, type SiteStyleId } from './types';
 import { type ThemeV2CompilerOwnedFieldName, type ThemeV2RuntimeStyleFieldName } from './rawStyleFields';
 export { themeV2RuntimeStyleFieldNames, type ThemeV2RuntimeStyleFieldName, } from './rawStyleFields';
 export declare const themeV2DesignStateSchemaVersion: 1;
@@ -32,29 +31,6 @@ export type BlockRuntimeStyleAuthority<TBlockId extends string = DesignBlockId>
     fields: NonEmptyRuntimeStyleFieldNames;
     authority: StyleAuthority;
 }>;
-export type PersistedPageDesignStateV1<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<PageDesignState<TBlockId, TPurpose> & {
-    schemaVersion: typeof themeV2DesignStateSchemaVersion;
-    siteStyleId: SiteStyleId;
-    templateId: DesignSystemTemplateId;
-    templateVersion: number;
-    resolverVersion: number;
-    styleAuthorities: readonly BlockRuntimeStyleAuthority<TBlockId>[];
-}>;
-/**
- * Current persisted design state alias. When boundary overrides or full page
- * rhythm payloads land, add PersistedPageDesignStateV2 and widen this union.
- */
-export type PersistedPageDesignState<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = PersistedPageDesignStateV1<TBlockId, TPurpose>;
-export type DesignStateParseIssue = SchemaVersionedJsonParseIssue;
-export type DesignStateParseResult<TBlockId extends string = DesignBlockId, TPurpose extends string = string> = Readonly<{
-    kind: 'absent';
-}> | Readonly<{
-    kind: 'parsed';
-    state: PersistedPageDesignState<TBlockId, TPurpose>;
-}> | Readonly<{
-    kind: 'invalid';
-    issue: DesignStateParseIssue;
-}>;
 export type RuntimeStyleClassification = Readonly<{
     kind: 'clean-auto';
     fields: readonly [];
@@ -106,164 +82,6 @@ export type PageStyleAuthoritySummary<TBlockId extends string = DesignBlockId> =
     legacyRawBlockIds: readonly [];
     advancedDetachedBlockIds: readonly TBlockId[];
 }>;
-export declare const blockDesignPlanSchema: z.ZodObject<{
-    blockId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignBlockId, string>>;
-    blockKind: z.ZodString;
-    purpose: z.ZodString;
-    sectionSurface: z.ZodEnum<{
-        base: "base";
-        "muted-band": "muted-band";
-        "accent-band": "accent-band";
-        "brand-depth-band": "brand-depth-band";
-        "hero-image": "hero-image";
-    }>;
-    contentFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"plain">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"panel">;
-        treatment: z.ZodEnum<{
-            raised: "raised";
-            editorial: "editorial";
-            inset: "inset";
-        }>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"flush-panel">;
-        treatment: z.ZodEnum<{
-            "media-panel": "media-panel";
-        }>;
-        bleed: z.ZodEnum<{
-            end: "end";
-            both: "both";
-            start: "start";
-        }>;
-    }, z.core.$strict>], "kind">;
-    itemSurface: z.ZodEnum<{
-        flat: "flat";
-        default: "default";
-        none: "none";
-        raised: "raised";
-        editorial: "editorial";
-        "color-blocked": "color-blocked";
-        inset: "inset";
-        outlined: "outlined";
-    }>;
-    transitionAfter: z.ZodEnum<{
-        none: "none";
-        "soft-fade-short": "soft-fade-short";
-        "soft-fade-long": "soft-fade-long";
-        "soft-fade-expansive": "soft-fade-expansive";
-        "wave-edge": "wave-edge";
-        "wave-edge-balanced": "wave-edge-balanced";
-        "wave-edge-gentle": "wave-edge-gentle";
-        "wave-edge-bold": "wave-edge-bold";
-        "wave-edge-drift": "wave-edge-drift";
-        "angle-edge": "angle-edge";
-        "angle-edge-subtle": "angle-edge-subtle";
-        "angle-edge-steep": "angle-edge-steep";
-    }>;
-    emphasis: z.ZodEnum<{
-        medium: "medium";
-        high: "high";
-        low: "low";
-    }>;
-    sectionHeight: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        hero: "hero";
-        banner: "banner";
-        immersive: "immersive";
-    }>>;
-    heroLegibility: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        "scrim-gradient": "scrim-gradient";
-        "solid-panel": "solid-panel";
-    }>>;
-    heroComposition: z.ZodOptional<z.ZodEnum<{
-        center: "center";
-        "bottom-left": "bottom-left";
-    }>>;
-    heroTypographyScale: z.ZodOptional<z.ZodEnum<{
-        display: "display";
-        poster: "poster";
-        editorial: "editorial";
-        quiet: "quiet";
-    }>>;
-    imageSurfaceTreatment: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"none">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"brand-scrim">;
-        token: z.ZodEnum<{
-            accent: "accent";
-            primary: "primary";
-            secondary: "secondary";
-        }>;
-        intensity: z.ZodOptional<z.ZodEnum<{
-            soft: "soft";
-            strong: "strong";
-            balanced: "balanced";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"brand-wash">;
-        token: z.ZodEnum<{
-            accent: "accent";
-            primary: "primary";
-            secondary: "secondary";
-        }>;
-        intensity: z.ZodOptional<z.ZodEnum<{
-            soft: "soft";
-            strong: "strong";
-            balanced: "balanced";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"neutral-scrim">;
-        intensity: z.ZodOptional<z.ZodEnum<{
-            soft: "soft";
-            strong: "strong";
-            balanced: "balanced";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"neutral-wash">;
-        intensity: z.ZodOptional<z.ZodEnum<{
-            soft: "soft";
-            strong: "strong";
-            balanced: "balanced";
-        }>>;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"solid-panel">;
-        intensity: z.ZodOptional<z.ZodEnum<{
-            soft: "soft";
-            strong: "strong";
-            balanced: "balanced";
-        }>>;
-    }, z.core.$strict>], "kind">>;
-    imageSurfaceMotion: z.ZodOptional<z.ZodEnum<{
-        static: "static";
-        "fixed-frame": "fixed-frame";
-    }>>;
-    testimonialCardTreatment: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        "accent-quote": "accent-quote";
-    }>>;
-    tileTreatment: z.ZodOptional<z.ZodEnum<{
-        default: "default";
-        quiet: "quiet";
-        "brand-depth": "brand-depth";
-    }>>;
-    eventListTreatment: z.ZodOptional<z.ZodEnum<{
-        plain: "plain";
-        "lined-panel": "lined-panel";
-        "ruled-register": "ruled-register";
-        "editorial-register": "editorial-register";
-        "dense-index": "dense-index";
-    }>>;
-    eyebrowTreatment: z.ZodOptional<z.ZodEnum<{
-        accent: "accent";
-        pill: "pill";
-        plain: "plain";
-        "accent-pill": "accent-pill";
-        "pill-bounce": "pill-bounce";
-        "accent-pill-bounce": "accent-pill-bounce";
-    }>>;
-}, z.core.$strict>;
 export declare const styleAuthoritySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"theme-v2">;
     source: z.ZodEnum<{
@@ -320,213 +138,29 @@ export declare const blockRuntimeStyleAuthoritySchema: z.ZodObject<{
         reason: z.ZodLiteral<"detached-custom-runtime-fields">;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
-export declare const persistedPageDesignStateV1Schema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
-    templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;
-    templateVersion: z.ZodNumber;
-    resolverVersion: z.ZodNumber;
-    rhythmPresetId: z.ZodString;
-    blocks: z.ZodArray<z.ZodObject<{
-        blockId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignBlockId, string>>;
-        blockKind: z.ZodString;
-        purpose: z.ZodString;
-        sectionSurface: z.ZodEnum<{
-            base: "base";
-            "muted-band": "muted-band";
-            "accent-band": "accent-band";
-            "brand-depth-band": "brand-depth-band";
-            "hero-image": "hero-image";
-        }>;
-        contentFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"plain">;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"panel">;
-            treatment: z.ZodEnum<{
-                raised: "raised";
-                editorial: "editorial";
-                inset: "inset";
-            }>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"flush-panel">;
-            treatment: z.ZodEnum<{
-                "media-panel": "media-panel";
-            }>;
-            bleed: z.ZodEnum<{
-                end: "end";
-                both: "both";
-                start: "start";
-            }>;
-        }, z.core.$strict>], "kind">;
-        itemSurface: z.ZodEnum<{
-            flat: "flat";
-            default: "default";
-            none: "none";
-            raised: "raised";
-            editorial: "editorial";
-            "color-blocked": "color-blocked";
-            inset: "inset";
-            outlined: "outlined";
-        }>;
-        transitionAfter: z.ZodEnum<{
-            none: "none";
-            "soft-fade-short": "soft-fade-short";
-            "soft-fade-long": "soft-fade-long";
-            "soft-fade-expansive": "soft-fade-expansive";
-            "wave-edge": "wave-edge";
-            "wave-edge-balanced": "wave-edge-balanced";
-            "wave-edge-gentle": "wave-edge-gentle";
-            "wave-edge-bold": "wave-edge-bold";
-            "wave-edge-drift": "wave-edge-drift";
-            "angle-edge": "angle-edge";
-            "angle-edge-subtle": "angle-edge-subtle";
-            "angle-edge-steep": "angle-edge-steep";
-        }>;
-        emphasis: z.ZodEnum<{
-            medium: "medium";
-            high: "high";
-            low: "low";
-        }>;
-        sectionHeight: z.ZodOptional<z.ZodEnum<{
-            default: "default";
-            hero: "hero";
-            banner: "banner";
-            immersive: "immersive";
-        }>>;
-        heroLegibility: z.ZodOptional<z.ZodEnum<{
-            none: "none";
-            "scrim-gradient": "scrim-gradient";
-            "solid-panel": "solid-panel";
-        }>>;
-        heroComposition: z.ZodOptional<z.ZodEnum<{
-            center: "center";
-            "bottom-left": "bottom-left";
-        }>>;
-        heroTypographyScale: z.ZodOptional<z.ZodEnum<{
-            display: "display";
-            poster: "poster";
-            editorial: "editorial";
-            quiet: "quiet";
-        }>>;
-        imageSurfaceTreatment: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"none">;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"brand-scrim">;
-            token: z.ZodEnum<{
-                accent: "accent";
-                primary: "primary";
-                secondary: "secondary";
-            }>;
-            intensity: z.ZodOptional<z.ZodEnum<{
-                soft: "soft";
-                strong: "strong";
-                balanced: "balanced";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"brand-wash">;
-            token: z.ZodEnum<{
-                accent: "accent";
-                primary: "primary";
-                secondary: "secondary";
-            }>;
-            intensity: z.ZodOptional<z.ZodEnum<{
-                soft: "soft";
-                strong: "strong";
-                balanced: "balanced";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"neutral-scrim">;
-            intensity: z.ZodOptional<z.ZodEnum<{
-                soft: "soft";
-                strong: "strong";
-                balanced: "balanced";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"neutral-wash">;
-            intensity: z.ZodOptional<z.ZodEnum<{
-                soft: "soft";
-                strong: "strong";
-                balanced: "balanced";
-            }>>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"solid-panel">;
-            intensity: z.ZodOptional<z.ZodEnum<{
-                soft: "soft";
-                strong: "strong";
-                balanced: "balanced";
-            }>>;
-        }, z.core.$strict>], "kind">>;
-        imageSurfaceMotion: z.ZodOptional<z.ZodEnum<{
-            static: "static";
-            "fixed-frame": "fixed-frame";
-        }>>;
-        testimonialCardTreatment: z.ZodOptional<z.ZodEnum<{
-            default: "default";
-            "accent-quote": "accent-quote";
-        }>>;
-        tileTreatment: z.ZodOptional<z.ZodEnum<{
-            default: "default";
-            quiet: "quiet";
-            "brand-depth": "brand-depth";
-        }>>;
-        eventListTreatment: z.ZodOptional<z.ZodEnum<{
-            plain: "plain";
-            "lined-panel": "lined-panel";
-            "ruled-register": "ruled-register";
-            "editorial-register": "editorial-register";
-            "dense-index": "dense-index";
-        }>>;
-        eyebrowTreatment: z.ZodOptional<z.ZodEnum<{
-            accent: "accent";
-            pill: "pill";
-            plain: "plain";
-            "accent-pill": "accent-pill";
-            "pill-bounce": "pill-bounce";
-            "accent-pill-bounce": "accent-pill-bounce";
-        }>>;
-    }, z.core.$strict>>;
-    styleAuthorities: z.ZodArray<z.ZodObject<{
-        unit: z.ZodLiteral<"block-runtime-fields">;
-        blockId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignBlockId, string>>;
-        fields: z.ZodPipe<z.ZodArray<z.ZodEnum<{
-            _frameStyles: "_frameStyles";
-            _sectionStyles: "_sectionStyles";
-            _containerStyles: "_containerStyles";
-            _cardStyles: "_cardStyles";
-            _transitionStyles: "_transitionStyles";
-            styleGroup: "styleGroup";
-        }>>, z.ZodTransform<NonEmptyRuntimeStyleFieldNames, ("_frameStyles" | "_sectionStyles" | "_containerStyles" | "_cardStyles" | "_transitionStyles" | "styleGroup")[]>>;
-        authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"theme-v2">;
-            source: z.ZodEnum<{
-                user: "user";
-                admin: "admin";
-                sdk: "sdk";
-                generated: "generated";
-            }>;
-            siteStyleId: z.ZodPipe<z.ZodString, z.ZodTransform<SiteStyleId, string>>;
-            templateId: z.ZodPipe<z.ZodString, z.ZodTransform<DesignSystemTemplateId, string>>;
-            templateVersion: z.ZodNumber;
-            resolverVersion: z.ZodNumber;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"legacy-raw">;
-            reason: z.ZodEnum<{
-                "pre-theme-v2": "pre-theme-v2";
-                "manual-runtime-fields": "manual-runtime-fields";
-            }>;
-        }, z.core.$strict>, z.ZodObject<{
-            kind: z.ZodLiteral<"advanced-detached">;
-            reason: z.ZodLiteral<"detached-custom-runtime-fields">;
-        }, z.core.$strict>], "kind">;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export declare function parsePersistedPageDesignState(value: unknown): DesignStateParseResult;
 export declare function collectRuntimeStyleFieldNames(content: Readonly<Record<string, unknown>>): readonly ThemeV2RuntimeStyleFieldName[];
 export declare function classifyRuntimeStyleFields(input: Readonly<{
     content: Readonly<Record<string, unknown>>;
     authority?: StyleAuthority;
 }>): RuntimeStyleClassification;
 export declare function canWriteThemeV2RuntimeFields(authority: StyleAuthority | undefined): authority is ThemeV2StyleAuthority;
+/**
+ * Replace every compiler-owned field on a block's content with a fresh compiled
+ * set — the one primitive both writers of compiled output share.
+ *
+ * Replacement rather than merge is the whole point: a field the new
+ * compilation does not produce must *go*, or a recompile onto a Look that asks
+ * for no card leaves the old `_cardStyles` sitting there claiming a surface
+ * nobody asked for. Every writer that discovers compiler ownership for itself
+ * eventually forgets one of these names, so nobody does.
+ *
+ * Pure, and deliberately free of authority checks — those belong to the
+ * persistence wrapper, not to the shape of the content.
+ */
+export declare function withCompiledRuntimeStyleFields<TContent extends Record<string, unknown>, TFields extends ThemeV2RuntimeStyleFields>(input: Readonly<{
+    content: TContent;
+    fields: TFields;
+}>): Omit<TContent, ThemeV2CompilerOwnedFieldName> & TFields;
 /**
  * Persisted Theme V2 output is compile-at-write: once a block has Theme V2
  * authority, compiler-owned runtime fields are replaced in the same content
@@ -538,4 +172,6 @@ export declare function replaceCompiledRuntimeStyleFields<TContent extends Recor
     fields: TFields;
     authority?: StyleAuthority;
 }>): RuntimeStyleWriteResultForFields<TContent, TFields>;
-export declare function summarizePageStyleAuthorities<TBlockId extends string>(state: Pick<PersistedPageDesignState<TBlockId>, 'styleAuthorities'>): PageStyleAuthoritySummary<TBlockId>;
+export declare function summarizePageStyleAuthorities<TBlockId extends string>(state: Readonly<{
+    styleAuthorities: readonly BlockRuntimeStyleAuthority<TBlockId>[];
+}>): PageStyleAuthoritySummary<TBlockId>;

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

@@ -76,22 +76,18 @@ export declare const generatedBlockDesignIntentSchema: z.ZodObject<{
             }>;
         }, z.core.$strict>], "kind">;
     }, z.core.$strict>], "kind">;
-    itemSurface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    cardRole: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodLiteral<"generated">;
         kind: z.ZodLiteral<"auto">;
     }, z.core.$strict>, z.ZodObject<{
         source: z.ZodLiteral<"generated">;
         kind: z.ZodLiteral<"explicit">;
-        value: z.ZodEnum<{
-            flat: "flat";
+        value: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+            open: "open";
             default: "default";
             none: "none";
-            raised: "raised";
-            editorial: "editorial";
-            "color-blocked": "color-blocked";
-            inset: "inset";
-            outlined: "outlined";
-        }>;
+            alternative: "alternative";
+        }>>;
     }, z.core.$strict>], "kind">;
     transitionAfter: z.ZodDiscriminatedUnion<[z.ZodObject<{
         source: z.ZodLiteral<"generated">;
@@ -231,22 +227,18 @@ export declare const generatedPageDesignIntentSchema: z.ZodObject<{
                     }>;
                 }, z.core.$strict>], "kind">;
             }, z.core.$strict>], "kind">;
-            itemSurface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            cardRole: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 source: z.ZodLiteral<"generated">;
                 kind: z.ZodLiteral<"auto">;
             }, z.core.$strict>, z.ZodObject<{
                 source: z.ZodLiteral<"generated">;
                 kind: z.ZodLiteral<"explicit">;
-                value: z.ZodEnum<{
-                    flat: "flat";
+                value: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
+                    open: "open";
                     default: "default";
                     none: "none";
-                    raised: "raised";
-                    editorial: "editorial";
-                    "color-blocked": "color-blocked";
-                    inset: "inset";
-                    outlined: "outlined";
-                }>;
+                    alternative: "alternative";
+                }>>;
             }, z.core.$strict>], "kind">;
             transitionAfter: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 source: z.ZodLiteral<"generated">;

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

@@ -1,6 +1,6 @@
 import type { ThemeHeader } from '../schema';
 import type { HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
-import type { HeaderOpeningForeground } from './headerOpeningForeground';
+import type { ResolvedSurfaceForeground } from '../surfaces';
 import { type BrandDisplayMode, type LogoAccommodationOption, type LogoFacts, type LogoSizePolicy } from './logoBranding';
 import { type Brand } from './types';
 export declare const headerLayoutIdValues: readonly ["classic", "centered", "floating"];
@@ -97,11 +97,9 @@ export type HeaderOpeningSectionContext = Readonly<{
     canAdjust: true;
 }> | Readonly<{
     kind: 'color-section';
-    contrast: 'light' | 'dark' | 'unknown';
     canAdjust: boolean;
 }> | Readonly<{
     kind: 'gradient-section';
-    contrast: 'light' | 'dark' | 'unknown';
     canAdjust: boolean;
 }> | Readonly<{
     kind: 'dynamic-media';
@@ -128,7 +126,7 @@ export type HeaderLogoContext = HeaderLogoShapeContext | HeaderLogoFactsContext;
 export declare const defaultHeaderLogoContext: HeaderLogoContext;
 export type HeaderSelectionContext = Readonly<{
     openingSection: HeaderOpeningSectionContext;
-    openingForeground: HeaderOpeningForeground;
+    openingForeground: ResolvedSurfaceForeground;
     logo: HeaderLogoContext;
     navigation: Readonly<{
         itemCount: number;

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

@@ -1,15 +1,8 @@
 import type { Theme } from '../schema';
-import { type ThemeColorToken } from '../tokens';
+import type { ResolvedSurfaceForeground } from '../surfaces';
 import type { HeaderStyleDefinition } from './headerLayoutTypes';
-export type HeaderOpeningForeground = Readonly<{
-    kind: 'known';
-    token: ThemeColorToken;
-    evidence: 'declared-opening-surface' | 'theme-default';
-}> | Readonly<{
-    kind: 'unknown';
-}>;
 export type HeaderOpeningForegroundContext = Readonly<{
-    openingForeground: HeaderOpeningForeground;
+    openingForeground: ResolvedSurfaceForeground;
 }>;
 export type HeaderStyleAvailability = Readonly<{
     kind: 'available';

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

@@ -1,6 +1,5 @@
 import type { BlockDesignPlan, DesignBlockId, ResolvedBlockDesignPlan } from './types';
 import type { HeaderLayoutStyleSelection, HeaderOpeningSectionContext } from './headerLayoutStyles';
-import type { HeaderOpeningForeground } from './headerOpeningForeground';
 export type HeaderOpeningSectionRepair = 'promote-opening-hero-surface' | 'add-opening-contrast-overlay' | 'add-opening-top-spacing';
 export type HeaderOpeningSectionPlan<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
     plan: readonly BlockDesignPlan<TBlockId>[];
@@ -16,7 +15,6 @@ export declare function planGeneratedHeaderOpeningSection<TBlockId extends Desig
     recommendedHeaderSelections: readonly HeaderLayoutStyleSelection[];
 }>): HeaderOpeningSectionPlan<TBlockId>;
 export declare function deriveHeaderOpeningSectionContextFromContent(input: HeaderOpeningContentSnapshot): HeaderOpeningSectionContext;
-export declare function deriveHeaderOpeningForegroundFromContent(input: HeaderOpeningContentSnapshot): HeaderOpeningForeground;
 export declare function deriveHeaderOpeningSectionContext(input: Readonly<{
     openingBlock: ResolvedBlockDesignPlan | null;
     openingContent?: Record<string, unknown> | null;