@riverbankcms/sdk 0.103.0 → 0.104.0

package/dist/_dts/theme-core/src/palette/resolveSelection.d.ts

@@ -0,0 +1,50 @@
+import type { PaletteColors, PaletteMode } from './colors';
+import { type CuratedPalette, type CuratedPaletteId } from './curated';
+import type { PaletteSelection, SitePalette, SitePaletteId } from './selection';
+declare const resolvedPaletteSelectionBrand: unique symbol;
+export type ResolvedCuratedPaletteSelection = Readonly<{
+    kind: 'curated';
+    selection: Extract<PaletteSelection, {
+        kind: 'curated';
+    }>;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    [resolvedPaletteSelectionBrand]: true;
+}>;
+export type ResolvedSitePaletteSelection = Readonly<{
+    kind: 'site';
+    selection: Extract<PaletteSelection, {
+        kind: 'site';
+    }>;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    version: SitePalette['version'];
+    [resolvedPaletteSelectionBrand]: true;
+}>;
+export type ResolvedPaletteSelection = ResolvedCuratedPaletteSelection | ResolvedSitePaletteSelection;
+export type PaletteSelectionResolutionError = Readonly<{
+    kind: 'curated-palette-not-found';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'site-palette-not-found';
+    paletteId: SitePaletteId;
+}>;
+export type PaletteSelectionResolution = Readonly<{
+    ok: true;
+    resolved: ResolvedPaletteSelection;
+}> | Readonly<{
+    ok: false;
+    error: PaletteSelectionResolutionError;
+}>;
+/** Core-owned constructors keep the resolved marker out of application code. */
+export declare function resolvedCuratedPaletteSelection(palette: CuratedPalette): ResolvedCuratedPaletteSelection;
+export declare function resolvedSitePaletteSelection(palette: SitePalette): ResolvedSitePaletteSelection;
+/** Resolves a persisted selection against the records that actually own it. */
+export declare function resolvePaletteSelection(input: Readonly<{
+    selection: PaletteSelection;
+    curatedPalettes: readonly CuratedPalette[];
+    sitePalettes: readonly SitePalette[];
+}>): PaletteSelectionResolution;
+/** Resolves catalog authority without asking callers to manufacture a brand. */
+export declare function resolveCuratedPaletteSelection(paletteId: CuratedPaletteId): PaletteSelectionResolution;
+export {};

package/dist/_dts/theme-core/src/palette/selection.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { type CuratedPaletteId } from './curated/types';
+import { type PaletteColors, type PaletteMode } from './colors';
+export type SitePaletteId = string & {
+    readonly __brand: 'SitePaletteId';
+};
+export type SitePaletteVersion = number & {
+    readonly __brand: 'SitePaletteVersion';
+};
+export declare const sitePaletteIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SitePaletteId, string>>;
+export declare const sitePaletteVersionSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<SitePaletteVersion, number>>;
+export declare function parseSitePaletteId(value: unknown): SitePaletteId | null;
+export declare function parseSitePaletteVersion(value: unknown): SitePaletteVersion | null;
+export type PaletteSelection = Readonly<{
+    kind: 'curated';
+    paletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'site';
+    paletteId: SitePaletteId;
+}>;
+export declare const paletteSelectionSchema: z.ZodType<PaletteSelection>;
+export type SitePaletteOrigin = Readonly<{
+    kind: 'onboarding';
+    sourceKey: string | null;
+}> | Readonly<{
+    kind: 'curated-fork';
+    sourcePaletteId: CuratedPaletteId;
+}> | Readonly<{
+    kind: 'manual';
+}> | Readonly<{
+    kind: 'legacy-customized';
+    sourceKey: string | null;
+}>;
+export declare const sitePaletteOriginSchema: z.ZodType<SitePaletteOrigin>;
+export type EditorSitePaletteOrigin = Extract<SitePaletteOrigin, {
+    kind: 'curated-fork';
+}> | Extract<SitePaletteOrigin, {
+    kind: 'manual';
+}>;
+export type SitePalette = Readonly<{
+    id: SitePaletteId;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: SitePaletteOrigin;
+    version: SitePaletteVersion;
+}>;
+export declare const sitePaletteSchema: z.ZodType<SitePalette>;
+export type PaletteCommand = Readonly<{
+    kind: 'preserve';
+}> | Readonly<{
+    kind: 'select';
+    selection: PaletteSelection;
+}> | Readonly<{
+    kind: 'create-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: EditorSitePaletteOrigin;
+}> | Readonly<{
+    kind: 'update-site';
+    paletteId: SitePaletteId;
+    expectedVersion: SitePaletteVersion;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}>;
+/** Server-only command shape for provisioning and legacy write-through. */
+export type TrustedPaletteCommand = PaletteCommand | Readonly<{
+    kind: 'create-site';
+    colors: PaletteColors;
+    mode: PaletteMode;
+    origin: SitePaletteOrigin;
+}>;
+export declare const paletteCommandSchema: z.ZodType<PaletteCommand>;

package/dist/_dts/theme-core/src/palette/sitePalettePersistence.d.ts

@@ -0,0 +1,34 @@
+import { type SitePalette } from './selection';
+/** Structural persistence shape shared by every site-palette reader. */
+export type SitePalettePersistenceRow = Readonly<{
+    id: string;
+    colors: unknown;
+    mode: string;
+    originKind: string;
+    originReference: string | null;
+    version: number;
+}>;
+export type SitePaletteParseError = Readonly<{
+    kind: 'invalid-site-palette-id';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-site-palette-colors';
+}> | Readonly<{
+    kind: 'invalid-site-palette-mode';
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-site-palette-origin';
+    originKind: string;
+    originReference: string | null;
+}> | Readonly<{
+    kind: 'invalid-site-palette-version';
+    value: number;
+}>;
+export type SitePaletteParseResult = Readonly<{
+    ok: true;
+    palette: SitePalette;
+}> | Readonly<{
+    ok: false;
+    error: SitePaletteParseError;
+}>;
+export declare function parseSitePalettePersistenceRow(row: SitePalettePersistenceRow): SitePaletteParseResult;

package/dist/_dts/theme-core/src/palette/themePaletteCompatibility.d.ts

@@ -0,0 +1,58 @@
+import { type PaletteTokenName } from '../tokens/themeColorTokens';
+import { type PaletteColors, type PaletteMode } from './colors';
+import type { PaletteOverrides } from './curated';
+/**
+ * The persisted Theme palette boundary. It deliberately stays narrower than
+ * the full Theme schema so consumers do not need to depend on another package
+ * just to interpret old sparse palette entries.
+ */
+export type ThemePaletteCompatibilityInput = Readonly<{
+    palette?: Readonly<{
+        colors: readonly Readonly<{
+            name: string;
+            hex: string;
+        }>[];
+        meta?: Readonly<{
+            mode?: unknown;
+        }> | null;
+    }> | null;
+}>;
+export type ThemePaletteCompatibilityError = Readonly<{
+    kind: 'missing-palette';
+}> | Readonly<{
+    kind: 'invalid-mode';
+}> | Readonly<{
+    kind: 'unknown-role';
+    role: string;
+}> | Readonly<{
+    kind: 'duplicate-role';
+    role: PaletteTokenName;
+}> | Readonly<{
+    kind: 'invalid-color';
+    role: PaletteTokenName;
+    value: string;
+}> | Readonly<{
+    kind: 'invalid-complete-palette';
+}>;
+export type CompatibleThemePalette = Readonly<{
+    kind: 'complete';
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'partial';
+    overrides: PaletteOverrides;
+    mode: PaletteMode;
+}>;
+export type ParseCompatibleThemePaletteResult = Readonly<{
+    ok: true;
+    palette: CompatibleThemePalette;
+}> | Readonly<{
+    ok: false;
+    error: ThemePaletteCompatibilityError;
+}>;
+/**
+ * Parses both current complete Theme palettes and historical sparse palettes.
+ * Sparse entries remain sparse so callers can overlay them onto their own
+ * authoritative base without silently changing the persisted Theme shape.
+ */
+export declare function parseCompatibleThemePalette(theme: ThemePaletteCompatibilityInput): ParseCompatibleThemePaletteResult;

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

@@ -2034,6 +2034,7 @@ export declare const headerSchema: z.ZodObject<{
         base: "base";
         sm: "sm";
         lg: "lg";
+        xl: "xl";
         xs: "xs";
     }>>;
     container: z.ZodOptional<z.ZodObject<{
@@ -2152,6 +2153,7 @@ export declare const headerSchema: z.ZodObject<{
             base: "base";
             sm: "sm";
             lg: "lg";
+            xl: "xl";
             xs: "xs";
         }>>;
         letterSpacing: z.ZodOptional<z.ZodEnum<{
@@ -2396,6 +2398,7 @@ export declare const footerSchema: z.ZodObject<{
             base: "base";
             sm: "sm";
             lg: "lg";
+            xl: "xl";
             xs: "xs";
         }>>;
         letterSpacing: z.ZodOptional<z.ZodEnum<{
@@ -3548,6 +3551,7 @@ export declare const themeSchema: z.ZodObject<{
             base: "base";
             sm: "sm";
             lg: "lg";
+            xl: "xl";
             xs: "xs";
         }>>;
         container: z.ZodOptional<z.ZodObject<{
@@ -3666,6 +3670,7 @@ export declare const themeSchema: z.ZodObject<{
                 base: "base";
                 sm: "sm";
                 lg: "lg";
+                xl: "xl";
                 xs: "xs";
             }>>;
             letterSpacing: z.ZodOptional<z.ZodEnum<{
@@ -3895,6 +3900,7 @@ export declare const themeSchema: z.ZodObject<{
                 base: "base";
                 sm: "sm";
                 lg: "lg";
+                xl: "xl";
                 xs: "xs";
             }>>;
             letterSpacing: z.ZodOptional<z.ZodEnum<{
@@ -5868,6 +5874,7 @@ export declare const themesTurnSchema: z.ZodObject<{
                 base: "base";
                 sm: "sm";
                 lg: "lg";
+                xl: "xl";
                 xs: "xs";
             }>>;
             container: z.ZodOptional<z.ZodObject<{
@@ -5986,6 +5993,7 @@ export declare const themesTurnSchema: z.ZodObject<{
                     base: "base";
                     sm: "sm";
                     lg: "lg";
+                    xl: "xl";
                     xs: "xs";
                 }>>;
                 letterSpacing: z.ZodOptional<z.ZodEnum<{
@@ -6215,6 +6223,7 @@ export declare const themesTurnSchema: z.ZodObject<{
                     base: "base";
                     sm: "sm";
                     lg: "lg";
+                    xl: "xl";
                     xs: "xs";
                 }>>;
                 letterSpacing: z.ZodOptional<z.ZodEnum<{

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

@@ -1,5 +1,5 @@
 import { type ButtonPersonalityId, type KnownButtonPersonalityId } from '../buttons/personalities';
-import { type KnownPaletteVariantId, type PaletteVariantId } from '../palette/variants';
+import { type KnownCuratedPaletteId, type CuratedPaletteId } from '../palette/curated';
 import type { Theme } from '../schema';
 import { type HeaderLayoutId, type HeaderLayoutIdValue, type HeaderLookId, type HeaderStyleId } from './headerLooks';
 import { type FooterLookId } from './footerLooks';
@@ -23,7 +23,7 @@ type CuratedSiteStyleCardOverrides = NonNullable<Theme['cards']>;
 type CuratedSiteStyleTestimonialQuoteOverrides = NonNullable<Theme['testimonialQuote']>;
 /**
  * Site-style-specific Theme overrides are applied after token recipes,
- * button personality, and palette variant selection have compiled the base
+ * button personality, and curated palette selection have compiled the base
  * Theme. Values here intentionally win; palette and button selections remain
  * independent Style configurator choices.
  */
@@ -50,7 +50,7 @@ export type CuratedSiteStyleThemeOverrides = Readonly<{
     testimonialQuote?: CuratedSiteStyleTestimonialQuoteOverrides;
 }>;
 export type ButtonPersonalityChoice = CuratedChoice<KnownButtonPersonalityId>;
-export type PaletteVariantChoice = CuratedChoice<KnownPaletteVariantId>;
+export type CuratedPaletteRecommendation = CuratedChoice<KnownCuratedPaletteId>;
 export type HeaderLayoutChoice = CuratedChoice<HeaderLayoutId>;
 export type HeaderStyleChoice = CuratedChoice<HeaderStyleId>;
 export type HeaderLayoutStyleChoice = Readonly<{
@@ -113,12 +113,12 @@ export type CuratedSiteStyle = Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>;
 export declare function defaultButtonPersonalityForSiteStyle(siteStyle: CuratedSiteStyle): ButtonPersonalityId;
-export declare function defaultPaletteVariantForSiteStyle(siteStyle: CuratedSiteStyle): PaletteVariantId;
+export declare function defaultPaletteForSiteStyle(siteStyle: CuratedSiteStyle): CuratedPaletteId;
 export declare function defaultTypographyPresetForSiteStyle(siteStyle: CuratedSiteStyle): TypographyPresetId;
 /**
  * V1 generated site styles are curated product presets, not AI-authored design
@@ -157,7 +157,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -192,7 +192,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -227,7 +227,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -262,7 +262,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -297,7 +297,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -332,7 +332,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -367,7 +367,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -402,7 +402,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -437,7 +437,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -472,7 +472,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -507,7 +507,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -542,7 +542,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -577,7 +577,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -612,7 +612,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -647,7 +647,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>, Readonly<{
@@ -682,7 +682,7 @@ export declare const curatedSiteStyles: readonly [Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>];
@@ -718,7 +718,7 @@ export declare const curatedSiteStylesById: Map<SiteStyleId, Readonly<{
     /** Authored picker choices. First item is the default/fallback. */
     buttonPersonalityChoices: NonEmptyReadonlyArray<ButtonPersonalityChoice>;
     /** Authored picker choices. First item is the default/fallback. */
-    paletteVariantChoices: NonEmptyReadonlyArray<PaletteVariantChoice>;
+    paletteRecommendations: NonEmptyReadonlyArray<CuratedPaletteRecommendation>;
     typographyPresetChoices: NonEmptyReadonlyArray<TypographyPresetChoice>;
     defaultTypographyPresetId: KnownTypographyPresetId;
 }>>;

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

@@ -35,4 +35,5 @@ export * from './sourceCatalogs';
 export * from './styleTags';
 export * from './tokenRecipes';
 export * from './typographyPresets';
+export * from './themeParity';
 export * from './types';

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

@@ -1,7 +1,8 @@
 import type { PageDesignEditorReadModel } from './pageDesignEditorModel';
 import { type Theme } from '../schema';
 import { type ButtonPersonalityId } from '../buttons/personalities';
-import { type PaletteOverrides, type PaletteVariantId } from '../palette/variants';
+import { type PaletteOverrides, type CuratedPaletteId } from '../palette/curated';
+import type { PaletteSelection, ResolvedPaletteSelection } from '../palette';
 import { type CuratedSiteStyle } from './curatedSiteStyles';
 import { type CompiledTypographySelection, type KnownTypographyPresetId, type TypographyPresetId, type TypographyPresetResolutionWarning, type TypographySelection } from './typographyPresets';
 import { type FooterLookId, type FooterSelectionContext, type FooterSelectionResult } from './footerLooks';
@@ -25,7 +26,7 @@ export { repairDesignIssue, resolveBlockDesignPlan } from './resolver';
 export { cycleableOptionsFromResolved, deriveDesignCustomizationScope, recommendedDesignOption, type CycleableDesignOption, type CycleableOptions, type DesignCustomizationAuthority, type DesignCustomizationScope, type DesignCustomizationSurface, type DesignCustomizationUnsupportedReason, type DesignOptionIssue, type ResolvedDesignOption, } from './previewCustomization';
 export { compileBlockRuntimeFields, compileBoundaryRuntime, compilePageRuntimeFields, compileTokenRecipes, compileTransitionRuntime, compiledRuntimeStyleFieldNames, defaultComponentRuntimeRules, defaultDesignRuntimeRules, surfaceResolutionContextFromPalette, surfaceResolutionContextFromTheme, stripCompiledRuntimeStyleFields, type CompiledBlockRuntime, type CompiledBlockRuntimeFields, type CompiledBoundaryRuntime, type CompiledPageRuntime, type CompileBlockRuntimeInput, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing, type SurfaceResolutionContext, } from './runtimeCompiler';
 export { defaultCuratedChoice, requireEntriesForCuratedChoices, resolveCuratedChoice, type CuratedChoice, type CuratedChoiceResolution, } from './curatedChoices';
-export { curatedSiteStyles, defaultButtonPersonalityForSiteStyle, defaultPaletteVariantForSiteStyle, defaultTypographyPresetForSiteStyle, getCuratedSiteStyle, type CuratedSiteStyle, } from './curatedSiteStyles';
+export { curatedSiteStyles, defaultButtonPersonalityForSiteStyle, defaultPaletteForSiteStyle, defaultTypographyPresetForSiteStyle, getCuratedSiteStyle, type CuratedSiteStyle, } from './curatedSiteStyles';
 export { asTypographyPresetId, compileTypographySelection, evaluateTypographyFontSlot, findTypographyPreset, parsePersistedTypographyPresetId, typographyPresetIdValues, typographyPresets, type CompiledTypographySelection, type GoogleFontCategory, type KnownTypographyPresetId, type KnownTypographyPresetIdValue, type TypographyFontCapability, type TypographyFontSlot, type TypographyFontSlotFit, type TypographyFontSlotPolicy, type TypographyPreset, type TypographyPresetId, type TypographyPresetResolutionWarning, type TypographySelection, } from './typographyPresets';
 export { asDesignBlockId, asSiteStyleId, makeBoundaryId, type AppearancePresetId, type BoundaryOptionId, type DesignBlockId, type DesignBoundaryId, type LayoutVariantKey, type NonEmptyReadonlyArray, type PageFlowPresetId, type ResolvedPageDesignPlan, type SiteStyleId, } from './types';
 export declare const previewCustomizePurpose: "preview-customize";
@@ -43,13 +44,11 @@ export type SelectionFallbackWarning = Readonly<{
 }> | Readonly<{
     kind: 'rejected-palette';
     requested: string;
-    fellBackTo: PaletteVariantId;
+    fellBackTo: CuratedPaletteId;
 }> | TypographyPresetResolutionWarning;
-export type SiteThemeSelectionsInput = Readonly<{
+type SiteThemeSelectionsCommonInput = Readonly<{
     siteStyle: CuratedSiteStyle;
     buttonPersonalityId: ButtonPersonalityId | null;
-    paletteVariantId: PaletteVariantId | null;
-    paletteOverrides: PaletteOverrides | null;
     typographyPresetId?: TypographyPresetId | null;
     typographyBodyFontOverride?: string | null;
     typographyHeadingFontOverride?: string | null;
@@ -61,6 +60,17 @@ export type SiteThemeSelectionsInput = Readonly<{
     headerSelectionContext?: Partial<HeaderSelectionContext>;
     footerSelectionContext?: Partial<FooterSelectionContext>;
 }>;
+export type LegacySiteThemeSelectionsInput = SiteThemeSelectionsCommonInput & Readonly<{
+    resolvedPalette?: undefined;
+    paletteVariantId: CuratedPaletteId | null;
+    paletteOverrides: PaletteOverrides | null;
+}>;
+export type ExplicitPaletteSiteThemeSelectionsInput = SiteThemeSelectionsCommonInput & Readonly<{
+    resolvedPalette: ResolvedPaletteSelection;
+    paletteVariantId?: never;
+    paletteOverrides?: never;
+}>;
+export type SiteThemeSelectionsInput = LegacySiteThemeSelectionsInput | ExplicitPaletteSiteThemeSelectionsInput;
 export type SiteThemeSelectionsResult = Readonly<{
     theme: CuratedSiteStyleTheme;
     requestedSelections: Readonly<{
@@ -71,7 +81,11 @@ export type SiteThemeSelectionsResult = Readonly<{
     }>;
     resolvedSelections: Readonly<{
         buttonPersonalityId: ButtonPersonalityId;
-        paletteVariantId: PaletteVariantId;
+        paletteVariantId: CuratedPaletteId;
+        paletteSelection: Readonly<{
+            kind: 'curated';
+            paletteId: CuratedPaletteId;
+        }>;
         typographySelection: CompiledTypographySelection['resolvedSelection'];
         typographyPresetId: KnownTypographyPresetId | null;
         typographyBodyFontOverride: string | null;
@@ -85,10 +99,16 @@ export type SiteThemeSelectionsResult = Readonly<{
     footerSelection: FooterSelectionResult;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
 }>;
+export type ExplicitPaletteSiteThemeSelectionsResult = Omit<SiteThemeSelectionsResult, 'resolvedSelections'> & Readonly<{
+    resolvedSelections: Omit<SiteThemeSelectionsResult['resolvedSelections'], 'paletteVariantId' | 'paletteSelection'> & Readonly<{
+        paletteVariantId: CuratedPaletteId | null;
+        paletteSelection: PaletteSelection;
+    }>;
+}>;
 /**
  * High-level, site-style-aware compiler. Resolves the user's personality and
  * palette selections into theme tokens. Button personality still resolves
- * against the site style's authored choice list; palette variants are brand
+ * against the site style's authored choice list; curated palettes are brand
  * choices, so any known palette is preserved across site styles and the style's
  * first palette choice is only used when the request is absent or unknown.
  *
@@ -96,7 +116,9 @@ export type SiteThemeSelectionsResult = Readonly<{
  * any fallback warnings the UI can surface as "we changed your selection"
  * notices.
  */
-export declare function compileSiteThemeFromSelections(input: SiteThemeSelectionsInput): SiteThemeSelectionsResult;
+export declare function compileSiteThemeFromSelections(input: LegacySiteThemeSelectionsInput): SiteThemeSelectionsResult;
+export declare function compileSiteThemeFromSelections(input: ExplicitPaletteSiteThemeSelectionsInput): ExplicitPaletteSiteThemeSelectionsResult;
+export declare function compileSiteThemeFromSelections(input: SiteThemeSelectionsInput): SiteThemeSelectionsResult | ExplicitPaletteSiteThemeSelectionsResult;
 export declare function siteStyleIdFromTheme(theme: Pick<Theme, 'siteStyleId'> | null | undefined): SiteStyleId | null;
 export type EditorModelRuntimeLookOverride<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
     kind: 'pinned';

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

@@ -1,7 +1,8 @@
 import { type CardStylesOverride, type ContainerStylesOverride, type SectionStylesOverride, type Theme } from '../schema';
 import { type ExpandedPalette } from '../palette/expandPalette';
 import { type ButtonPersonalityId } from '../buttons/personalities';
-import { type PaletteOverrides, type PaletteVariantId } from '../palette/variants';
+import { type PaletteOverrides, type CuratedPaletteId } from '../palette/curated';
+import type { ResolvedPaletteSelection } from '../palette/resolveSelection';
 import { type RuntimeStyleWriteResultForFields, type StyleAuthority } from './designState';
 import { type ContentFrameIntent, type EyebrowTreatment, type FlushFrameTreatment, type DesignBoundaryId, type PanelFrameTreatment, type ResolvedBlockDesignPlan, type ResolvedPageDesignPlan, type SiteStyleItemSurfaceIntent, type SiteStyleSectionTransitionIntent, type SiteStyleSurfaceIntent, type ThemeTokenRecipes } from './types';
 import { type SectionBoundaryRuntimeMetrics } from './sectionTransitions';
@@ -311,30 +312,35 @@ export declare function compilePageRuntimeFields<TBlockId extends string, TPurpo
     sectionSpacing?: SemanticSpacing;
     terminalSectionAdjacency?: TerminalSectionAdjacency;
 }>): CompiledPageRuntime<TBlockId>;
-export type CompileTokenRecipesOptions = Readonly<{
-    /** Resolved button personality ID. When provided, emits `theme.buttons`. */
-    buttonPersonalityId?: ButtonPersonalityId;
-    /**
-     * Resolved palette variant ID. When provided, replaces the recipe-based
-     * palette lookup; the recipe family is still consulted for the rest of the
-     * theme (typography, spacing, etc.).
-     */
-    paletteVariantId?: PaletteVariantId;
+type ResolvedPaletteCompileOptions = Readonly<{
+    /** A complete palette resolved from an explicit curated or site selection. */
+    resolvedPalette: ResolvedPaletteSelection;
+    paletteVariantId?: never;
+    paletteOverrides?: never;
+}>;
+type LegacyPaletteCompileOptions = Readonly<{
+    resolvedPalette?: undefined;
     /**
-     * Sparse per-token hex overrides applied on top of the palette variant.
-     * Tokens not in this map keep the variant's value.
+     * Legacy curated-palette selection retained while persisted Theme V2
+     * selections are migrated to the explicit palette-selection model.
      */
+    paletteVariantId?: CuratedPaletteId;
+    /** Legacy sparse overrides materialized into a site palette during migration. */
     paletteOverrides?: PaletteOverrides;
 }>;
+export type CompileTokenRecipesOptions = Readonly<{
+    /** Resolved button personality ID. When provided, emits `theme.buttons`. */
+    buttonPersonalityId?: ButtonPersonalityId;
+}> & (ResolvedPaletteCompileOptions | LegacyPaletteCompileOptions);
 /**
  * Compiles bounded token recipes to the current Theme schema. This is intentionally
  * pure and schema-validated so generated Theme V2 choices have a concrete legacy
  * Theme output before any persistence or Phase 5 integration consumes them.
  *
- * Optional `options` accept already-resolved button personality and palette
- * variant IDs (typically supplied by `compileSiteThemeFromSelections`). When
- * IDs are omitted, the function falls through to the legacy recipe-based
- * palette lookup and leaves `theme.buttons` as the mock-theme default.
+ * Optional `options` accept an already-resolved palette selection and button
+ * personality. During migration they also accept the legacy curated ID plus
+ * sparse overrides. When neither palette input is supplied, the function falls
+ * through to the recipe-based palette lookup.
  */
 export declare function compileTokenRecipes(recipes: ThemeTokenRecipes, options?: CompileTokenRecipesOptions): Theme;
 export {};