@riverbankcms/sdk 0.111.0 → 0.118.0

package/dist/_dts/sdk/src/contracts/theme.d.ts

@@ -1,21 +1,5 @@
-/**
- * Public SDK theme contracts.
- *
- * The SDK keeps the full theme schema intentionally broad so consumers don't
- * couple to the underlying blocks package, while still exposing the pieces the
- * SDK runtime genuinely reads.
- */
-export type Theme = {
-    header?: {
-        variant?: 'classic' | 'centered' | 'transparent' | 'floating';
-        [key: string]: unknown;
-    };
-    footer?: {
-        mode?: 'default' | 'blocks' | 'default+blocks' | 'none';
-        [key: string]: unknown;
-    };
-    [key: string]: unknown;
-};
+/** The SDK consumes the same canonical theme contract as Riverbank rendering. */
+export type { Theme } from '../../../theme-core/src/index';
 export declare const colorTokens: readonly ["background/base", "background/elevated", "surface/base", "surface/subtle", "surface/inverted", "content/primary", "content/secondary", "accent/primary", "accent/secondary", "border/base"];
 export declare const typographyTokens: readonly ["display/hero", "display/section", "heading/large", "heading/medium", "heading/small", "body/normal", "body/small", "caption"];
 export declare const spacingTokens: readonly ["none", "3xs", "2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl"];

package/dist/_dts/sdk/src/manifest/passes/pass1-fields.d.ts

@@ -21,9 +21,9 @@ export declare const fieldTypeEnum: z.ZodEnum<{
     select: "select";
     link: "link";
     media: "media";
+    repeater: "repeater";
     group: "group";
     richText: "richText";
-    repeater: "repeater";
 }>;
 /**
  * Combined field schema supporting all field types.

package/dist/_dts/sdk/src/manifest/three-pass-converter.d.ts

@@ -10,7 +10,8 @@
  * This approach ensures CSS rules reference classNames that actually exist
  * in the layout by applying patches programmatically between passes.
  */
-import { parseRichTextInlineMarkdown, parseRichTextParagraphInlineMarkdown, type TipTapNode } from '../../../blocks/src/index';
+import { parseRichTextInlineMarkdown, parseRichTextParagraphInlineMarkdown } from '../../../blocks/src/index';
+import { type RichTextDoc } from '../../../blocks/src/system/manifest/richTextSchema';
 import type { HtmlToManifestInput, HtmlToManifestOutput, ConversionResult, ConverterOptions } from './types';
 import { DEFAULT_MANIFEST_MODEL } from './constants';
 export { DEFAULT_MANIFEST_MODEL };
@@ -21,15 +22,14 @@ export { DEFAULT_MANIFEST_MODEL };
  * current paragraph as TipTap hardBreak nodes for line-oriented content such as
  * addresses and opening hours.
  */
-declare function stringToTipTapDoc(text: string): TipTapNode;
+declare function stringToTipTapDoc(text: string): RichTextDoc;
 /**
  * Coerce a richText defaultValue to TipTap format.
  * Handles:
  * - Plain strings → TipTap doc with paragraphs
  * - Already valid TipTap docs → pass through
- * - Legacy { doc: {...} } wrapper → unwrap
  */
-declare function coerceRichTextDefaultValue(value: unknown): TipTapNode | null;
+declare function coerceRichTextDefaultValue(value: unknown): RichTextDoc | null;
 export declare function convertHtmlToManifest(input: HtmlToManifestInput, options: ConverterOptions): Promise<ConversionResult>;
 /**
  * Validate HTML-to-manifest output structure.

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

@@ -5,7 +5,7 @@
  * the SDK's public type surface must remain SDK-owned so consumers don't need
  * to install `@riverbankcms/blocks`.
  */
-import { applyBindings as blocksApplyBindings, applyBindingsToContent as blocksApplyBindingsToContent, normalizeBindingOutput as blocksNormalizeBindingOutput, getPath as blocksGetPath, applyTransform as blocksApplyTransform, extractFirstParagraph as blocksExtractFirstParagraph, isBindingDescriptorLike as blocksIsBindingDescriptorLike, isRecord as blocksIsRecord } from '../../../../blocks/src/bindings/index';
+import { applyBindings as blocksApplyBindings, applyBindingsToContent as blocksApplyBindingsToContent, getPath as blocksGetPath, applyTransform as blocksApplyTransform, extractFirstParagraph as blocksExtractFirstParagraph, isBindingDescriptorLike as blocksIsBindingDescriptorLike, isRecord as blocksIsRecord } from '../../../../blocks/src/bindings/index';
 import type { BindingSource, BindingDescriptor, BindingInput, BindingContext } from '../../contracts';
 export type { BindingSource, BindingDescriptor, BindingInput, BindingMap, BindingContext } from '../../contracts';
 export declare const TRANSFORMS: {
@@ -19,7 +19,6 @@ export declare const isRecord: typeof blocksIsRecord;
 export declare const isBindingDescriptor: (value: unknown) => value is BindingDescriptor;
 export declare const isBindingDescriptorLike: typeof blocksIsBindingDescriptorLike;
 export declare const normalizeBindingInput: (value: BindingInput) => BindingDescriptor | null;
-export declare const normalizeBindingOutput: typeof blocksNormalizeBindingOutput;
 export declare const applyBindings: typeof blocksApplyBindings;
 export declare const applyBindingsToContent: typeof blocksApplyBindingsToContent;
 export declare const resolveBindingValue: (descriptor: BindingDescriptor, context: BindingContext) => unknown;

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

@@ -3,5 +3,5 @@
  */
 export { loadPage } from './loadPage';
 export type { LoadPageParams, LoadPageResult } from './loadPage';
-export { applyBindings, normalizeBindingOutput } from './bindings';
+export { applyBindings } from './bindings';
 export type { BindingContext } from './bindings';

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

@@ -1,4 +1,4 @@
-import type { EventScheduleScope as SystemEventScheduleScope, EventSurfacePreset as SystemEventSurfacePreset } from '../../contracts/system-block-content';
+import type { EventScheduleScope as SystemEventScheduleScope, EventSurfacePreset as SystemEventSurfacePreset, RichTextDoc as SystemRichTextDoc } from '../../contracts/system-block-content';
 import type { PublicTeamMemberSummary } from '../../../../api/src/index';
 import type { BookingFlexibleBalanceConfig, BookingInstalmentPlanConfig, LocationCoordinates, PublicCoursePriceDisplay, PublicEventPriceDisplay, PublicEventPricing, PublicEventPricingType } from '../../../../core/src/index';
 import type { AccordionIslandProps as BlocksAccordionIslandProps, BookingFormConfig as BlocksBookingFormConfig, BookingFormInteractiveIslandProps as BlocksBookingFormIslandProps, BookingFormService as BlocksBookingFormService, CarouselIslandProps as BlocksCarouselIslandProps, CourseRegistrationInteractiveIslandProps as BlocksCourseRegistrationIslandProps, CartDisplay as BlocksCartDisplay, CartInteractiveIslandProps as BlocksCartIslandProps, CartLineDisplay as BlocksCartLineDisplay, CheckoutDisplay as BlocksCheckoutDisplay, CheckoutInteractiveIslandProps as BlocksCheckoutIslandProps, EventCalendarInteractiveIslandProps as BlocksEventCalendarIslandProps, EventCombinedInteractiveIslandProps as BlocksEventCombinedIslandProps, EventDetailsContentEntry as BlocksEventDetailsContentEntry, EventDetailsIslandProps as BlocksEventDetailsIslandProps, EventDetailsOccurrenceContext as BlocksEventDetailsOccurrenceContext, LocationMapIslandProps as BlocksLocationMapIslandProps, EventRegistrationInteractiveIslandProps as BlocksEventRegistrationIslandProps, EventListingDisplay as BlocksEventListingDisplay, EventListingHydration as BlocksEventListingHydration, EventListingInteractiveIslandProps as BlocksEventListingIslandProps, PublicEvent as BlocksPublicEvent, FormInteractiveIslandProps as BlocksFormIslandProps, HeaderSectionIslandProps as BlocksHeaderSectionIslandProps, MembershipCardDisplay as BlocksMembershipCardDisplay, NewsletterFormInteractiveIslandProps as BlocksNewsletterFormIslandProps, PassCardDisplay as BlocksPassCardDisplay, PassesMembershipsDisplay as BlocksPassesMembershipsDisplay, ProductCardDisplay as BlocksProductCardDisplay, ProductDetailDisplay as BlocksProductDetailDisplay, ProductDetailInteractiveIslandProps as BlocksProductDetailIslandProps, ProductListDisplay as BlocksProductListDisplay, ProductListInteractiveIslandProps as BlocksProductListIslandProps, ProductVariantOptionDisplay as BlocksProductVariantOptionDisplay, ShopInteractiveIslandProps as BlocksShopIslandProps } from '../../../../blocks/src/contracts/index';
@@ -49,18 +49,7 @@ export type EventCategory = {
 };
 export type PricingType = PublicEventPricingType;
 export type { PublicCoursePriceDisplay, PublicEventPriceDisplay, PublicEventPricing, };
-export type RichTextDoc = {
-    type: 'doc';
-    content?: Array<{
-        type: string;
-        content?: Array<{
-            type: string;
-            text?: string;
-            [key: string]: unknown;
-        }>;
-        [key: string]: unknown;
-    }>;
-};
+export type RichTextDoc = SystemRichTextDoc;
 export type EventSurfacePreset = SystemEventSurfacePreset;
 export type EventScheduleScope = Exclude<SystemEventScheduleScope, 'any'>;
 export type AccessRestriction = 'none' | 'category';

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

@@ -7,32 +7,3 @@ import type { ZodTypeAny } from 'zod';
 export type { Theme } from '../contracts';
 export declare const themeSchema: ZodTypeAny;
 export { loadLocalTheme, listLocalThemes, type LoadedTheme } from './loader';
-/**
- * Apply a Builder theme to the DOM by injecting CSS variables
- *
- * @param theme - The theme object from Riverbank CMS
- * @param element - The element to apply the theme to (default: document.documentElement)
- *
- * @example
- * ```ts
- * const site = await client.getSite({ slug: 'my-site' });
- * applyTheme(site.theme);
- * ```
- */
-export declare function applyTheme(theme: Record<string, unknown>, element?: HTMLElement): void;
-/**
- * Create a theme object with type-safe defaults
- *
- * @param partial - Partial theme configuration
- * @returns Complete theme object
- *
- * @example
- * ```ts
- * const customTheme = createTheme({
- *   colors: {
- *     primary: '#007bff',
- *   },
- * });
- * ```
- */
-export declare function createTheme(partial?: Record<string, unknown>): Record<string, unknown>;

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

package/dist/_dts/site-commands/src/commands.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type RichTextDoc } from '../../core/src/index';
 import { type BlockRef, type BlocksRef, type CommandRef, type ContentEntryRef, type CourseRef, type PassProductRef, type MembershipProductRef, type BookingCustomerRef, type CustomerPassRef, type CustomerMembershipRef, type AppointmentBookingRef, type CourseEnrollmentRef, type EventRegistrationRef, type PassRedemptionRef, type OrderRef, type EventSeriesRef, type FormRef, type FooterRef, type MediaRef, type NavigationRef, type PageRef, type SiteStyleRef, type StaffRef, type TicketTypeRef, type VenueRef, type EventCategoryRef, type AppointmentServiceRef, type AppointmentResourceRef, type AppointmentAvailabilityRef, type SiteCommandSiteRef } from './refs';
 export declare const navigationLocations: readonly ["main", "header", "footer"];
 export type NavigationLocation = (typeof navigationLocations)[number];
@@ -334,8 +335,8 @@ export declare const applySiteStyleSelectionCommandSchema: z.ZodObject<{
                 }, z.core.$strip>;
                 scale: z.ZodEnum<{
                     compact: "compact";
-                    balanced: "balanced";
                     spacious: "spacious";
+                    balanced: "balanced";
                     minorThird: "minorThird";
                     majorThird: "majorThird";
                     perfectFourth: "perfectFourth";
@@ -618,7 +619,7 @@ export declare const upsertFooterContentCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"upsertFooterContent">;
     ref: z.ZodPipe<z.ZodString, z.ZodTransform<FooterRef, string>>;
     input: z.ZodObject<{
-        bottomText: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        bottomText: z.ZodOptional<z.ZodNullable<z.ZodCustom<RichTextDoc, RichTextDoc>>>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export declare const upsertContentEntryCommandSchema: z.ZodObject<{
@@ -865,8 +866,10 @@ export declare const upsertEventSeriesCommandSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         content: z.ZodOptional<z.ZodObject<{
             summary: z.ZodOptional<z.ZodString>;
-            body: z.ZodOptional<z.ZodUnknown>;
-            image: z.ZodOptional<z.ZodUnknown>;
+            body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+            image: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodString;
+            }, z.core.$catchall<z.ZodUnknown>>>;
             imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
             mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
             contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
@@ -979,8 +982,10 @@ export declare const upsertCourseCommandSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         content: z.ZodOptional<z.ZodObject<{
             summary: z.ZodOptional<z.ZodString>;
-            body: z.ZodOptional<z.ZodUnknown>;
-            image: z.ZodOptional<z.ZodUnknown>;
+            body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+            image: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodString;
+            }, z.core.$catchall<z.ZodUnknown>>>;
             imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
             mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
             contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
@@ -1710,8 +1715,8 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 }, z.core.$strip>;
                 scale: z.ZodEnum<{
                     compact: "compact";
-                    balanced: "balanced";
                     spacious: "spacious";
+                    balanced: "balanced";
                     minorThird: "minorThird";
                     majorThird: "majorThird";
                     perfectFourth: "perfectFourth";
@@ -1941,7 +1946,7 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"upsertFooterContent">;
     ref: z.ZodPipe<z.ZodString, z.ZodTransform<FooterRef, string>>;
     input: z.ZodObject<{
-        bottomText: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        bottomText: z.ZodOptional<z.ZodNullable<z.ZodCustom<RichTextDoc, RichTextDoc>>>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"upsertContentEntry">;
@@ -2191,8 +2196,10 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strict>>>;
         content: z.ZodOptional<z.ZodObject<{
             summary: z.ZodOptional<z.ZodString>;
-            body: z.ZodOptional<z.ZodUnknown>;
-            image: z.ZodOptional<z.ZodUnknown>;
+            body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+            image: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodString;
+            }, z.core.$catchall<z.ZodUnknown>>>;
             imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
             mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
             contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
@@ -2302,8 +2309,10 @@ export declare const siteCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strict>>>;
         content: z.ZodOptional<z.ZodObject<{
             summary: z.ZodOptional<z.ZodString>;
-            body: z.ZodOptional<z.ZodUnknown>;
-            image: z.ZodOptional<z.ZodUnknown>;
+            body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+            image: z.ZodOptional<z.ZodObject<{
+                identifier: z.ZodString;
+            }, z.core.$catchall<z.ZodUnknown>>>;
             imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
             mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
             contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
@@ -2951,8 +2960,8 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
                     }, z.core.$strip>;
                     scale: z.ZodEnum<{
                         compact: "compact";
-                        balanced: "balanced";
                         spacious: "spacious";
+                        balanced: "balanced";
                         minorThird: "minorThird";
                         majorThird: "majorThird";
                         perfectFourth: "perfectFourth";
@@ -3182,7 +3191,7 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
         type: z.ZodLiteral<"upsertFooterContent">;
         ref: z.ZodPipe<z.ZodString, z.ZodTransform<FooterRef, string>>;
         input: z.ZodObject<{
-            bottomText: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            bottomText: z.ZodOptional<z.ZodNullable<z.ZodCustom<RichTextDoc, RichTextDoc>>>;
         }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"upsertContentEntry">;
@@ -3432,8 +3441,10 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             }, z.core.$strict>>>;
             content: z.ZodOptional<z.ZodObject<{
                 summary: z.ZodOptional<z.ZodString>;
-                body: z.ZodOptional<z.ZodUnknown>;
-                image: z.ZodOptional<z.ZodUnknown>;
+                body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+                image: z.ZodOptional<z.ZodObject<{
+                    identifier: z.ZodString;
+                }, z.core.$catchall<z.ZodUnknown>>>;
                 imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
                 mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
                 contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;
@@ -3543,8 +3554,10 @@ export declare const siteCommandBatchSchema: z.ZodObject<{
             }, z.core.$strict>>>;
             content: z.ZodOptional<z.ZodObject<{
                 summary: z.ZodOptional<z.ZodString>;
-                body: z.ZodOptional<z.ZodUnknown>;
-                image: z.ZodOptional<z.ZodUnknown>;
+                body: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<RichTextDoc, RichTextDoc>]>>;
+                image: z.ZodOptional<z.ZodObject<{
+                    identifier: z.ZodString;
+                }, z.core.$catchall<z.ZodUnknown>>>;
                 imageRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>;
                 mediaRefs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<MediaRef, string>>>>>;
                 contentEntryRef: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<ContentEntryRef, string>>>;

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

@@ -3,7 +3,7 @@
  *
  * A button variant may declare a trailing `affordance` icon (see
  * `ButtonVariantAffordance`). The generated button CSS renders that icon as a
- * masked `::after` pseudo-element, so the personality supplies it to every
+ * masked `::after` pseudo-element, so the theme supplies it to every
  * button of the variant without per-node authoring.
  *
  * Icons live in the `@riverbankcms/blocks` registry, but the button CSS is
@@ -11,7 +11,7 @@
  * the *affordance-eligible* icon path data (arrows/chevrons — the action-oriented
  * subset). The `d` values below are duplicated verbatim from the matching entries
  * in `blocks/src/system/icons/svg.tsx`; ids match the registry ids exactly so a
- * node-level `trailingIcon` and a personality `affordance` share one id space.
+ * node-level `trailingIcon` and a theme-owned `affordance` share one id space.
  *
  * Keep this set intentionally tiny. It is not the full CTA icon set — only the
  * shapes that read as a trailing affordance.

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

@@ -15,7 +15,6 @@ export interface ButtonVariantCore {
 export interface ButtonCoreSettings {
     readonly corners: 'square' | 'soft' | 'rounded' | 'pill';
     readonly shadow: 'none' | 'low' | 'medium' | 'high';
-    readonly borderWidth: 'none' | 'thin' | 'medium' | 'thick';
     readonly fontWeight?: number;
     readonly textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
 }

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

@@ -1,4 +1,5 @@
-export type ButtonUnsupportedEffectReason = 'alpha_requires_surface' | 'changes_foreground' | 'changes_border' | 'changes_element_opacity' | 'unresolved_background_overlay' | 'not_button_effect';
+import { type ButtonEffectApplication } from './types';
+export type ButtonUnsupportedEffectReason = 'alpha_requires_surface' | 'changes_foreground' | 'changes_border' | 'changes_shadow_colour' | 'changes_element_opacity' | 'unresolved_background_overlay' | 'not_button_effect';
 export type ButtonEffectPolicy = Readonly<{
     classification: 'colour-transition';
     transition: Readonly<{
@@ -9,6 +10,8 @@ export type ButtonEffectPolicy = Readonly<{
     }>;
 }> | Readonly<{
     classification: 'non-colour';
+}> | Readonly<{
+    classification: 'decorative-colour';
 }> | Readonly<{
     classification: 'unsupported-colour' | 'unsupported-background-overlay' | 'not-button';
     reason: ButtonUnsupportedEffectReason;
@@ -101,22 +104,24 @@ export declare const BUTTON_EFFECT_POLICIES: {
         readonly classification: "non-colour";
     };
     readonly 'border-glow': {
-        readonly classification: "non-colour";
+        readonly classification: "unsupported-colour";
+        readonly reason: "changes_shadow_colour";
     };
     readonly 'drop-shadow': {
-        readonly classification: "non-colour";
+        readonly classification: "decorative-colour";
     };
     readonly 'inner-shadow': {
-        readonly classification: "non-colour";
+        readonly classification: "decorative-colour";
     };
     readonly 'neumorphic-shadow': {
-        readonly classification: "non-colour";
+        readonly classification: "decorative-colour";
     };
     readonly 'outer-glow': {
-        readonly classification: "non-colour";
+        readonly classification: "unsupported-colour";
+        readonly reason: "changes_shadow_colour";
     };
     readonly 'retro-3d-shadow': {
-        readonly classification: "non-colour";
+        readonly classification: "decorative-colour";
     };
     readonly 'scale-up': {
         readonly classification: "non-colour";
@@ -137,11 +142,19 @@ export declare const BUTTON_EFFECT_POLICIES: {
         readonly classification: "non-colour";
     };
     readonly 'sketchy-border': {
-        readonly classification: "non-colour";
+        readonly classification: "decorative-colour";
     };
     readonly 'pulse-animation': {
-        readonly classification: "non-colour";
+        readonly classification: "unsupported-colour";
+        readonly reason: "changes_element_opacity";
     };
 };
+export type ButtonEffectOptionsValidation = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    option: string;
+}>;
+export declare function validateButtonEffectOptions(effect: ButtonEffectApplication): ButtonEffectOptionsValidation;
 export declare function getButtonEffectPolicy(effectId: string): ButtonEffectPolicy | null;
 export declare function classifyButtonEffectId(effectId: string): ButtonEffectClassification;

package/dist/_dts/theme-core/src/buttons/effects/presets/background.d.ts

@@ -20,8 +20,7 @@ export declare const fadeBackgroundEffect: EffectPreset;
 /**
  * Reduce opacity on hover (simple opacity reduction)
  *
- * Works with all background types. Reduces opacity by a percentage (default 15%).
- * This is useful for default button styles that need simple hover feedback.
+ * Navigation-link effect that reduces opacity by a percentage (default 15%).
  */
 export declare const opacityReduceEffect: EffectPreset;
 /**

package/dist/_dts/theme-core/src/buttons/effects/presets/border.d.ts

@@ -8,7 +8,6 @@ export declare const borderColorChangeEffect: EffectPreset;
 /**
  * Sketchy/hand-drawn border effect
  *
- * Creates an imperfect, hand-drawn appearance using multiple shadows,
- * filters, and slight rotation to simulate hand-drawn lines.
+ * Creates an imperfect, hand-drawn appearance using slight rotations.
  */
 export declare const sketchyBorderEffect: EffectPreset;

package/dist/_dts/theme-core/src/buttons/effects/presets/overlay.d.ts

@@ -57,8 +57,10 @@ export declare const animatedGradientBorderFillEffect: EffectPreset;
  * Creates an animated underline that grows from one side on hover.
  * Uses ::after pseudo-element positioned at the bottom of the button.
  *
+ * The underline inherits `currentColor`, so it cannot create a second button
+ * colour authority or drift from the canonical foreground.
+ *
  * Options:
- * - colorToken: Color token for the border (default: neutral-400)
  * - height: Height of the border in pixels (default: 1)
  * - origin: Transform origin - 'left', 'center', or 'right' (default: left)
  */

package/dist/_dts/theme-core/src/buttons/effects/presets/shadow.d.ts

@@ -31,8 +31,8 @@ export declare const neumorphicShadowEffect: EffectPreset;
 /**
  * Outer glow effect
  *
- * Creates an outer glow using box-shadow with no offset.
- * Can be used in base, hover, or active states for retro/neon aesthetics.
+ * Creates an outer glow around a navigation link using box-shadow with no
+ * offset.
  */
 export declare const outerGlowEffect: EffectPreset;
 /**

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

@@ -4,10 +4,10 @@ import type { Theme } from '../../schema';
 import type { InteractiveElementConfig } from '../../interactive/types';
 import type { InteractiveElementType } from '../../interactive/types';
 /**
- * Valid effect preset IDs
+ * Valid generic interactive-effect preset IDs.
  *
- * This union type ensures type safety when referencing effects in button variants.
- * If you add a new effect to the registry, add its ID here.
+ * Button variants deliberately use the narrower `ButtonEffectApplication`
+ * contract from `buttons/types.ts`; this registry also serves navigation.
  */
 export type EffectId = 'darken-background' | 'lighten-background' | 'fade-background' | 'opacity-reduce' | 'animated-gradient' | 'background-on-hover' | 'background-on-hover-alpha' | 'border-glow' | 'drop-shadow' | 'inner-shadow' | 'neumorphic-shadow' | 'outer-glow' | 'retro-3d-shadow' | 'scale-up' | 'scale-down' | 'lift' | 'press-down' | 'pop' | 'aurora-glow' | 'cosmic-stardust' | 'gradient-border-fill' | 'animated-gradient-border-fill' | 'border-bottom-grow' | 'gradient-text' | 'text-color-change' | 'border-color-change' | 'sketchy-border' | 'pulse-animation' | 'nav-underline' | 'nav-frosted-base' | 'nav-frosted-hover' | 'nav-frosted-active';
 /**
@@ -66,9 +66,10 @@ export interface CustomizableOption {
     options?: unknown[];
 }
 /**
- * Effect preset - a reusable CSS generator for button effects
+ * Effect preset - a reusable CSS generator for interactive-element effects.
  *
- * Effect presets are composable building blocks that can be combined to create complex button styles.
+ * The generic registry serves navigation and button emitters. Button persistence
+ * is governed by the closed `ButtonEffectApplication` schema, not this catalog.
  * They must use theme tokens (not hardcoded colors) and declare which category they belong to.
  */
 export interface EffectPreset {
@@ -89,13 +90,13 @@ export interface EffectPreset {
     /**
      * Which interactive element types can use this effect
      *
-     * If undefined, the effect is assumed to work with all element types (backward compatible).
+     * If undefined, the generic emitter supports all interactive element types.
      * Use this to restrict effects that only make sense for certain elements.
      *
      * Examples:
      * - 'button' only: darken-background, lighten-background (require solid background)
      * - 'nav-link' only: nav-underline, nav-frosted
-     * - both: scale-up, border-glow, text-color-change
+     * - both: scale-up
      */
     applicableTo?: InteractiveElementType[];
     /**
@@ -128,14 +129,3 @@ export interface EffectPreset {
      */
     isApplicable?: (buttonConfig: ButtonVariant | InteractiveElementConfig) => boolean;
 }
-/**
- * Reference to an effect preset with customization options
- *
- * This is what's stored in ButtonPreset.effects and ButtonVariant.effects
- */
-export interface EffectReference {
-    /** Effect preset ID (type-safe) */
-    effectId: EffectId;
-    /** User-provided customization options */
-    options?: Record<string, unknown>;
-}

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

@@ -2,8 +2,8 @@ import type { Theme } from '../schema';
 import type { ButtonSystem } from './types';
 /**
  * Class the `button` runtime node adds when it renders its own trailing icon,
- * so a node-level icon suppresses the personality's CSS `::after` affordance
- * (node overrides personality). Shared so generator and renderer can't drift.
+ * so a node-level icon suppresses the theme's CSS `::after` affordance.
+ * Shared so generator and renderer can't drift.
  */
 export declare const AFFORDANCE_SUPPRESS_CLASS = "rb-affordance-off";
 export interface GenerateButtonCssOptions {

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

@@ -3,11 +3,11 @@ import { type ButtonSystem } from './types';
 /**
  * Generate default button system from theme settings.
  *
- * Creates 4 sized variants when theme.buttons is not defined:
- * 1. Primary - primary color background with opacity-reduce hover effect
- * 2. Secondary - neutral-700 background with opacity-reduce hover effect
- * 3. Outline - transparent background with primary border and opacity-reduce hover effect
- * 4. Ghost - transparent background, no border, with opacity-reduce hover effect
+ * Creates 4 sized canonical variants when theme.buttons is not defined:
+ * 1. Primary - solid primary treatment
+ * 2. Secondary - solid neutral treatment
+ * 3. Outline - surface treatment with a border
+ * 4. Ghost - surface treatment without a border
  *
  * All four are sized variants — they inherit padding/fontSize from the theme's
  * `sizes` config (or the system defaults) so they're consistent at any size.

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

@@ -4,6 +4,7 @@
  * Complete button system including types, schemas, presets, and CSS variable generation.
  */
 export * from './types';
+export * from './parseThemeForPersistence';
 export * from './classNames';
 export * from './generateButtonCss';
 export * from './resolveButtonColourStates';
@@ -12,7 +13,3 @@ export * from './generateDefaultButtonSystem';
 export * from './constants';
 export * from './presets';
 export * from './styles';
-export * from './effects/types';
-export * from './effects/registry';
-export * from './effects/presets/transform';
-export * from './core';

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

@@ -0,0 +1,36 @@
+import { type Theme } from '../schema';
+import type { ZodIssue } from 'zod';
+import { type ButtonColourContractError } from './resolveButtonColourStates';
+export type ThemeButtonColourContractError = Readonly<{
+    kind: 'invalid-button-colour-contract';
+    variantId: string;
+    cause: ButtonColourContractError;
+}>;
+export type ThemePersistenceValidationError = Readonly<{
+    kind: 'invalid-theme-schema';
+    issues: readonly ZodIssue[];
+}> | ThemeButtonColourContractError;
+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.
+ */
+export type ValidatedThemeForPersistence = Theme & {
+    readonly [validatedThemeForPersistenceBrand]: true;
+};
+export type ThemeButtonColourContractResult = Readonly<{
+    ok: true;
+    value: ValidatedThemeForPersistence;
+}> | Readonly<{
+    ok: false;
+    error: ThemePersistenceValidationError;
+}>;
+/**
+ * Proves that every persisted button variant compiles against the theme's
+ * concrete palette. Public rendering may still recover from malformed
+ * external/runtime input, but persistence boundaries must reject it.
+ */
+export declare function parseThemeForPersistence(value: unknown): ThemeButtonColourContractResult;
+export {};