@riverbankcms/sdk 0.129.0 → 0.130.0

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,8 +8,10 @@ export * from './parseThemeForPersistence';
 export * from './classNames';
 export * from './generateButtonCss';
 export * from './resolveButtonColourStates';
+export * from './buttonSurfaceContext';
 export * from './affordanceIcons';
 export * from './generateDefaultButtonSystem';
 export * from './constants';
 export * from './presets';
 export * from './styles';
+export { createDefaultButtonStyleSelection } from './styles';

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;

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

@@ -1,12 +1,15 @@
-import type { ResolvedButtonColour, ResolvedButtonFocusIndicator } from './resolveButtonColourStates';
+import type { ButtonVisualState, ResolvedButtonColour, ResolvedButtonFocusIndicator } from './resolveButtonColourStates';
 export type ButtonCssDeclaration = readonly [property: string, value: string];
 /**
  * Canonical colour declaration mapping shared by full themes and ThemeBridge.
  * Both background properties are always emitted so transitions cannot retain
  * a stale gradient or solid layer.
  */
-export declare function resolvedButtonColourDeclarations(colour: ResolvedButtonColour): readonly ButtonCssDeclaration[];
-export declare function resolvedButtonFocusDeclarations(indicator: ResolvedButtonFocusIndicator): readonly ButtonCssDeclaration[];
+export declare function resolvedButtonColourDeclarations(colour: ResolvedButtonColour, action?: Readonly<{
+    role: string;
+    state: ButtonVisualState;
+}>): readonly ButtonCssDeclaration[];
+export declare function resolvedButtonFocusDeclarations(indicator: ResolvedButtonFocusIndicator, role?: string): readonly ButtonCssDeclaration[];
 /**
  * Disabled buttons retain their validated colour pair and add a non-layout
  * visual affordance. `currentColor` keeps the cue inside the same contrast

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

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 import type { StyleTags } from '../../site-styles/styleTags';
-import type { ButtonGlobalSettings, ButtonSizes, ButtonSystem, ButtonVariant } from '../types';
+import type { ButtonGlobalSettings, ButtonSizes, ButtonSurfacePolicy, ButtonSystem, ButtonVariant } from '../types';
 export declare const PUBLIC_BUTTON_ROLES: readonly ["primary", "secondary", "outline", "ghost", "accent"];
 export type PublicButtonRole = (typeof PUBLIC_BUTTON_ROLES)[number];
 export type CompleteButtonRole = 'primary' | 'secondary';
@@ -13,7 +13,7 @@ export type PublicButtonVariant<TRole extends PublicButtonRole = PublicButtonRol
 export type CompleteButtonRoles = Readonly<{
     [TRole in PublicButtonRole]: PublicButtonVariant<TRole>;
 }>;
-type CompleteRoleDefinition<TRole extends PublicButtonRole> = Readonly<{
+type CompleteRoleDefinition = Readonly<{
     kind: 'complete';
     appearance: ButtonVariantAppearance;
 }>;
@@ -23,16 +23,17 @@ type DerivedRoleDefinition = Readonly<{
     overrides?: Partial<ButtonVariantAppearance>;
 }>;
 export type ButtonRoleDefinitions = Readonly<{
-    primary: CompleteRoleDefinition<'primary'>;
-    secondary: CompleteRoleDefinition<'secondary'>;
-    outline: CompleteRoleDefinition<'outline'> | DerivedRoleDefinition;
-    ghost: CompleteRoleDefinition<'ghost'> | DerivedRoleDefinition;
-    accent: CompleteRoleDefinition<'accent'> | DerivedRoleDefinition;
+    primary: CompleteRoleDefinition;
+    secondary: CompleteRoleDefinition;
+    outline: CompleteRoleDefinition | DerivedRoleDefinition;
+    ghost: CompleteRoleDefinition | DerivedRoleDefinition;
+    accent: CompleteRoleDefinition | DerivedRoleDefinition;
 }>;
 export type ButtonStyleSystemDefinition = Readonly<{
     global: ButtonGlobalSettings;
     sizes?: ButtonSizes;
     roles: ButtonRoleDefinitions;
+    surfacePolicy?: ButtonSurfacePolicy;
 }>;
 type StringParameterKey<TParameters> = Extract<keyof TParameters, string>;
 export type ButtonStyleControl<TParameters> = {

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

@@ -63,5 +63,6 @@ export declare const quietArrowRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;

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

@@ -55,6 +55,7 @@ export declare const softPillRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const earthPillRecipe: Readonly<{
@@ -114,6 +115,7 @@ export declare const earthPillRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const confidentChipRecipe: Readonly<{
@@ -173,6 +175,7 @@ export declare const confidentChipRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const editorialLinkRecipe: Readonly<{
@@ -232,6 +235,7 @@ export declare const editorialLinkRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const pebbleRecipe: Readonly<{
@@ -291,6 +295,7 @@ export declare const pebbleRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const brushedWashRecipe: Readonly<{
@@ -350,6 +355,7 @@ export declare const brushedWashRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const inkStampRecipe: Readonly<{
@@ -409,6 +415,7 @@ export declare const inkStampRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const flatInkRecipe: Readonly<{
@@ -468,6 +475,7 @@ export declare const flatInkRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const showtimePillRecipe: Readonly<{
@@ -527,6 +535,7 @@ export declare const showtimePillRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const joyStampRecipe: Readonly<{
@@ -586,6 +595,7 @@ export declare const joyStampRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;
 export declare const ornateRitualRecipe: Readonly<{
@@ -645,5 +655,6 @@ export declare const ornateRitualRecipe: Readonly<{
                 overrides?: Partial<import("..").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
     }>;
 }>;