@riverbankcms/sdk 0.129.1 → 0.130.2

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

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

@@ -4,6 +4,7 @@
  * Pure functions for generating card CSS without requiring the full Theme type.
  * Used by both the full CMS theme system and the SDK theme bridge.
  */
+import type { CardEdgeRule } from './types';
 export type CardBackgroundType = 'solid' | 'transparent' | 'gradient';
 export type CardSpacingCore = 'none' | 'compact' | 'cozy' | 'medium' | 'comfortable' | 'spacious';
 export type CardCornerValueCore = 'square' | 'soft' | 'rounded' | 'pill' | 'expressive';
@@ -15,14 +16,20 @@ export interface CardCornerRadiiCore {
     bottomLeft?: CardCornerValueCore;
     bottomRight?: CardCornerValueCore;
 }
-export interface CardAccentEdgeCore {
-    edge: CardEdgeCore;
-    colorToken: string;
-    width: CardEdgeWidthCore;
-}
 export interface CardVariantCore {
-    /** Unique variant identifier (e.g., 'default', 'elevated') */
+    /** Unique variant identifier (e.g., 'default', 'alternative') */
     id: string;
+    /**
+     * Which card role this variant implements. Generated CSS addresses the
+     * variant by its stable `.card-role-*` alias as well as its id, so content
+     * compiled against the role contract renders on a bridge theme too.
+     */
+    role?: CardRoleCore;
+    /**
+     * Ids this variant used to ship under. They keep emitting their `.card-{id}`
+     * class so SDK sites that address an older variant name keep their surface.
+     */
+    legacyIds?: readonly string[];
     /** Background style */
     background: CardBackgroundType;
     /** Background color token for solid backgrounds */
@@ -41,10 +48,17 @@ export interface CardVariantCore {
     borderToken?: string;
     /** Border width */
     borderWidth?: 'none' | 'thin' | 'medium' | 'thick';
-    /** Single accent edge; replaces the full border when set */
-    accentEdge?: CardAccentEdgeCore;
+    /** Edge rules drawn on the card; coexists with the border */
+    decorations?: CardEdgeRule[];
     /** Per-corner radius override; wins over the global corners setting */
     cornerRadii?: CardCornerRadiiCore;
+    /**
+     * Opts a variant out of the theme's global card shadow. A boxless card has
+     * no box to cast one, so `open` sets it; every other variant inherits the
+     * setting as before. Named for what it does rather than mirroring
+     * `CardVariant.shadow`, which is an object describing a shadow.
+     */
+    suppressShadow?: true;
 }
 export interface CardCoreSettings {
     /** Corner radius style */
@@ -65,8 +79,38 @@ export interface CardCoreSettings {
  * @param settings - Global card settings
  * @returns CSS string
  */
-export declare function generateCardCoreCss(scopeId: string, variants: CardVariantCore[], settings: CardCoreSettings): string;
+export declare function generateCardCoreCss(scopeId: string, variants: CardVariantCore[], settings: CardCoreSettings, scope?: CardClassScope): string;
+/** The roles a bridge card variant can implement. `none` is never a variant. */
+export type CardRoleCore = 'default' | 'alternative' | 'open';
+/**
+ * Which half of a variant's class list to address.
+ *
+ * The split exists because the two halves have different lifecycles on a
+ * bridge theme. `.card-role-*` is the *contract*: compiled content names a
+ * role and expects a surface, so the aliases are emitted unconditionally.
+ * `.card-{id}` and its legacy ids are the *catalogue*: an SDK consumer opts
+ * into those by name through `components.cards`.
+ */
+export type CardClassScope = 'all' | 'role-aliases' | 'named';
+/** Every class a variant's rule is addressed by, within a scope. */
+export declare function cardVariantClasses(variant: CardVariantCore, scope?: CardClassScope): string[];
 /**
- * Get default card variants for SDK usage.
+ * The default card variants for SDK/bridge themes — one per surface-backed
+ * role, so a bridge theme implements the same card contract a site style does
+ * and compiled `_cardStyles.role` renders on it.
+ *
+ * Two of the pre-role trio survive as legacy ids: `.card-elevated` is the
+ * `alternative` card under its old name, and both were the same surface before
+ * the rename. `outlined` is different — a fully bordered box is not what the
+ * `open` role means (boxless but marked), so it keeps its own variant and its
+ * own declarations as a *compatibility class only*. It carries no role, which
+ * means:
+ *
+ * - `.card-outlined` renders exactly what it always did;
+ * - `role: 'open'` renders the boxless marked card on a bridge theme, the same
+ *   thing it renders under a site style;
+ * - naming `outlined` in `components.cards.variants` enables the compatibility
+ *   class and nothing else — it does not publish `.card-role-open`, because
+ *   selecting a legacy name is not a claim on a semantic role.
  */
 export declare function getDefaultCardVariants(): CardVariantCore[];

package/dist/_dts/theme-core/src/cards/decorations.d.ts

@@ -0,0 +1,33 @@
+import type { CardEdgeRule, CardEdgeRuleWidth } from './types';
+/**
+ * Card decoration CSS — the single implementation shared by the Theme-driven
+ * generator (`generateCardCss`) and the dependency-free core generator
+ * (`core.ts`). Both used to carry their own accent-edge emitter; they now
+ * differ only in how a colour token resolves to a CSS colour.
+ */
+/** Resolves a palette token name to a CSS colour value. */
+export type CardColorResolver = (token: string) => string;
+export declare const CARD_EDGE_RULE_WIDTH_MAP: Record<CardEdgeRuleWidth, string>;
+/**
+ * The one short-rule length in the corpus (the editorial-rule accent). A fixed
+ * constant keeps `length: 'short'` a semantic choice rather than a free number.
+ */
+export declare const SHORT_CARD_EDGE_RULE_LENGTH = "2.75rem";
+/** Apply a decoration's optional alpha to its resolved colour. */
+export declare function cardDecorationColor(rule: CardEdgeRule, resolveColor: CardColorResolver): string;
+/**
+ * Container border declarations for a variant's border and its full-length
+ * edge rules. The two are independent: a card may be outlined *and* carry an
+ * accent edge. A variant with edge rules and no border still zeroes the box so
+ * only the decorated sides draw.
+ */
+export declare function cardBorderDeclarations(borderDeclaration: string | null, decorations: readonly CardEdgeRule[] | undefined, resolveColor: CardColorResolver): string[];
+/**
+ * Complete pseudo-element rules for a variant's short edge rules.
+ *
+ * `cardDecorationsSchema` caps the list at two, which makes the two pseudos
+ * sufficient for anything that parsed. The dependency-free core types carry a
+ * plain array with no such cap, so short rules past the second are dropped
+ * here rather than silently overwriting `::after`.
+ */
+export declare function cardDecorationPseudoRules(containerSelectors: readonly string[], decorations: readonly CardEdgeRule[] | undefined, resolveColor: CardColorResolver): string[];

package/dist/_dts/theme-core/src/cards/generateDefaultCardSystem.d.ts

@@ -6,9 +6,14 @@ import type { CardSystem } from './types';
  * Creates the baseline card roles that blocks can request:
  * - `default` for everyday surfaced cards
  * - `alternative` for emphasised cards
+ * - `open` for boxless-but-marked cards
  *
- * Both variants explicitly set theme.shadow and theme.corners for runtime
- * transform access, and both use theme.border when it has meaningful width.
+ * This is the terminal arm of the role fallback chain, so every theme
+ * implements every surface role whether or not its site style defines cards.
+ *
+ * The surfaced variants explicitly set theme.shadow and theme.corners for
+ * runtime transform access, and both use theme.border when it has meaningful
+ * width.
  *
  * This ensures cards have sensible defaults even when theme.cards is undefined.
  *

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

@@ -1,5 +1,8 @@
 export * from './types';
 export * from './constants';
+export * from './decorations';
+export * from './roles';
+export * from './openCardVariant';
 export * from './generateCardCss';
 export * from './generateDefaultCardSystem';
 export * from './core';

package/dist/_dts/theme-core/src/cards/openCardVariant.d.ts

@@ -0,0 +1,24 @@
+import type { CardEdgeRuleWidth, CardVariant } from './types';
+/**
+ * The boxless `open` card, as data.
+ *
+ * Every implementation of the role is the same shape — no fill, no box, square
+ * corners, an inline-flush content edge, a full hairline rule across the top
+ * and a short brand accent sitting on it. This absorbed the legacy
+ * `editorial-rule` treatment class, which Phase 3 deleted; the treatment's
+ * bundled `margin-top: 1rem` is deliberately absent, because outer rhythm is
+ * composition, not card identity. Pinned by `openCardVariant.test.ts`.
+ *
+ * What a site style gets to change is the *marking*: which token the accent
+ * uses and how heavy it is. Anna Raven's grounded-practice style takes her
+ * ochre `accent` where the generated baseline takes `primary`.
+ */
+export declare function boxlessOpenCardVariant(marking: Readonly<{
+    /** Token for the short accent rule riding on the hairline. */
+    accentToken: string;
+    accentWidth: CardEdgeRuleWidth;
+    /** Token for the full-width hairline. Defaults to `border`. */
+    ruleToken?: string;
+    /** Opacity for the hairline, when it should sit back from the border colour. */
+    ruleAlpha?: number;
+}>): CardVariant;

package/dist/_dts/theme-core/src/cards/roles.d.ts

@@ -0,0 +1,38 @@
+import type { Theme } from '../schema';
+import type { CardRole, CardSystem, CardVariant, SurfaceCardRole } from './types';
+/**
+ * Card role resolution — the closed interface between Looks (which say *which
+ * role*) and site styles (which say *what the role looks like*).
+ *
+ * The fallback chain is total, so a Look never has to know which variants a
+ * site style happens to define.
+ */
+/** Where a resolved surface came from. */
+export type CardSurfaceSource = 'site-style' | 'generated-baseline';
+export type ResolvedCardSurface = {
+    kind: 'none';
+    requestedRole: CardRole;
+} | {
+    kind: 'surface';
+    requestedRole: CardRole;
+    /** The role whose variant actually supplied the surface. */
+    resolvedRole: SurfaceCardRole;
+    variant: CardVariant;
+    source: CardSurfaceSource;
+};
+/**
+ * Resolve a card role against a site style's card system.
+ *
+ * - `none` — terminal, no surface.
+ * - `open` — site style's `open` variant → generated baseline `open`.
+ * - `default` — site style's `default` → generated baseline `default`.
+ * - `alternative` — site style's `alternative` → site style's `default` →
+ *   generated baseline `default`.
+ *
+ * The `theme` argument exists solely so the chain can reach the generated
+ * baseline without the caller synthesizing one. Pass `null` for `cardSystem`
+ * when the site style declares none — resolving against a baseline the caller
+ * synthesized would report `source: 'site-style'` for a surface no site style
+ * chose.
+ */
+export declare function resolveCardRole(theme: Theme, cardSystem: CardSystem | null, role: CardRole): ResolvedCardSurface;