@riverbankcms/sdk 0.130.2 → 0.134.0

package/dist/_dts/sdk/src/public-api/contracts.d.ts

@@ -1,9 +1,11 @@
-import type { AddressedLocationValue, BusinessAddress } from '../../../core/src/index';
-import type { APIEndpoints, SdkRuntimePageSurfaceSubject as ApiSdkRuntimePageSurfaceSubject, SiteBySlugResponse as ApiSiteBySlugResponse, SiteBookingOfferingPresetSummary as ApiSiteBookingOfferingPresetSummary } from '../../../api/src/index';
+import type { AddressedLocationValue, BookingConsent, BusinessAddress } from '../../../core/src/index';
+import type { ResolvedInternalLinkEntityType } from '../../../blocks/src/index';
+import type { APIEndpoints, RoutableContentItem as ApiRoutableContentItem, SdkRuntimePageSurfaceSubject as ApiSdkRuntimePageSurfaceSubject, SiteBySlugResponse as ApiSiteBySlugResponse, SiteBookingOfferingPresetSummary as ApiSiteBookingOfferingPresetSummary } from '../../../api/src/index';
 import type { MediaAssetIndexItem, SiteFooterContent, SiteHeaderContent } from '../contracts';
 import type { CompiledBoundaryRuntime } from '../../../theme-core/src/site-styles/index';
 import type { BlockFieldConfig as SdkBlockFieldConfig, BlockFieldOptionsMap as SdkBlockFieldOptionsMap, ContentConfig as SdkContentConfig, ContainerOptionsConfig as SdkContainerOptionsConfig, FieldSelectOption as SdkFieldSelectOption, SdkCustomBlock, SdkThemeConfig, SdkThemePalette, SectionBackground as SdkSectionBackground, SectionOptionsConfig as SdkSectionOptionsConfig, SiteStyleConfig as SdkSiteStyleConfig } from '../config/types';
 import type { PublicTeamMemberBlockItem } from './teamMemberContracts';
+import type { ResolveEventSubrouteResponse } from './eventSubrouteContracts';
 export type { PublicTeamMemberBlockItem, PublicTeamMemberPhoto, PublicTeamMemberSummary, } from './teamMemberContracts';
 export type { PublicWholeSeriesOfferingResponse } from './wholeSeriesContracts';
 export type RuntimeSiteSdkConfig = {
@@ -99,7 +101,7 @@ export type InternalLinkPayload = {
     kind: 'internal';
     routeId: string;
     entityId: string;
-    entityType: 'page' | 'content';
+    entityType: ResolvedInternalLinkEntityType;
     href: string;
     title: string;
     typeLabel: string;
@@ -268,7 +270,7 @@ export type SiteRouteRecord = {
     publishedAt?: string | null;
 };
 export type SiteBookingOfferingPresetSummary = ApiSiteBookingOfferingPresetSummary;
-type SiteSelectionResponse = Pick<ApiSiteBySlugResponse, 'theme' | 'themeId' | 'selectionId' | 'selectionVersion' | 'selectionUpdatedAt' | 'selectionButtonStyleSelection' | 'selectionHeaderSelection' | 'selectionFooterLookId'>;
+type SiteSelectionResponse = Pick<ApiSiteBySlugResponse, 'theme' | 'themeId' | 'selectionId' | 'selectionVersion' | 'selectionUpdatedAt' | 'selectionButtonStyleSelection' | 'selectionButtonStyleRepairs' | 'selectionHeaderSelection' | 'selectionFooterLookId'>;
 export type SiteResponse = SiteSelectionResponse & {
     site: {
         id: string;
@@ -534,6 +536,7 @@ export type PublicBookingService = {
     title: string;
     description: string | null;
     durationMinutes: number;
+    consent?: BookingConsent;
 };
 export type PublicBookingServicesResponse = {
     services: PublicBookingService[];
@@ -638,18 +641,7 @@ export type PublicMembershipsResponse = {
         eligibleCategoryNames: string[];
     }>;
 };
-export type ResolveEventOccurrenceResponse = {
-    occurrence: {
-        id: string;
-        seriesId: string;
-        startsAt: string;
-        endsAt: string;
-        timeZone: string;
-        status: string;
-        capacityOverride: number | null;
-        overridesJson: Record<string, unknown>;
-    } | null;
-};
+export type { ResolveEventOccurrenceResponse, ResolveEventRunResponse, ResolveEventSubrouteResponse, } from './eventSubrouteContracts';
 export type CheckRedirectResponse = {
     redirectTo: string | null;
     status?: number;
@@ -674,22 +666,7 @@ export type RouteNonContentDecisionResponse = Exclude<RouteOutcomeResponse, {
 export type RouteDecisionResponse = {
     type: 'contentExists';
 } | RouteNonContentDecisionResponse;
-export type RoutableContentItem = {
-    routeId: string;
-    entityId: string;
-    entityType: 'page' | 'content';
-    identifier: string | null;
-    contentTypeKey?: string | null;
-    contentTypeName?: string | null;
-    title: string;
-    draftTitle: string | null;
-    path: string;
-    draftPath: string | null;
-    status: string;
-    draftStatus: string | null;
-    typeLabel: string;
-    updatedAt: string | null;
-};
+export type RoutableContentItem = ApiRoutableContentItem;
 export type RoutableContentResponse = {
     items: RoutableContentItem[];
 };
@@ -705,7 +682,7 @@ export type SitemapRoutesResponse = {
     pageSize: number;
     allowIndexingInProduction: boolean;
 };
-export type PublicEndpointName = 'getSite' | 'getContentByPath' | 'resolveRouteOutcome' | 'resolveRouteDecision' | 'listPublishedEntries' | 'getPublishedEntryPreview' | 'getPublicFormById' | 'listPublicForms' | 'getPublicBookingServices' | 'getPublicWeeklySlotAvailability' | 'getPublicChallenge' | 'listPublicEvents' | 'batchBlockLoaders' | 'listPublicTeamMembers' | 'listPublicProducts' | 'listPublicPasses' | 'listPublicMemberships' | 'resolveEventOccurrence' | 'checkRedirect' | 'getRoutableContent' | 'getPublicRoutableContent' | 'getPublicSitemapRoutes';
+export type PublicEndpointName = 'getSite' | 'getContentByPath' | 'resolveRouteOutcome' | 'resolveRouteDecision' | 'listPublishedEntries' | 'getPublishedEntryPreview' | 'getPublicFormById' | 'listPublicForms' | 'getPublicBookingServices' | 'getPublicWeeklySlotAvailability' | 'getPublicChallenge' | 'listPublicEvents' | 'batchBlockLoaders' | 'listPublicTeamMembers' | 'listPublicProducts' | 'listPublicPasses' | 'listPublicMemberships' | 'resolveEventSubroute' | 'checkRedirect' | 'getRoutableContent' | 'getPublicRoutableContent' | 'getPublicSitemapRoutes';
 export type PublicAPIEndpoints = {
     getSite: APIEndpointBase<never, {
         id?: string;
@@ -834,11 +811,7 @@ export type PublicAPIEndpoints = {
         siteId: string;
         categories?: string;
     }, PublicMembershipsResponse>;
-    resolveEventOccurrence: APIEndpointBase<never, {
-        siteId: string;
-        eventSeriesIds: string;
-        segment: string;
-    }, ResolveEventOccurrenceResponse>;
+    resolveEventSubroute: APIEndpointBase<never, NonNullable<APIEndpoints['resolveEventSubroute']['query']>, ResolveEventSubrouteResponse>;
     checkRedirect: APIEndpointBase<never, {
         site: string;
         path: string;

package/dist/_dts/sdk/src/public-api/eventSubrouteContracts.d.ts

@@ -0,0 +1,12 @@
+import type { APIEndpoints } from '../../../api/src/index';
+export type ResolveEventSubrouteResponse = NonNullable<APIEndpoints['resolveEventSubroute']['response']>;
+export type ResolveEventOccurrenceResponse = Readonly<{
+    occurrence: Extract<ResolveEventSubrouteResponse['subroute'], {
+        kind: 'event-occurrence';
+    }>['occurrence'] | null;
+}>;
+export type ResolveEventRunResponse = Readonly<{
+    run: Extract<ResolveEventSubrouteResponse['subroute'], {
+        kind: 'event-run';
+    }>['run'] | null;
+}>;

package/dist/_dts/sdk/src/public-api/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { ApiResult, HTTPMethod, PublicAPIEndpoints, PublicEndpointName } from './contracts';
-export declare const PUBLIC_ENDPOINT_NAMES: readonly ["getSite", "getContentByPath", "resolveRouteOutcome", "resolveRouteDecision", "listPublishedEntries", "getPublishedEntryPreview", "getPublicFormById", "listPublicForms", "getPublicBookingServices", "getPublicWeeklySlotAvailability", "getPublicChallenge", "listPublicEvents", "batchBlockLoaders", "listPublicTeamMembers", "listPublicProducts", "listPublicPasses", "listPublicMemberships", "resolveEventOccurrence", "checkRedirect", "getRoutableContent", "getPublicRoutableContent", "getPublicSitemapRoutes"];
+export declare const PUBLIC_ENDPOINT_NAMES: readonly ["getSite", "getContentByPath", "resolveRouteOutcome", "resolveRouteDecision", "listPublishedEntries", "getPublishedEntryPreview", "getPublicFormById", "listPublicForms", "getPublicBookingServices", "getPublicWeeklySlotAvailability", "getPublicChallenge", "listPublicEvents", "batchBlockLoaders", "listPublicTeamMembers", "listPublicProducts", "listPublicPasses", "listPublicMemberships", "resolveEventSubroute", "checkRedirect", "getRoutableContent", "getPublicRoutableContent", "getPublicSitemapRoutes"];
 export type ApiClient = <E extends PublicEndpointName>(params: {
     endpoint: E;
     params?: PublicAPIEndpoints[E]['query'];

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

@@ -1,2 +1,46 @@
+import { type ReactElement, type ReactNode } from 'react';
+export type BlockApiAuth = Readonly<{
+    type: 'api-key';
+    key: string;
+}> | Readonly<{
+    type: 'bearer';
+    token: string;
+}> | Readonly<{
+    type: 'none';
+}>;
+export type BlockApiConfig = Readonly<{
+    baseUrl: string;
+    auth: BlockApiAuth;
+    siteId?: string;
+    isPreview?: boolean;
+}>;
+export type NewsletterSubscribeInput = Readonly<{
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    name?: string;
+    company?: string;
+    phone?: string;
+    target: Readonly<{
+        tag: 'published_block_ref';
+        destinationRef: Readonly<{
+            tag: 'block_ref';
+            blockId: string;
+        }>;
+    }>;
+    tags?: string[];
+}>;
+export type NewsletterSubscribeResult = Readonly<{
+    subscribed: boolean;
+    requiresConfirmation?: boolean;
+}>;
+export declare function BlockApiProvider({ config, children, }: Readonly<{
+    config: BlockApiConfig;
+    children: ReactNode;
+}>): ReactElement;
+/** Narrow client contract for custom newsletter override renderers. */
+export declare function useNewsletterBlockApi(): Readonly<{
+    subscribeNewsletter(input: NewsletterSubscribeInput): Promise<NewsletterSubscribeResult>;
+}>;
 export declare const clientComponentRegistry: Record<string, unknown>;
 export { BlocksIslandsHydrator } from './islands/BlocksIslandsHydrator';

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

@@ -20,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, 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 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, IntroContent, LayoutAlign, LayoutWidth, Media, MediaTextAlignment, MediaTextAspectRatio, MediaTextContent, MediaTextImagePosition, NewsletterSignupContent, NewsletterSignupPreset, OfferingsPreviewContent, 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/routing/entrySubroutes.d.ts

@@ -27,7 +27,7 @@ export type ShouldAttemptEntrySubrouteArgs = {
     entryTypeKey: string | null;
     segment: string;
 };
-export type KnownEntrySubrouteKind = 'event-occurrence';
+export type KnownEntrySubrouteKind = 'event-occurrence' | 'event-run';
 /**
  * Parse a path into parent path and last segment.
  * Returns null when no parent/segment split exists.

package/dist/_dts/sdk/src/routing/resolveOccurrence.d.ts

@@ -4,6 +4,7 @@
  * Resolves URL segments like "2025-01-15" or "abc123-uuid" to event occurrence data.
  */
 import type { RiverbankClient, ResolveEventOccurrenceResponse } from '../client/types';
+import type { EventPageSurfaceSubjectRefWire } from '../../../core/src/index';
 import { isISODateString, isUUID, isValidSegment } from './segmentValidators';
 /**
  * Data for a resolved event occurrence
@@ -32,9 +33,9 @@ export type ResolveOccurrenceParams = {
      */
     siteId: string;
     /**
-     * Event series IDs represented by the page authority.
+     * Canonical Event page subject that owns the occurrence.
      */
-    eventSeriesIds: readonly [string, ...string[]];
+    subject: EventPageSurfaceSubjectRefWire;
     /**
      * URL segment to resolve - either a date (YYYY-MM-DD) or UUID
      */
@@ -56,7 +57,7 @@ export type ResolveOccurrenceParams = {
  *   const result = await resolveOccurrence({
  *     client,
  *     siteId: 'your-site-id',
- *     eventSeriesIds: [pageSurface.subject.eventSeriesId],
+ *     subject: pageSurface.subject,
  *     segment: params.occurrence, // e.g., "2025-01-15"
  *   });
  *

package/dist/_dts/sdk/src/routing/resolvePageContent.d.ts

@@ -7,12 +7,16 @@
  * Both SDK and frontend inject their own auth/loaders, but share the same resolution logic.
  */
 import type { ContentTypeRoutingInfo } from './contentTypeResolver';
-import type { ResolveEventOccurrenceResponse } from '../client/types';
+import type { ResolveEventOccurrenceResponse, ResolveEventRunResponse } from '../client/types';
 export type OccurrenceData = NonNullable<ResolveEventOccurrenceResponse['occurrence']>;
-export type EntrySubrouteData = {
+export type EventRunData = NonNullable<ResolveEventRunResponse['run']>;
+export type EntrySubrouteData = Readonly<{
     kind: 'event-occurrence';
     occurrence: OccurrenceData;
-};
+}> | Readonly<{
+    kind: 'event-run';
+    run: EventRunData;
+}>;
 export type PublicLoadStage = 'site_lookup' | 'content_lookup' | 'entry_subroute_lookup' | 'redirect_lookup' | 'content_normalization';
 export type PublicContentLoadError = {
     kind: 'timeout';

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.130.2";
+export declare const SDK_VERSION = "0.134.0";

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

@@ -46,8 +46,8 @@ export declare const accordionSystemSchema: z.ZodObject<{
         elevation: z.ZodEnum<{
             medium: "medium";
             none: "none";
-            high: "high";
             low: "low";
+            high: "high";
         }>;
         softness: z.ZodNullable<z.ZodEnum<{
             crisp: "crisp";
@@ -91,9 +91,9 @@ export declare const accordionSystemSchema: z.ZodObject<{
             body: "body";
         }>>;
         fontScale: z.ZodOptional<z.ZodEnum<{
-            body: "body";
             md: "md";
             lg: "lg";
+            body: "body";
         }>>;
         letterSpacing: z.ZodOptional<z.ZodEnum<{
             tight: "tight";

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

@@ -44,7 +44,7 @@ export type ContextualButtonResolution = Readonly<{
 }> | Readonly<{
     kind: 'repaired';
     requestedRole: VariantRole;
-    candidate: 'surface-outline' | VariantRole;
+    candidate: 'contextual-hover' | 'surface-outline' | VariantRole;
     states: ResolvedButtonColourStates;
     focusIndicator: ResolvedButtonFocusIndicator;
     boundary: Readonly<{

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

@@ -0,0 +1,41 @@
+import { type ButtonColourPalette, type KnownButtonSurface } from './buttonColourContract';
+import { type ContextualButtonHover, type OpaqueButtonColourToken } from './types';
+type ShadeDirection = ContextualButtonHover['fallbackDirection'];
+export type ContextualHoverResolution = Readonly<{
+    kind: 'resolved';
+    token: OpaqueButtonColourToken;
+    direction: ShadeDirection;
+    evidence: 'known-surface' | 'fallback-direction';
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: 'no-distinct-shade' | 'no-text-safe-candidate' | 'no-surface-safe-candidate';
+}>;
+export type ButtonContextualHoverRepair = Readonly<{
+    kind: 'preferred-token-replaced';
+    preferredToken: OpaqueButtonColourToken;
+    contextualToken: OpaqueButtonColourToken;
+}>;
+export type ContextualHoverPreferenceResolution = Readonly<{
+    kind: 'resolved';
+    token: OpaqueButtonColourToken;
+    repair: ButtonContextualHoverRepair | null;
+}> | Extract<ContextualHoverResolution, {
+    kind: 'unavailable';
+}>;
+export declare function resolveContextualHoverPreference(input: Readonly<{
+    instruction: ContextualButtonHover;
+    palette: ButtonColourPalette;
+    surface?: KnownButtonSurface;
+}>): ContextualHoverPreferenceResolution;
+/**
+ * Resolves semantic shade movement from real palette steps. The persisted
+ * instruction owns the colour family and deterministic unknown-surface
+ * fallback; a proven surface may select the opposite direction when it gives
+ * the button stronger separation while retaining the shared contrast contract.
+ */
+export declare function resolveContextualHover(input: Readonly<{
+    instruction: ContextualButtonHover;
+    palette: ButtonColourPalette;
+    surface?: KnownButtonSurface;
+}>): ContextualHoverResolution;
+export {};

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

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

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

@@ -1,4 +1,5 @@
 import type { ButtonGlobalSettings, ButtonVariant, OpaqueButtonColourToken, VariantEffects } from './types';
+import type { ButtonContextualHoverRepair } from './contextualHover';
 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';
@@ -40,10 +41,12 @@ export type ButtonColourContractResult = Readonly<{
     states: ResolvedButtonColourStates;
     focusIndicator: ResolvedButtonFocusIndicator;
     nonColourEffects: VariantEffects;
+    contextualHoverRepair: ButtonContextualHoverRepair | null;
 }> | Readonly<{
     ok: false;
     error: ButtonColourContractError;
 }>;
+export type { ButtonContextualHoverRepair } from './contextualHover';
 export declare function compileButtonColourStates(input: Readonly<{
     variant: ButtonVariant;
     global: ButtonGlobalSettings;

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

@@ -0,0 +1,14 @@
+import type { ButtonColourPalette, KnownButtonSurface } from './buttonColourContract';
+import { type ButtonContextualHoverRepair } from './contextualHover';
+import type { ButtonColourTreatment, ButtonGlobalSettings, ButtonVariant } from './types';
+export type ResolvedButtonHoverTreatment = Readonly<{
+    treatment: ButtonColourTreatment;
+    repair: ButtonContextualHoverRepair | null;
+}>;
+export declare function resolveButtonHoverTreatment(input: Readonly<{
+    variant: ButtonVariant;
+    global: ButtonGlobalSettings;
+    fallback: ButtonColourTreatment;
+    palette: ButtonColourPalette;
+    surface?: KnownButtonSurface;
+}>): ResolvedButtonHoverTreatment;

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

@@ -1,11 +1,11 @@
 import type { z } from 'zod';
 import type { StyleTags } from '../../site-styles/styleTags';
-import type { ButtonGlobalSettings, ButtonSizes, ButtonSurfacePolicy, ButtonSystem, ButtonVariant } from '../types';
+import type { ButtonGlobalSettings, ButtonSizes, ButtonSurfacePolicy, ButtonSystem, ButtonVariant, OpaqueButtonColourToken, VariantRole } from '../types';
 export declare const PUBLIC_BUTTON_ROLES: readonly ["primary", "secondary", "outline", "ghost", "accent"];
-export type PublicButtonRole = (typeof PUBLIC_BUTTON_ROLES)[number];
+export type PublicButtonRole = VariantRole;
 export type CompleteButtonRole = 'primary' | 'secondary';
 export type SupportingButtonRole = Exclude<PublicButtonRole, CompleteButtonRole>;
-export type ButtonVariantAppearance = Readonly<Pick<ButtonVariant, 'background' | 'borderRadius' | 'shadow' | 'border' | 'hoverBackgroundToken' | 'effects' | 'sizes' | 'affordance'>>;
+export type ButtonVariantAppearance = Readonly<Pick<ButtonVariant, 'background' | 'borderRadius' | 'shadow' | 'border' | 'hoverBackgroundToken' | 'contextualHover' | 'effects' | 'sizes' | 'affordance'>>;
 export type PublicButtonVariant<TRole extends PublicButtonRole = PublicButtonRole> = Omit<ButtonVariant, 'id' | 'enabled'> & Readonly<{
     id: TRole;
     enabled: true;
@@ -36,6 +36,23 @@ export type ButtonStyleSystemDefinition = Readonly<{
     surfacePolicy?: ButtonSurfacePolicy;
 }>;
 type StringParameterKey<TParameters> = Extract<keyof TParameters, string>;
+export type ButtonHoverTreatmentValue = 'contextual' | 'secondary' | 'accent';
+type ButtonHoverParameterKey<TParameters> = Extract<{
+    [TKey in keyof TParameters]-?: NonNullable<TParameters[TKey]> extends Partial<Record<VariantRole, ButtonHoverTreatmentValue>> ? TKey : never;
+}[keyof TParameters], string>;
+export type ButtonHoverRoleControl<TParameter extends string = 'hoverPreferences'> = Readonly<{
+    kind: 'button-hover-by-role';
+    parameter: TParameter;
+    label: string;
+    roles: Readonly<Record<VariantRole, Readonly<{
+        contextualSeedToken: OpaqueButtonColourToken;
+        fallbackDirection: 'lighter' | 'darker';
+    }>>>;
+    options: readonly Readonly<{
+        value: ButtonHoverTreatmentValue;
+        label: string;
+    }>[];
+}>;
 export type ButtonStyleControl<TParameters> = {
     [TKey in StringParameterKey<TParameters>]: Readonly<{
         kind: 'choice';
@@ -46,7 +63,7 @@ export type ButtonStyleControl<TParameters> = {
             label: string;
         }>[];
     }>;
-}[StringParameterKey<TParameters>];
+}[StringParameterKey<TParameters>] | (ButtonHoverParameterKey<TParameters> extends never ? never : ButtonHoverRoleControl<ButtonHoverParameterKey<TParameters>>);
 export type ButtonStyleRecipe<TId extends string = string, TParameters = Readonly<Record<string, never>>> = Readonly<{
     id: TId;
     accessibilityLabel: string;

package/dist/_dts/theme-core/src/buttons/styles/recipes/flatInk.d.ts

@@ -0,0 +1,92 @@
+export declare const flatInkRecipe: Readonly<{
+    id: "flat-ink";
+    accessibilityLabel: string;
+    tags: Readonly<Partial<Readonly<{
+        tone: import("../../../../../blocks/src/index").StyleTone;
+        energy: import("../../../../../blocks/src/index").StyleEnergy;
+        motion: import("../../../../../blocks/src/index").StyleMotion;
+        era: import("../../../../../blocks/src/index").StyleEra;
+    }>>>;
+    parameterSchema: import("zod").ZodType<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }, unknown, import("zod/v4/core").$ZodTypeInternals<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }, unknown>>;
+    defaultParameters: {
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    };
+    controls: readonly import("..").ButtonStyleControl<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }>[];
+    defineSystem: (parameters: {
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }) => Readonly<{
+        global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
+        sizes?: import("../..").ButtonSizes;
+        roles: Readonly<{
+            primary: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }>;
+            secondary: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }>;
+            outline: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+            ghost: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+            accent: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+        }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
+    }>;
+}>;