@riverbankcms/sdk 0.129.1 → 0.130.0

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;

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;
     }>;
 }>;

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

@@ -58,6 +58,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "earth-pill";
@@ -116,6 +117,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "confident-chip";
@@ -174,6 +176,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "editorial-link";
@@ -232,6 +235,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "pebble";
@@ -290,6 +294,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "ink-stamp";
@@ -348,6 +353,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "flat-ink";
@@ -406,6 +412,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "brushed-wash";
@@ -464,6 +471,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "showtime-pill";
@@ -522,6 +530,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "joy-stamp";
@@ -580,6 +589,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "ornate-ritual";
@@ -638,6 +648,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>, Readonly<{
     id: "quiet-arrow";
@@ -704,6 +715,7 @@ export declare const buttonStyleRecipes: readonly [Readonly<{
                 overrides?: Partial<import("./domain").ButtonVariantAppearance>;
             }>;
         }>;
+        surfacePolicy?: import("..").ButtonSurfacePolicy;
     }>;
 }>];
 export type RegisteredButtonStyleRecipe = (typeof buttonStyleRecipes)[number];

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

@@ -60,6 +60,11 @@ export declare const DEFAULT_BUTTON_STYLE_SELECTION: {
 };
 export declare function createDefaultButtonStyleSelection(styleId: ButtonStyleId): ButtonStyleSelection;
 export declare function isButtonStyleId(value: string): value is ButtonStyleId;
+export type PersistedButtonStyleSelectionResult = Readonly<{
+    selection: ButtonStyleSelection;
+    warning: 'invalid-persisted-button-style-selection' | null;
+}>;
+export declare function parsePersistedButtonStyleSelection(value: unknown, fallback?: ButtonStyleSelection): PersistedButtonStyleSelectionResult;
 /**
  * Stable identity for a validated style selection. Parsing first canonicalises
  * parameter key order, so future recipe parameters do not require editor-core

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

@@ -6,9 +6,9 @@ import { type ThemeColorToken } from '../tokens/themeColorTokens';
  * Defines the type-safe configuration for site button styles.
  */
 export type Shadow = {
-    elevation: "none" | "low" | "medium" | "high";
-    softness: "crisp" | "soft" | "hard" | null;
-    position: "bottom" | "bottom-right";
+    elevation: 'none' | 'low' | 'medium' | 'high';
+    softness: 'crisp' | 'soft' | 'hard' | null;
+    position: 'bottom' | 'bottom-right';
     /**
      * Optional palette token for the shadow colour. When omitted the shadow
      * falls back to the historical neutral black (`rgb(0 0 0 / …)`), so existing
@@ -105,7 +105,11 @@ export type ButtonColourTreatment = {
     colorToken: OpaqueButtonColourToken;
 } | {
     type: 'gradient';
-    stops: [OpaqueButtonColourToken, OpaqueButtonColourToken, ...OpaqueButtonColourToken[]];
+    stops: [
+        OpaqueButtonColourToken,
+        OpaqueButtonColourToken,
+        ...OpaqueButtonColourToken[]
+    ];
     direction: GradientDirection;
     foregroundToken: OpaqueButtonColourToken;
 } | {
@@ -313,6 +317,35 @@ export declare const variantRoleSchema: z.ZodEnum<{
     secondary: "secondary";
     ghost: "ghost";
 }>;
+export declare const buttonSurfaceFallbackSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"surface-outline">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"variant">;
+    role: z.ZodEnum<{
+        outline: "outline";
+        accent: "accent";
+        primary: "primary";
+        secondary: "secondary";
+        ghost: "ghost";
+    }>;
+}, z.core.$strict>], "kind">;
+export type ButtonSurfaceFallback = z.infer<typeof buttonSurfaceFallbackSchema>;
+export type ButtonSurfacePolicy = Record<VariantRole, ButtonSurfaceFallback[]>;
+type ReadonlyButtonSurfacePolicy = Readonly<Record<VariantRole, readonly ButtonSurfaceFallback[]>>;
+export declare const STANDARD_BUTTON_SURFACE_POLICY: ReadonlyButtonSurfacePolicy;
+export declare function createStandardButtonSurfacePolicy(): ButtonSurfacePolicy;
+export declare const buttonSurfacePolicySchema: z.ZodObject<Record<"outline" | "accent" | "primary" | "secondary" | "ghost", z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"surface-outline">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"variant">;
+    role: z.ZodEnum<{
+        outline: "outline";
+        accent: "accent";
+        primary: "primary";
+        secondary: "secondary";
+        ghost: "ghost";
+    }>;
+}, z.core.$strict>], "kind">>>, z.core.$strict>;
 export declare const buttonSizeNameSchema: z.ZodEnum<{
     sm: "sm";
     md: "md";
@@ -2240,6 +2273,18 @@ export declare const buttonSystemSchema: z.ZodObject<{
             fontSize?: string | undefined;
         } | undefined;
     }>>>;
+    surfacePolicy: z.ZodOptional<z.ZodObject<Record<"outline" | "accent" | "primary" | "secondary" | "ghost", z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"surface-outline">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"variant">;
+        role: z.ZodEnum<{
+            outline: "outline";
+            accent: "accent";
+            primary: "primary";
+            secondary: "secondary";
+            ghost: "ghost";
+        }>;
+    }, z.core.$strict>], "kind">>>, z.core.$strict>>;
 }, z.core.$strict>;
 export type Priority = 1 | 2 | 3;
 interface ButtonGlobalSettingsBase {
@@ -2315,5 +2360,7 @@ export interface ButtonSystem {
     global: ButtonGlobalSettings;
     variants: ButtonVariant[];
     sizes?: ButtonSizes;
+    /** Optional only for pre-policy in-memory fixtures; persistence canonicalizes it. */
+    surfacePolicy?: ButtonSurfacePolicy;
 }
 export {};