@riverbankcms/sdk 0.129.1 → 0.130.2

package/dist/_dts/sdk/src/rendering/helpers/loadContent.d.ts

@@ -102,7 +102,7 @@ export type PageContentResult = {
     page: PageProps['page'];
     runtimeBoundaries?: PageProps['runtimeBoundaries'];
     /** Site theme for styling */
-    theme: Theme;
+    theme: Theme | null;
     /** Site ID */
     siteId: string;
     /** Declarative custom blocks stored in DB (if any) */
@@ -151,7 +151,7 @@ export type EntryContentResult = {
         contentEntry: Record<string, unknown>;
     };
     /** Site theme for styling (useful if rendering with SDK components) */
-    theme: Theme;
+    theme: Theme | null;
     /** Site ID */
     siteId: string;
     /** Declarative custom blocks stored in DB (if any) */
@@ -213,7 +213,7 @@ export type PageSurfaceContentResult = {
         pageSurface: Record<string, unknown>;
         subject: PageSurfaceContentData['subject'];
     };
-    theme: Theme;
+    theme: Theme | null;
     siteId: string;
     customBlocks?: SdkCustomBlock[];
     site: SiteData;
@@ -256,6 +256,7 @@ export declare function isPageSurfaceContent(result: LoadContentResult): result
  *   });
  *
  *   if (isPageContent(content)) {
+ *     if (!content.theme) throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
  *     return <Page {...content} />;
  *   }
  *
@@ -284,6 +285,7 @@ export declare function isPageSurfaceContent(result: LoadContentResult): result
  *   }
  * }
  *
+ * if (!content.theme) throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
  * return <Page {...content} />;
  * ```
  *

package/dist/_dts/sdk/src/rendering/helpers/pageRuntimeSupport.d.ts

@@ -5,7 +5,7 @@ import type { SdkCustomBlock } from '../../config/types';
 export type RuntimeSdkConfig = NonNullable<SiteResponse['sdkConfig']>;
 export type SiteData = SiteResponse['site'];
 export type SiteRenderSupport = Readonly<{
-    theme: Theme;
+    theme: Theme | null;
     site: SiteData;
     sdkConfig: RuntimeSdkConfig | null;
     bookingOfferingPresets: readonly SiteBookingOfferingPresetSummary[];

package/dist/_dts/sdk/src/rendering/hooks/useContent.d.ts

@@ -58,7 +58,7 @@ type PageSuccessState = {
     page: PageProps['page'];
     runtimeBoundaries?: PageProps['runtimeBoundaries'];
     entry: null;
-    theme: Theme;
+    theme: Theme | null;
     siteId: string;
     resolvedData: ResolvedBlockData;
     supabaseUrl?: string;
@@ -73,7 +73,7 @@ type EntrySuccessState = {
     type: 'entry';
     page: null;
     entry: ContentEntryData;
-    theme: Theme;
+    theme: Theme | null;
     siteId: string;
     resolvedData: null;
 };
@@ -116,6 +116,7 @@ export declare function isEntryContentResult(result: UseContentResult): result i
  *   if (content.error) return <div>Error: {content.error.message}</div>;
  *
  *   if (isPageContentResult(content)) {
+ *     if (!content.theme) return <div>This site needs a theme before it can be displayed.</div>;
  *     return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
  *   }
  *
@@ -145,6 +146,7 @@ export declare function isEntryContentResult(result: UseContentResult): result i
  *   }
  * }
  *
+ * if (!content.theme) return <MissingTheme />;
  * return <Page {...content} />;
  * ```
  */

package/dist/_dts/sdk/src/rendering/index.d.ts

@@ -9,6 +9,8 @@ export type { PageProps } from './components/Page';
 export { Layout } from './components/Layout';
 export type { LayoutProps, HeaderData, FooterData, CustomHeaderData, CustomFooterData, } from './components/Layout';
 export { UnsupportedOverrideOnlyLayoutChromeError } from './components/Layout';
+export { MISSING_SDK_THEME_ERROR_CODE, MissingSdkThemeError, } from './themeAdmission';
+export type { MissingSdkThemeReason } from './themeAdmission';
 export type { SdkThemeResponsiveMode, SdkThemeRuntime } from './themeRuntime';
 export type { SdkOverrideOnlyRendering, SdkOverrideOnlyRuntime, SdkRenderingMode, } from './renderingMode';
 export { Block } from './components/Block';
@@ -18,7 +20,7 @@ export type { LoadPageParams, LoadPageResult } from './helpers/loadPage';
 export { loadContent, isPageContent, isEntryContent, isPageSurfaceContent, } from './helpers/loadContent';
 export type { LoadContentParams, LoadContentResult, ContentEntryData, PagePreviewMetadata, SiteData, } from './helpers/loadContent';
 export type { BlockLoaderMap, DataLoaderContext, DataLoaderFn, DataLoaderOverrides, DataLoaderPreviewStage, DataLoaderRenderTarget, DataLoaderSearchParams, DataLoaderValue, } from '../data/types';
-export type { AppointmentBookingContent, BlogListingContent, BlogPostContent, BodyTextAlignment, BodyTextContent, ButtonVariant, CalendarTabViews, CardStylesContent, CollectionContent, ColumnsContent, ColumnOption, ContainerStylesContent, CtaFullContent, DisplayMode, EmbedContent, EventCalendarContent, EventDetailsContent, EventLayout, EventListingContent, EventRegistrationContent, EventSpotlightContent, FaqContent, FaqItem, FilterAutoShow, FormBlockContent, GiftingContent, HeroContent, HeroCta, HeroCtaInput, HeroMedia, ImageColSize, ImageGalleryContent, LayoutAlign, LayoutWidth, Media, MediaTextAlignment, MediaTextAspectRatio, MediaTextContent, MediaTextImagePosition, NewsletterSignupContent, NewsletterSignupPreset, RichTextDoc, TipTapNode, TipTapMark, LinkValue, InternalLinkValue, ExternalLinkValue, CustomLinkValue, PageLinkValue, EntryLinkValue, RichTextPrimitiveProps, RichTextVariant, PageOutline, BlockOutline, RouteMap, RouteMapEntry, OccurrenceContextData, EntrySubrouteContextData, Theme, ThemeTokens, SectionStylesContent, SemanticSpacing, ShopContent, SingleButtonContent, SiteFooterContent, SiteHeaderContent, StackContentAlignment, StackImagePosition, SystemBlockContentByFullKind, SystemBlockContentByKind, SystemBlockContentFor, SystemBlockShortKind, TeamMembersContent, TestimonialEntryContent, TestimonialsBlockContent, ThumbnailPadding, ThumbnailShape, VideoGridContent, WeekStart, MediaAssetIndexItem, ImageOptions, ResolveImageUrlContext, ResolveImageUrlContextInput, ResolveImageSourceSetOptions, ResolvedImageSourceSet, } from '../contracts';
+export type { AppointmentBookingContent, BlogListingContent, BlogPostContent, BodyTextAlignment, BodyTextContent, ButtonVariant, CalendarTabViews, CardStylesContent, CollectionContent, ColumnsContent, ColumnOption, ContainerStylesContent, ContentFrameIntent, CtaFullContent, DisplayMode, EmbedContent, EventCalendarContent, EventDetailsContent, EventLayout, EventListingContent, EventRegistrationContent, EventSpotlightContent, FaqContent, FaqItem, CardRole, FeatureCardLegacySurfaceRole, FeatureCardSurfaceRole, FilterAutoShow, FormBlockContent, GiftingContent, HeroContent, HeroCta, HeroCtaInput, HeroMedia, ImageColSize, ImageGalleryContent, LayoutAlign, LayoutWidth, Media, MediaTextAlignment, MediaTextAspectRatio, MediaTextContent, MediaTextImagePosition, NewsletterSignupContent, NewsletterSignupPreset, RichTextDoc, TipTapNode, TipTapMark, LinkValue, InternalLinkValue, ExternalLinkValue, CustomLinkValue, PageLinkValue, EntryLinkValue, RichTextPrimitiveProps, RichTextVariant, PageOutline, BlockOutline, RouteMap, RouteMapEntry, OccurrenceContextData, EntrySubrouteContextData, Theme, ThemeTokens, SectionStylesContent, SemanticSpacing, ShopContent, SingleButtonContent, SiteFooterContent, SiteHeaderContent, StackContentAlignment, StackImagePosition, SystemBlockContentByFullKind, SystemBlockContentByKind, SystemBlockContentFor, SystemBlockShortKind, TeamMembersContent, TestimonialEntryContent, TestimonialsBlockContent, ThumbnailPadding, ThumbnailShape, VideoGridContent, WeekStart, MediaAssetIndexItem, ImageOptions, ResolveImageUrlContext, ResolveImageUrlContextInput, ResolveImageSourceSetOptions, ResolvedImageSourceSet, } from '../contracts';
 export { ImagePresets } from '../contracts';
 export { RichText } from './primitives/RichText';
 export { resolveImageUrl, resolveImageUrlWithContext, resolveImageSourceSetWithContext, } from './image';

package/dist/_dts/sdk/src/rendering/islands/types.d.ts

@@ -147,7 +147,12 @@ export type PublicPassProduct = {
     validDays: number | null;
     eligibleCategoryIds: string[];
     eligibleCategoryNames: string[];
-};
+} & ({
+    purchaseAvailability: 'purchasable';
+} | {
+    purchaseAvailability: 'display_only';
+    unavailabilityReason: 'online_payments_unavailable';
+});
 export type PublicMembershipProduct = {
     id: string;
     name: string;
@@ -239,7 +244,15 @@ export type FormIslandProps = BlocksFormIslandProps;
 export type BookingFormService = BlocksBookingFormService;
 export type BookingFormConfig = BlocksBookingFormConfig;
 export type BookingFormIslandProps = BlocksBookingFormIslandProps;
-export type CardVariant = 'default' | 'variant1' | 'variant2';
+/**
+ * Card surface selection as it reaches an island.
+ *
+ * The canonical vocabulary is the card *role* (`none` / `open` / `default` /
+ * `alternative`); `variant1` / `variant2` are legacy aliases of `alternative`
+ * that persisted content still carries. Both keep parsing — the union is
+ * widened additively so no existing SDK consumer breaks.
+ */
+export type CardVariant = 'default' | 'alternative' | 'open' | 'none' | 'variant1' | 'variant2';
 export type ButtonVariant = SystemButtonVariant;
 export type EventListingLayout = EventLayout;
 export type CardOrientation = 'vertical' | 'horizontal';

package/dist/_dts/sdk/src/rendering/server.d.ts

@@ -5,6 +5,8 @@
 export { Page } from './components/Page.server';
 export type { PageProps } from './components/Page.server';
 export { Layout, UnsupportedOverrideOnlyLayoutChromeError, } from './components/Layout';
+export { MISSING_SDK_THEME_ERROR_CODE, MissingSdkThemeError, } from './themeAdmission';
+export type { MissingSdkThemeReason } from './themeAdmission';
 export type { LayoutProps, HeaderData, FooterData, CustomHeaderData, CustomFooterData, } from './components/Layout';
 export type { SdkThemeResponsiveMode, SdkThemeRuntime } from './themeRuntime';
 export type { SdkOverrideOnlyRendering, SdkOverrideOnlyRuntime, SdkRenderingMode, } from './renderingMode';

package/dist/_dts/sdk/src/rendering/themeAdmission.d.ts

@@ -0,0 +1,11 @@
+import type { Theme } from '../contracts';
+export declare const MISSING_SDK_THEME_ERROR_CODE: "missing_sdk_theme";
+export type MissingSdkThemeReason = 'cms_theme_absent' | 'local_theme_absent';
+export declare class MissingSdkThemeError extends Error {
+    readonly siteId: string;
+    readonly reason: MissingSdkThemeReason;
+    readonly themeKey?: string | undefined;
+    readonly code: "missing_sdk_theme";
+    constructor(siteId: string, reason?: MissingSdkThemeReason, themeKey?: string | undefined);
+}
+export declare function requireSdkTheme(theme: Theme | null | undefined, siteId: string, reason?: MissingSdkThemeReason): Theme;

package/dist/_dts/sdk/src/theme-bridge/types.d.ts

@@ -44,10 +44,12 @@ export interface ThemeBridgeButtonConfig {
  */
 export interface ThemeBridgeCardConfig {
     /**
-     * Which card variants to generate.
+     * Which card variants to generate — one id per card role the theme
+     * implements. `elevated` and `outlined` are the pre-role names of
+     * `alternative` and `open`, kept so existing configs keep working.
      * @default ['default']
      */
-    variants?: Array<'default' | 'elevated' | 'outlined'>;
+    variants?: Array<'default' | 'alternative' | 'open' | 'elevated' | 'outlined'>;
 }
 /**
  * Component CSS generation options.

package/dist/_dts/sdk/src/version.d.ts

@@ -8,4 +8,4 @@
  * 1. This constant
  * 2. The "version" field in package.json
  */
-export declare const SDK_VERSION = "0.129.1";
+export declare const SDK_VERSION = "0.130.2";

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

@@ -1,4 +1,4 @@
-import type { BlockThemeOverride, Theme } from "./schema";
+import { type BlockThemeOverride, type Theme } from './schema';
 import type { HeadingDecorationOverride, VisibleHeadingDecoration } from "./site-styles/types";
 export declare function normalizeBlockKind(blockKind: string): string;
 export type EffectiveHeadingDecoration = Readonly<{

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

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+export declare const boxBackgroundOverlaySchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"none">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"color">;
+    color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"gradient">;
+    gradient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>], "type">>;
+export declare const boxBackgroundSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    contentOwner: z.ZodOptional<z.ZodLiteral<"page-design-editor">>;
+    textColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linkColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supportingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodLiteral<"color">;
+    color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    contentOwner: z.ZodOptional<z.ZodLiteral<"page-design-editor">>;
+    textColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linkColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supportingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodLiteral<"gradient">;
+    gradient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    gradientPresetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    contentOwner: z.ZodOptional<z.ZodLiteral<"page-design-editor">>;
+    textColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linkColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supportingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    opacity: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNullable<z.ZodNumber>>>;
+    objectFit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        fill: "fill";
+        custom: "custom";
+        fit: "fit";
+        original: "original";
+    }>>>;
+    scale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    position: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    motion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        static: "static";
+        "fixed-frame": "fixed-frame";
+    }>>>;
+    overflow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    overlay: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"color">;
+        color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"gradient">;
+        gradient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>], "type">>>>;
+    type: z.ZodLiteral<"image">;
+    image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        purpose: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        assetId: z.ZodOptional<z.ZodString>;
+        identifier: z.ZodOptional<z.ZodString>;
+        src: z.ZodOptional<z.ZodString>;
+        alt: z.ZodOptional<z.ZodString>;
+        filename: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        storageBucket: z.ZodOptional<z.ZodString>;
+        storagePath: z.ZodOptional<z.ZodString>;
+        poster: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            tag: z.ZodLiteral<"storage">;
+            assetId: z.ZodOptional<z.ZodString>;
+            storageBucket: z.ZodString;
+            storagePath: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            tag: z.ZodLiteral<"external-src">;
+            assetId: z.ZodOptional<z.ZodString>;
+            src: z.ZodString;
+        }, z.core.$strip>], "tag">>;
+        transform: z.ZodOptional<z.ZodObject<{
+            aspectCrops: z.ZodOptional<z.ZodPipe<z.ZodTransform<object | undefined, unknown>, z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodObject<{
+                aspect: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+                rect: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+                hotspot: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    radius: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+                rotation: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>>;
+            }, z.core.$strip>>>>>;
+            rect: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            hotspot: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                radius: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            rotation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"image">;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    contentOwner: z.ZodOptional<z.ZodLiteral<"page-design-editor">>;
+    textColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linkColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    supportingColor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    opacity: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodNullable<z.ZodNumber>>>;
+    objectFit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        fill: "fill";
+        custom: "custom";
+        fit: "fit";
+        original: "original";
+    }>>>;
+    scale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    position: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    motion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        static: "static";
+        "fixed-frame": "fixed-frame";
+    }>>>;
+    overflow: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    overlay: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"none">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"color">;
+        color: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"gradient">;
+        gradient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        opacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>], "type">>>>;
+    type: z.ZodLiteral<"video">;
+    image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        purpose: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        assetId: z.ZodOptional<z.ZodString>;
+        identifier: z.ZodOptional<z.ZodString>;
+        src: z.ZodOptional<z.ZodString>;
+        alt: z.ZodOptional<z.ZodString>;
+        filename: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        storageBucket: z.ZodOptional<z.ZodString>;
+        storagePath: z.ZodOptional<z.ZodString>;
+        poster: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            tag: z.ZodLiteral<"storage">;
+            assetId: z.ZodOptional<z.ZodString>;
+            storageBucket: z.ZodString;
+            storagePath: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            tag: z.ZodLiteral<"external-src">;
+            assetId: z.ZodOptional<z.ZodString>;
+            src: z.ZodString;
+        }, z.core.$strip>], "tag">>;
+        transform: z.ZodOptional<z.ZodObject<{
+            aspectCrops: z.ZodOptional<z.ZodPipe<z.ZodTransform<object | undefined, unknown>, z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodObject<{
+                aspect: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodString>>;
+                rect: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>>;
+                hotspot: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    radius: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+                rotation: z.ZodPipe<z.ZodTransform<{} | undefined, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>>;
+            }, z.core.$strip>>>>>;
+            rect: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+            hotspot: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                radius: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            rotation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"video">;
+    }, z.core.$strip>>>;
+    showVideoOnMobile: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>], "type">;
+export type BoxBackground = z.infer<typeof boxBackgroundSchema>;

package/dist/_dts/theme-core/src/buttons/buttonColourContract.d.ts

@@ -0,0 +1,96 @@
+import type { ButtonUnsupportedEffectReason } from './effectClassification';
+import type { ButtonColourTreatment, OpaqueButtonColourToken } from './types';
+export declare const BUTTON_VISUAL_STATES: readonly ["base", "hover", "focus", "active", "disabled"];
+export type ButtonVisualState = (typeof BUTTON_VISUAL_STATES)[number];
+/** A surface whose rendered colour and foreground contract are both known. */
+export type KnownButtonSurface = Readonly<{
+    kind: 'solid';
+    backgroundHex: string;
+    backgroundCss: string;
+    foregroundHex: string;
+    foregroundCss: string;
+}>;
+export type ButtonColourPalette = Readonly<Record<string, string>>;
+export declare const BUTTON_CONTRAST_POLICY: {
+    readonly textMinimumRatio: 4.5;
+    readonly nonTextMinimumRatio: 3;
+    readonly gradientSamplesPerSegment: 20;
+    readonly alphaBackgrounds: "reject-without-known-surface";
+    readonly disabled: "retain-full-colour-contract";
+};
+export type ButtonColourContractError = Readonly<{
+    tag: 'unknown_palette_token';
+    variantId: string;
+    state: ButtonVisualState;
+    token: OpaqueButtonColourToken;
+}> | Readonly<{
+    tag: 'missing_on_colour';
+    variantId: string;
+    state: ButtonVisualState;
+    backgroundToken: OpaqueButtonColourToken;
+    foregroundToken: OpaqueButtonColourToken;
+}> | Readonly<{
+    tag: 'insufficient_contrast';
+    variantId: string;
+    state: ButtonVisualState;
+    background: string;
+    foreground: string;
+    ratio: number;
+    requiredRatio: number;
+}> | Readonly<{
+    tag: 'insufficient_surface_contrast';
+    variantId: string;
+    state: ButtonVisualState;
+    buttonPaint: string;
+    surface: string;
+    ratio: number;
+    requiredRatio: number;
+}> | Readonly<{
+    tag: 'unsupported_colour_effect';
+    variantId: string;
+    state: ButtonVisualState;
+    effectId: string;
+    reason: ButtonUnsupportedEffectReason;
+}> | Readonly<{
+    tag: 'invalid_colour_effect_options';
+    variantId: string;
+    state: ButtonVisualState;
+    effectId: string;
+    option: string;
+}> | Readonly<{
+    tag: 'inapplicable_colour_effect';
+    variantId: string;
+    state: ButtonVisualState;
+    effectId: string;
+    treatment: ButtonColourTreatment['type'];
+}> | Readonly<{
+    tag: 'unknown_button_effect';
+    variantId: string;
+    state: ButtonVisualState;
+    effectId: string;
+}>;
+export declare function formatButtonColourContractError(error: ButtonColourContractError): string;
+export declare function validateButtonSurfaceContrast(input: Readonly<{
+    variantId: string;
+    state: ButtonVisualState;
+    buttonPaint: string;
+    surfaceHex: string;
+}>): Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    error: ButtonColourContractError;
+}>;
+export declare function validateButtonTextContrast(input: Readonly<{
+    variantId: string;
+    state: ButtonVisualState;
+    background: string;
+    backgroundHex: string;
+    foreground: string;
+    foregroundHex: string;
+}>): Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    error: ButtonColourContractError;
+}>;

package/dist/_dts/theme-core/src/buttons/buttonSurfaceContext.d.ts

@@ -0,0 +1,78 @@
+import { type ButtonColourContractError, type ButtonColourPalette, type ButtonVisualState, type KnownButtonSurface, type ResolvedButtonColourStates, type ResolvedButtonFocusIndicator } from './resolveButtonColourStates';
+import type { ButtonSystem, VariantRole } from './types';
+export type ButtonSurfaceContext = Readonly<{
+    kind: 'known-solid';
+    source: 'palette-token' | 'literal-css' | 'fallback-token';
+    surface: KnownButtonSurface;
+}> | Readonly<{
+    kind: 'unknown';
+    reason: 'missing-background' | 'image-background' | 'gradient-background' | 'composited-background' | 'unresolvable-colour';
+}>;
+/**
+ * Narrow rendering-boundary contract for the surface beneath a button.
+ * Blocks own their authored background schema and translate it into this
+ * vocabulary; theme-core does not inspect or guess at that external shape.
+ */
+export type ButtonSurfaceInput = Readonly<{
+    kind: 'inherit';
+    foreground?: string | null;
+}> | Readonly<{
+    kind: 'solid';
+    color?: string | null;
+    foreground?: string | null;
+    composited: boolean;
+}> | Readonly<{
+    kind: 'image';
+}> | Readonly<{
+    kind: 'gradient';
+}> | Readonly<{
+    kind: 'unknown';
+}>;
+export type RejectedButtonSurfaceCandidate = Readonly<{
+    candidate: 'preferred' | 'surface-outline' | VariantRole;
+    error: ButtonColourContractError;
+}>;
+export type ContextualButtonResolution = Readonly<{
+    kind: 'preferred';
+    requestedRole: VariantRole;
+    states: ResolvedButtonColourStates;
+    focusIndicator: ResolvedButtonFocusIndicator;
+    boundary: Readonly<{
+        width: string;
+        color: string;
+    }> | null;
+}> | Readonly<{
+    kind: 'repaired';
+    requestedRole: VariantRole;
+    candidate: 'surface-outline' | VariantRole;
+    states: ResolvedButtonColourStates;
+    focusIndicator: ResolvedButtonFocusIndicator;
+    boundary: Readonly<{
+        width: string;
+        color: string;
+    }> | null;
+    rejectedCandidates: readonly RejectedButtonSurfaceCandidate[];
+}> | Readonly<{
+    kind: 'unresolved';
+    requestedRole: VariantRole;
+    rejectedCandidates: readonly RejectedButtonSurfaceCandidate[];
+}>;
+/**
+ * Derive only what the rendered section can honestly prove about its backing.
+ * Images, gradients, alpha/composite layers and arbitrary CSS remain unknown.
+ */
+export declare function deriveButtonSurfaceContext(input: ButtonSurfaceInput, palette: Readonly<Record<string, string>>, fallbackToken?: string): ButtonSurfaceContext;
+export declare function resolveContextualButtonRole(input: Readonly<{
+    role: VariantRole;
+    buttonSystem: ButtonSystem;
+    palette: ButtonColourPalette;
+    surface: KnownButtonSurface;
+}>): ContextualButtonResolution;
+export declare function contextualButtonSurfaceStyles(resolution: ContextualButtonResolution): Readonly<Record<string, string>>;
+/**
+ * Break an inherited surface contract when a nested element establishes a
+ * backing whose colours cannot be proven (for example an image or gradient).
+ */
+export declare function contextualButtonSurfaceResetStyles(): Readonly<Record<string, string>>;
+export declare function actionVariableName(role: string, state: ButtonVisualState, property: string): string;
+export declare function actionVariableFallback(role: string, state: ButtonVisualState, property: string, fallback: string): string;

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

@@ -8,6 +8,7 @@ export * from './parseThemeForPersistence';
 export * from './classNames';
 export * from './generateButtonCss';
 export * from './resolveButtonColourStates';
+export * from './buttonSurfaceContext';
 export * from './affordanceIcons';
 export * from './generateDefaultButtonSystem';
 export * from './constants';

package/dist/_dts/theme-core/src/buttons/parseThemeForPersistence.d.ts

@@ -14,8 +14,8 @@ declare const validatedThemeForPersistenceBrand: unique symbol;
 /**
  * A schema-parsed Theme whose button variants all compile against its palette.
  *
- * The brand is intentionally phantom: validation does not mutate themes or add
- * persistence-only data to the JSON document.
+ * The brand is intentionally phantom. The parser also canonicalizes legacy
+ * button systems by adding the standard surface policy before the next save.
  */
 export type ValidatedThemeForPersistence = Theme & {
     readonly [validatedThemeForPersistenceBrand]: true;

package/dist/_dts/theme-core/src/buttons/resolveButtonColourStates.d.ts

@@ -1,65 +1,17 @@
-import type { ExpandedPalette } from '../palette/expandPalette';
-import type { ButtonColourTreatment, ButtonGlobalSettings, ButtonVariant, OpaqueButtonColourToken, VariantEffects } from './types';
-import { type ButtonUnsupportedEffectReason } from './effectClassification';
+import type { ButtonGlobalSettings, ButtonVariant, OpaqueButtonColourToken, VariantEffects } from './types';
+import { type ButtonColourContractError, type ButtonColourPalette, type ButtonVisualState, type KnownButtonSurface } from './buttonColourContract';
+export { BUTTON_CONTRAST_POLICY, BUTTON_VISUAL_STATES, formatButtonColourContractError, type ButtonColourContractError, type ButtonColourPalette, type ButtonVisualState, type KnownButtonSurface, } from './buttonColourContract';
 export { classifyButtonEffectId, type ButtonEffectClassification, } from './effectClassification';
-export declare const BUTTON_VISUAL_STATES: readonly ["base", "hover", "focus", "active", "disabled"];
-export type ButtonVisualState = (typeof BUTTON_VISUAL_STATES)[number];
-export declare const BUTTON_CONTRAST_POLICY: {
-    readonly textMinimumRatio: 4.5;
-    readonly nonTextMinimumRatio: 3;
-    readonly gradientSamplesPerSegment: 20;
-    readonly alphaBackgrounds: "reject-without-known-surface";
-    readonly disabled: "retain-full-colour-contract";
-};
-export type ButtonColourContractError = Readonly<{
-    tag: 'unknown_palette_token';
-    variantId: string;
-    state: ButtonVisualState;
-    token: OpaqueButtonColourToken;
-}> | Readonly<{
-    tag: 'missing_on_colour';
-    variantId: string;
-    state: ButtonVisualState;
-    backgroundToken: OpaqueButtonColourToken;
-    foregroundToken: OpaqueButtonColourToken;
-}> | Readonly<{
-    tag: 'insufficient_contrast';
-    variantId: string;
-    state: ButtonVisualState;
-    background: string;
-    foreground: string;
-    ratio: number;
-    requiredRatio: number;
-}> | Readonly<{
-    tag: 'unsupported_colour_effect';
-    variantId: string;
-    state: ButtonVisualState;
-    effectId: string;
-    reason: ButtonUnsupportedEffectReason;
-}> | Readonly<{
-    tag: 'invalid_colour_effect_options';
-    variantId: string;
-    state: ButtonVisualState;
-    effectId: string;
-    option: string;
-}> | Readonly<{
-    tag: 'inapplicable_colour_effect';
-    variantId: string;
-    state: ButtonVisualState;
-    effectId: string;
-    treatment: ButtonColourTreatment['type'];
-}> | Readonly<{
-    tag: 'unknown_button_effect';
-    variantId: string;
-    state: ButtonVisualState;
-    effectId: string;
-}>;
 export type ResolvedButtonColour = Readonly<{
     kind: 'solid';
     backgroundToken: OpaqueButtonColourToken;
     foregroundToken: OpaqueButtonColourToken;
     backgroundCss: string;
     foregroundCss: string;
+}> | Readonly<{
+    kind: 'known-solid';
+    backgroundCss: string;
+    foregroundCss: string;
 }> | Readonly<{
     kind: 'gradient';
     backgroundTokens: readonly [OpaqueButtonColourToken, OpaqueButtonColourToken, ...OpaqueButtonColourToken[]];
@@ -95,6 +47,6 @@ export type ButtonColourContractResult = Readonly<{
 export declare function compileButtonColourStates(input: Readonly<{
     variant: ButtonVariant;
     global: ButtonGlobalSettings;
-    palette: ExpandedPalette;
+    palette: ButtonColourPalette;
+    surface?: KnownButtonSurface;
 }>): ButtonColourContractResult;
-export declare function formatButtonColourContractError(error: ButtonColourContractError): string;