@riverbankcms/sdk 0.104.3 → 0.108.0

package/dist/_dts/preview-next/src/client/preview/StyleConfigurator.d.ts

@@ -2,10 +2,10 @@ import React from 'react';
 import type { ApiClient } from '../../../../api/src/request';
 import type { Theme } from '../../../../blocks/src/index';
 import { type ButtonPersonalityId } from '../../../../theme-core/src/buttons/index';
-import { type CuratedPaletteId, type PaletteOverrides, type RuntimePaletteState } from '../../../../theme-core/src/palette/index';
-import { type FooterSelectionContext, type FooterLookId, type HeaderLayoutId, type HeaderLookId, type HeaderSelectionContext, type HeaderStyleId, type TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
+import { type FooterSelectionContext, type FooterLookId, type HeaderLayoutId, type HeaderLookId, type HeaderSelectionContext, type HeaderStyleId } from '../../../../theme-core/src/site-styles/index';
 import { type VisibleSiteStyleAccess } from './siteStyleAccess';
 import type { PreviewDesignRow } from './sidebarTabPreference';
+import type { PreviewRuntimePaletteState } from './styleConfiguratorSnapshot';
 export type StyleConfiguratorProps = Readonly<{
     siteId: string;
     apiClient: ApiClient;
@@ -19,14 +19,9 @@ export type StyleConfiguratorProps = Readonly<{
         selectionVersion?: number | null;
         selectionUpdatedAt?: string | null;
         buttonPersonalityId: ButtonPersonalityId | null;
-        runtimePaletteState?: RuntimePaletteState | null;
-        paletteVariantId?: CuratedPaletteId | null;
-        paletteOverrides?: PaletteOverrides | null;
+        runtimePaletteState: PreviewRuntimePaletteState;
         headerLayoutId?: HeaderLayoutId | null;
         headerStyleId?: HeaderStyleId | null;
-        typographyPresetId?: TypographyPresetId | null;
-        typographyBodyFontOverride?: string | null;
-        typographyHeadingFontOverride?: string | null;
         headerLookId?: HeaderLookId | null;
         footerLookId?: FooterLookId | null;
     }> & Readonly<Record<string, unknown>>;
@@ -37,6 +32,7 @@ export type StyleConfiguratorProps = Readonly<{
         id: number;
         row: PreviewDesignRow;
     }> | null;
+    onFocusedSurfaceChange?: (focused: boolean) => void;
     siteStyleAccess: VisibleSiteStyleAccess;
 }>;
-export declare function StyleConfigurator({ siteId, apiClient, theme, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, expandedRowRequest, siteStyleAccess, }: StyleConfiguratorProps): React.JSX.Element;
+export declare function StyleConfigurator({ siteId, apiClient, theme, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, expandedRowRequest, onFocusedSurfaceChange, siteStyleAccess, }: StyleConfiguratorProps): React.JSX.Element;

package/dist/_dts/preview-next/src/client/preview/StyleConfigurator.state.d.ts

@@ -12,8 +12,8 @@
  */
 import type { ButtonPersonalityId } from '../../../../theme-core/src/buttons/index';
 import type { Theme } from '../../../../blocks/src/index';
-import type { CuratedPaletteId, PaletteColors, PaletteMode, RuntimePaletteState, SitePaletteId, SitePaletteVersion } from '../../../../theme-core/src/palette/index';
-import { type FooterLookId, type HeaderLayoutId, type HeaderLookId, type HeaderStyleId, type TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
+import type { PaletteColors, PaletteMode, PaletteSelection, PaletteEditorState, KnownCuratedPaletteValueKey, ResolvedPaletteSelection, RuntimePaletteState, SitePalette, SitePaletteId, SitePaletteVersion, PaletteLibraryAuthority } from '../../../../theme-core/src/palette/index';
+import { type FooterLookId, type HeaderLayoutId, type HeaderLookId, type HeaderStyleId } from '../../../../theme-core/src/site-styles/index';
 import type { SelectionFallbackWarning, SiteStyleId } from '../../../../theme-core/src/site-styles/previewCompiler';
 import { type EditorStagedSessionCapabilities, type EditorStagedSessionState } from '../../../../content-editor/src/editorTransactionState';
 export type StyleConfiguratorSaveStatus = Readonly<{
@@ -25,6 +25,7 @@ export type StyleConfiguratorSaveStatus = Readonly<{
 }> | Readonly<{
     kind: 'failed';
     message: string;
+    failureKind: 'retryable' | 'stale';
 }>;
 export type StyleConfiguratorExpandedRow = 'style' | 'header-layout' | 'header-style' | 'footer-layout' | 'footer' | 'buttons' | 'typography' | 'palette' | 'colours' | null;
 /**
@@ -37,20 +38,6 @@ export type StyleConfiguratorNotice = never;
 type ThemeTypography = Theme['typography'];
 type BodyTypography = ThemeTypography['body'];
 type HeadingTypography = ThemeTypography['headings']['default'];
-export type TypographySelectionSnapshot = Readonly<{
-    kind: 'preset';
-    presetId: TypographyPresetId | null;
-    bodyFontOverride: string | null;
-    headingFontOverride: string | null;
-}> | Readonly<{
-    kind: 'custom';
-    typography: ThemeTypography;
-}>;
-export type TypographySelectionFlatFields = Readonly<{
-    typographyPresetId: TypographyPresetId | null;
-    typographyBodyFontOverride: string | null;
-    typographyHeadingFontOverride: string | null;
-}>;
 export type TypographyDraftPatch = Readonly<{
     kind: 'heading';
     patch: Partial<HeadingTypography>;
@@ -61,24 +48,41 @@ export type TypographyDraftPatch = Readonly<{
     kind: 'scale';
     scale: ThemeTypography['scale'];
 }>;
+/** Runtime authority is deliberately separate from the editable core state. */
 export type PaletteSelectionSnapshot = Readonly<{
-    kind: 'migrated-curated';
-    paletteId: CuratedPaletteId;
+    kind: 'available';
+    editor: PaletteEditorState;
+}> | Readonly<{
+    kind: 'invalid';
+    reason: PaletteAuthorityError;
+}>;
+export type PaletteAuthorityError = Extract<RuntimePaletteState, {
+    kind: 'invalid';
+}>['reason'] | 'runtime-curated-palette-missing' | 'runtime-curated-palette-mismatch' | 'invalid-active-site-palette-version';
+/** Read-only UI projection. It intentionally owns no palette transitions. */
+export type PalettePreviewProjection = Readonly<{
+    kind: 'curated';
+    valueKey: KnownCuratedPaletteValueKey;
+    colors: PaletteColors;
+    mode: PaletteMode;
+}> | Readonly<{
+    kind: 'curated-fork';
+    sourceValueKey: KnownCuratedPaletteValueKey;
     colors: PaletteColors;
     mode: PaletteMode;
 }> | Readonly<{
-    kind: 'migrated-site';
+    kind: 'site';
     paletteId: SitePaletteId;
     colors: PaletteColors;
     mode: PaletteMode;
     version: SitePaletteVersion;
 }> | Readonly<{
-    kind: 'legacy-unmigrated';
+    kind: 'new-site';
     colors: PaletteColors;
     mode: PaletteMode;
 }> | Readonly<{
     kind: 'invalid';
-    reason: string;
+    reason: PaletteAuthorityError;
 }>;
 export type SelectionSnapshot = Readonly<{
     siteStyleId: SiteStyleId;
@@ -90,7 +94,7 @@ export type SelectionSnapshot = Readonly<{
     footerLookId: FooterLookId | null;
     buttonPersonalityId: ButtonPersonalityId;
     palette: PaletteSelectionSnapshot;
-    typographySelection: TypographySelectionSnapshot;
+    typography: ThemeTypography;
 }>;
 type StyleConfiguratorTargetKey = 'design:site-style';
 export type StyleConfiguratorHistoryEntry = Readonly<{
@@ -100,6 +104,22 @@ export type StyleConfiguratorHistoryEntry = Readonly<{
     next: SelectionSnapshot;
 }>;
 export type StyleConfiguratorStagedSession = EditorStagedSessionState<SelectionSnapshot, StyleConfiguratorHistoryEntry, StyleConfiguratorTargetKey>;
+/**
+ * A collaborator selected a different active palette while this editor had an
+ * unsaved edit to the formerly active site palette. The base remains the
+ * server authority; the complete local draft remains available for an
+ * intentional retry or cancel.
+ */
+export type StyleConfiguratorStalePaletteConflict = Readonly<{
+    kind: 'active-palette-changed';
+    originalPaletteId: SitePaletteId;
+    localDraft: Readonly<{
+        paletteId: SitePaletteId;
+        expectedVersion: SitePaletteVersion;
+        colors: PaletteColors;
+        mode: PaletteMode;
+    }>;
+}>;
 export type StyleConfiguratorState = Readonly<{
     /**
      * Last persisted server snapshot. Updated on apply-success (and on
@@ -114,10 +134,7 @@ export type StyleConfiguratorState = Readonly<{
     saveStatus: StyleConfiguratorSaveStatus;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
     notices: ReadonlyArray<StyleConfiguratorNotice>;
-    paletteDrafts: Readonly<Partial<Record<CuratedPaletteId, Readonly<{
-        colors: PaletteColors;
-        mode: PaletteMode;
-    }>>>>;
+    stalePaletteConflict: StyleConfiguratorStalePaletteConflict | null;
     expandedRow: StyleConfiguratorExpandedRow;
     stagedSession: StyleConfiguratorStagedSession;
 }>;
@@ -144,33 +161,39 @@ export declare function previewButtonPersonality(state: StyleConfiguratorState,
 export declare function previewHeaderLayout(state: StyleConfiguratorState, headerLayoutId: HeaderLayoutId): StyleConfiguratorState;
 export declare function previewHeaderStyle(state: StyleConfiguratorState, headerStyleId: HeaderStyleId): StyleConfiguratorState;
 export declare function previewFooterLook(state: StyleConfiguratorState, footerLookId: FooterLookId | null): StyleConfiguratorState;
-export declare function previewTypographyPreset(state: StyleConfiguratorState, typographyPresetId: TypographyPresetId): StyleConfiguratorState;
-export declare function setCustomTypography(state: StyleConfiguratorState, typography: ThemeTypography): StyleConfiguratorState;
+export declare function previewTypography(state: StyleConfiguratorState, typography: ThemeTypography): StyleConfiguratorState;
 export declare function applyTypographyDraftPatch(state: StyleConfiguratorState, currentTypography: ThemeTypography, patch: TypographyDraftPatch): StyleConfiguratorState;
 export declare function resetTypographyToSaved(state: StyleConfiguratorState): StyleConfiguratorState;
-export declare function previewCuratedPalette(state: StyleConfiguratorState, palette: Readonly<{
-    paletteId: CuratedPaletteId;
+export declare function previewCuratedPalette(state: StyleConfiguratorState, valueKey: KnownCuratedPaletteValueKey): StyleConfiguratorState;
+export declare function previewSitePalette(state: StyleConfiguratorState, palette: Readonly<{
+    paletteId: SitePaletteId;
     colors: PaletteColors;
     mode: PaletteMode;
+    version: SitePaletteVersion;
 }>): StyleConfiguratorState;
+/** Starts a manual palette from the active complete palette, never sparse overrides. */
+export declare function createPalette(state: StyleConfiguratorState): StyleConfiguratorState;
 export declare function setPaletteColors(state: StyleConfiguratorState, colors: PaletteColors): StyleConfiguratorState;
 /**
  * Records the post-compile resolved selection + any fallback warnings.
  * Used after `compileSiteThemeFromSelections` runs against a new site style:
  * the resolver may have auto-picked a different personality if the user's
  * previous selection is not offered for the new style, or a different palette
- * if the persisted palette ID is no longer known.
+ * if the persisted palette value key is no longer known.
  *
  */
 export declare function applyResolvedSelections(state: StyleConfiguratorState, input: Readonly<{
-    resolved: Pick<SelectionSnapshot, 'buttonPersonalityId' | 'headerLayoutId' | 'headerStyleId' | 'headerLookId'> & TypographySelectionFlatFields;
-    typographySelection?: TypographySelectionSnapshot;
+    resolved: Pick<SelectionSnapshot, 'buttonPersonalityId' | 'headerLayoutId' | 'headerStyleId' | 'headerLookId' | 'typography'>;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
 }>): StyleConfiguratorState;
 export declare function cancelPreview(state: StyleConfiguratorState): StyleConfiguratorState;
 export declare function markApplySaving(state: StyleConfiguratorState): StyleConfiguratorState;
 export declare function markApplySaved(state: StyleConfiguratorState, persisted: SelectionSnapshot): StyleConfiguratorState;
 export declare function markApplyFailed(state: StyleConfiguratorState, message: string, failureKind?: 'retryable' | 'stale'): StyleConfiguratorState;
+/** Advances a stale site's CAS token only for the user's explicit retry. */
+export declare function prepareStalePaletteRetry(state: StyleConfiguratorState, input?: Readonly<{
+    sitePalettes: readonly SitePalette[];
+}>): StyleConfiguratorState;
 export declare function toggleRow(state: StyleConfiguratorState, row: StyleConfiguratorExpandedRow): StyleConfiguratorState;
 export declare function dismissWarnings(state: StyleConfiguratorState): StyleConfiguratorState;
 export declare function dismissNotices(state: StyleConfiguratorState): StyleConfiguratorState;
@@ -180,16 +203,31 @@ export declare function dismissNotices(state: StyleConfiguratorState): StyleConf
  * changes the persisted selection out-of-band.
  */
 export declare function syncStyleConfiguratorState(state: StyleConfiguratorState, base: SelectionSnapshot): StyleConfiguratorState;
+/** Reconciles typed palette-library authority with the editor's saved base. */
+export declare function reconcilePaletteLibraryActive(state: StyleConfiguratorState, active: PaletteLibraryAuthority, sitePalettes: readonly SitePalette[]): StyleConfiguratorState;
+/**
+ * A palette-library response only refreshes palette authority. Unlike a full
+ * server snapshot, it must never discard the user's staged site-style work.
+ * Site drafts keep their complete local colours/mode and rebase their expected
+ * version when the same palette was changed elsewhere.
+ */
+export declare function rebasePaletteLibraryAuthority(state: StyleConfiguratorState, committedPalette: ResolvedPaletteSelection): StyleConfiguratorState;
 export declare function selectionSnapshotsEqual(a: SelectionSnapshot, b: SelectionSnapshot): boolean;
-export declare function typographySelectionSnapshotFromFlat(input: Readonly<{
-    typographyPresetId?: TypographyPresetId | null;
-    typographyBodyFontOverride?: string | null;
-    typographyHeadingFontOverride?: string | null;
-    theme?: Theme | null;
-}>): TypographySelectionSnapshot;
-export declare function typographySelectionFlatFields(selection: TypographySelectionSnapshot): TypographySelectionFlatFields;
-export declare function customTypographyForSelection(selection: TypographySelectionSnapshot): ThemeTypography | null;
-export declare function typographySelectionsEqual(a: TypographySelectionSnapshot, b: TypographySelectionSnapshot): boolean;
-export declare function paletteSelectionSnapshotFromRuntime(runtime: RuntimePaletteState | null | undefined): PaletteSelectionSnapshot;
+type ModernRuntimePaletteState = Extract<RuntimePaletteState, Readonly<{
+    authority: 'curated';
+}>> | Extract<RuntimePaletteState, Readonly<{
+    authority: 'site';
+}>> | Extract<RuntimePaletteState, Readonly<{
+    kind: 'invalid';
+}>>;
+export declare function paletteSelectionSnapshotFromRuntime(runtime: ModernRuntimePaletteState): PaletteSelectionSnapshot;
+export declare function paletteSelectionSnapshotFromComplete(input: Readonly<{
+    selection: PaletteSelection;
+    colors: PaletteColors;
+    mode: PaletteMode;
+    version?: SitePaletteVersion;
+}>): PaletteSelectionSnapshot;
 export declare function paletteSelectionSnapshotsEqual(left: PaletteSelectionSnapshot, right: PaletteSelectionSnapshot): boolean;
+export declare function palettePreviewProjection(palette: PaletteSelectionSnapshot): PalettePreviewProjection;
+export declare function committedPaletteForSnapshot(palette: PaletteSelectionSnapshot): ResolvedPaletteSelection | null;
 export {};

package/dist/_dts/preview-next/src/client/preview/StyleConfigurator.typography.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import type { ApiClient } from '../../../../api/src/request';
+import type { Theme } from '../../../../blocks/src/index';
+import { type GoogleFontRecord, type SiteFontRecord, type TypographyFontSlot } from './typographyFontCatalog';
+type ThemeTypography = Theme['typography'];
+type BodyTypography = ThemeTypography['body'];
+type HeadingTypography = ThemeTypography['headings']['default'];
+type CatalogResource<T> = Readonly<{
+    kind: 'idle';
+    value: T;
+}> | Readonly<{
+    kind: 'loading';
+    value: T;
+}> | Readonly<{
+    kind: 'loaded';
+    value: T;
+}> | Readonly<{
+    kind: 'failed';
+    value: T;
+    message: string;
+}>;
+export type TypographyFontCatalogState = Readonly<{
+    google: CatalogResource<readonly GoogleFontRecord[]>;
+    site: CatalogResource<readonly SiteFontRecord[]>;
+}>;
+export type TypographyEditorSurface = Readonly<{
+    kind: 'overview';
+}> | Readonly<{
+    kind: 'font-picker';
+    slot: TypographyFontSlot;
+}> | Readonly<{
+    kind: 'advanced';
+}>;
+export declare const typographyOverviewSurface: TypographyEditorSurface;
+export declare function useTypographyFontCatalog(apiClient: ApiClient, siteId: string, enabled: boolean): TypographyFontCatalogState;
+export declare function TypographyOverviewContent({ typography, catalog, onChooseFont, onOpenAdvanced, onReset, disabled, }: Readonly<{
+    typography: ThemeTypography;
+    catalog: TypographyFontCatalogState;
+    onChooseFont: (slot: TypographyFontSlot) => void;
+    onOpenAdvanced: () => void;
+    onReset: () => void;
+    disabled?: boolean;
+}>): React.JSX.Element;
+export declare function TypographyFontPickerTakeover({ slot, value, catalog, onBack, onChange, disabled, }: Readonly<{
+    slot: TypographyFontSlot;
+    value: string;
+    catalog: TypographyFontCatalogState;
+    onBack: () => void;
+    onChange: (family: string) => void;
+    disabled?: boolean;
+}>): React.JSX.Element;
+export declare function TypographyAdvancedTakeover({ typography, catalog, onBack, onHeadingChange, onBodyChange, onScaleChange, disabled, }: Readonly<{
+    typography: ThemeTypography;
+    catalog: TypographyFontCatalogState;
+    onBack: () => void;
+    onHeadingChange: (patch: Partial<HeadingTypography>) => void;
+    onBodyChange: (patch: Partial<BodyTypography>) => void;
+    onScaleChange: (scale: ThemeTypography['scale']) => void;
+    disabled?: boolean;
+}>): React.JSX.Element;
+export {};

package/dist/_dts/preview-next/src/client/preview/previewErrorMessages.d.ts

@@ -0,0 +1,4 @@
+export declare const PREVIEW_DESIGN_SAVE_ERROR_MESSAGE = "We couldn\u2019t save that change just now. Please try again in a minute or two.";
+export declare const PREVIEW_DESIGN_REFRESH_ERROR_MESSAGE = "We couldn\u2019t refresh the latest design just now. Your changes are still here. Please try again in a minute or two.";
+export declare const PREVIEW_DESIGN_LOAD_ERROR_MESSAGE = "We couldn\u2019t load those design options just now. Please try again in a minute or two.";
+export declare function reportPreviewDesignError(operation: string, error: unknown): void;

package/dist/_dts/preview-next/src/client/preview/siteStylePreviewPlanner.d.ts

@@ -1,14 +1,14 @@
 import type { Theme } from '../../../../blocks/src/index';
 import type { ButtonPersonalityId } from '../../../../theme-core/src/buttons/index';
-import { type CuratedPaletteId } from '../../../../theme-core/src/palette/index';
-import type { FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId, TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
-import { type CuratedSiteStyle, type CompiledTypographySelection, type SelectionFallbackWarning, type SiteStyleId } from '../../../../theme-core/src/site-styles/previewCompiler';
-import type { PaletteSelectionSnapshot, TypographySelectionSnapshot } from './StyleConfigurator.state';
+import { type CompleteResolvedPaletteSelection } from '../../../../theme-core/src/palette/index';
+import type { FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId } from '../../../../theme-core/src/site-styles/index';
+import { compileSiteThemeFromSelections, type CuratedSiteStyle, type SelectionFallbackWarning, type SiteStyleId } from '../../../../theme-core/src/site-styles/previewCompiler';
+import type { PaletteSelectionSnapshot } from './StyleConfigurator.state';
 export type SiteStylePreviewSelection = Readonly<{
     siteStyleId: SiteStyleId;
     buttonPersonalityId: ButtonPersonalityId;
     palette: PaletteSelectionSnapshot;
-    typographySelection?: TypographySelectionSnapshot;
+    typography: Theme['typography'];
     headerLayoutId?: HeaderLayoutId | null;
     headerStyleId?: HeaderStyleId | null;
     headerLookId: HeaderLookId | null;
@@ -20,18 +20,7 @@ export type SiteStyleChromePreviewSelection = Readonly<{
 }>;
 export type SiteStylePreviewPlan = Readonly<{
     themeOverlay: Theme;
-    resolvedSelections: Readonly<{
-        buttonPersonalityId: ButtonPersonalityId;
-        paletteVariantId: CuratedPaletteId;
-        typographySelection: CompiledTypographySelection['resolvedSelection'];
-        typographyPresetId: TypographyPresetId | null;
-        typographyBodyFontOverride: string | null;
-        typographyHeadingFontOverride: string | null;
-        headerLayoutId: HeaderLayoutId;
-        headerStyleId: HeaderStyleId;
-        headerLookId: HeaderLookId | null;
-        footerLookId: FooterLookId;
-    }>;
+    resolvedSelections: ReturnType<typeof compileSiteThemeFromSelections>['resolvedSelections'];
     chromeSelection: SiteStyleChromePreviewSelection;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
 }>;
@@ -43,3 +32,4 @@ export type SiteStylePreviewPlanInput = Readonly<{
     footerSelectionContext?: Partial<FooterSelectionContext>;
 }>;
 export declare function planSiteStylePreviewChange(input: SiteStylePreviewPlanInput): SiteStylePreviewPlan;
+export declare function resolvedPaletteForPreview(palette: PaletteSelectionSnapshot, siteStyle: CuratedSiteStyle): CompleteResolvedPaletteSelection;

package/dist/_dts/preview-next/src/client/preview/styleConfiguratorSnapshot.d.ts

@@ -1,28 +1,35 @@
 import type { Theme } from '../../../../blocks/src/index';
 import type { ButtonPersonalityId } from '../../../../theme-core/src/buttons/index';
-import { type CuratedPaletteId, type PaletteOverrides, type RuntimePaletteState } from '../../../../theme-core/src/palette/index';
-import type { FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId, TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
+import { type RuntimePaletteState } from '../../../../theme-core/src/palette/index';
+import type { FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId } from '../../../../theme-core/src/site-styles/index';
 import type { SelectionSnapshot } from './StyleConfigurator.state';
+export type PreviewRuntimePaletteState = Extract<RuntimePaletteState, Readonly<{
+    authority: 'curated';
+}>> | Extract<RuntimePaletteState, Readonly<{
+    authority: 'site';
+}>> | Extract<RuntimePaletteState, Readonly<{
+    kind: 'invalid';
+}>>;
 type StyleConfiguratorSnapshotInput = Readonly<{
     theme?: Theme | null;
     initialSelections: Readonly<{
         selectionVersion?: number | null;
         selectionUpdatedAt?: string | null;
         buttonPersonalityId: ButtonPersonalityId | null;
-        runtimePaletteState?: RuntimePaletteState | null;
-        paletteVariantId?: CuratedPaletteId | null;
-        paletteOverrides?: PaletteOverrides | null;
+        runtimePaletteState: PreviewRuntimePaletteState;
         headerLayoutId?: HeaderLayoutId | null;
         headerStyleId?: HeaderStyleId | null;
-        typographyPresetId?: TypographyPresetId | null;
-        typographyBodyFontOverride?: string | null;
-        typographyHeadingFontOverride?: string | null;
         headerLookId?: HeaderLookId | null;
         footerLookId?: FooterLookId | null;
     }>;
     headerSelectionContext?: Partial<HeaderSelectionContext>;
     footerSelectionContext?: Partial<FooterSelectionContext>;
 }>;
+/**
+ * Preview only accepts the modern, server-resolved palette runtime state. The
+ * old Theme-plus-overrides reconstruction belongs to migration tooling, never
+ * to a live editor where it could silently overwrite authoritative state.
+ */
 export declare function resolveStyleConfiguratorInitialSnapshot(input: Readonly<{
     theme?: Theme | null;
     initialSelections: StyleConfiguratorSnapshotInput['initialSelections'];

package/dist/_dts/preview-next/src/client/preview/typographyFontCatalog.d.ts

@@ -0,0 +1,57 @@
+import type { APIEndpoints } from '../../../../api/src/index';
+export type GoogleFontRecord = NonNullable<APIEndpoints['listFonts']['response']>[number];
+export type SiteFontRecord = NonNullable<APIEndpoints['listSiteFonts']['response']>['fonts'][number];
+export type TypographyFontCategory = 'all' | 'sans-serif' | 'serif' | 'display' | 'handwriting' | 'monospace';
+export type TypographyFontSlot = 'body' | 'heading';
+export type TypographyFontOption = Readonly<{
+    source: 'site';
+    family: string;
+    label: string;
+    category: Exclude<TypographyFontCategory, 'all'> | null;
+    siteFont: SiteFontRecord;
+}> | Readonly<{
+    source: 'google';
+    family: string;
+    label: string;
+    category: Exclude<TypographyFontCategory, 'all'> | null;
+    googleFont: GoogleFontRecord;
+}>;
+export declare const TYPOGRAPHY_INITIAL_GOOGLE_FONT_COUNT = 24;
+export declare const typographyFontCategories: readonly [{
+    readonly value: "all";
+    readonly label: "All";
+}, {
+    readonly value: "sans-serif";
+    readonly label: "Sans";
+}, {
+    readonly value: "serif";
+    readonly label: "Serif";
+}, {
+    readonly value: "display";
+    readonly label: "Display";
+}, {
+    readonly value: "handwriting";
+    readonly label: "Handwriting";
+}, {
+    readonly value: "monospace";
+    readonly label: "Mono";
+}];
+export declare function buildTypographyFontCatalog(input: Readonly<{
+    googleFonts: readonly GoogleFontRecord[];
+    siteFonts: readonly SiteFontRecord[];
+    query: string;
+    category: TypographyFontCategory;
+}>): Readonly<{
+    site: readonly TypographyFontOption[];
+    google: readonly TypographyFontOption[];
+}>;
+export declare function visibleTypographyFontOptions(input: Readonly<{
+    options: readonly TypographyFontOption[];
+    selectedFamily: string;
+    limit: number;
+}>): readonly TypographyFontOption[];
+export declare function fontOptionForFamily(family: string, catalog: Readonly<{
+    googleFonts: readonly GoogleFontRecord[];
+    siteFonts: readonly SiteFontRecord[];
+}>): TypographyFontOption | null;
+export declare function primaryFontFamily(cssFamily: string): string;

package/dist/_dts/sdk/src/cli/commands/pull.d.ts

@@ -27,7 +27,7 @@ export declare function entryBaseSnapshotTargetForPull(input: Readonly<{
  * then remove canonical/owner-managed entry types before diffing or writing.
  */
 export declare function pullAllContentWithCanonicalEntryPolicy(client: ManagementClient, output: OutputContext): Promise<PulledContent>;
-export declare function createScopedPullContent(meta: PulledContent['meta'], overrides: Partial<Omit<PulledContent, 'meta'>>): PulledContent;
+export declare function createScopedPullContent(meta: Omit<PulledContent['meta'], 'truncation'> & Partial<Pick<PulledContent['meta'], 'truncation'>>, overrides: Partial<Omit<PulledContent, 'meta'>>): PulledContent;
 /**
  * Determines whether the pull command should prompt for overwrite confirmation.
  * Scoped pulls (e.g., `pull entries blog-post`) only modify their target subdirectory,

package/dist/_dts/sdk/src/cli/commands/push/execute/theme.d.ts

@@ -1,12 +1,9 @@
 import type { OutputContext } from '../../../output';
 import type { Theme } from '../../../../contracts';
+import type { ThemeUpsertUpdateInput } from '../../../../client/management/types';
 export type ThemePushClient = {
     theme: {
-        upsert: (params: {
-            theme: Theme;
-            themeId?: string;
-            selectionId?: string;
-        }) => Promise<{
+        upsert: (params: ThemeUpsertUpdateInput) => Promise<{
             themeId: string;
             selectionId: string;
             savedAt: string;
@@ -33,7 +30,7 @@ export declare function pushThemeAndUpdateMeta(params: {
     client: ThemePushClient;
     contentDir: string;
     themeName: string;
-    theme: Theme;
+    theme: ThemeUpsertUpdateInput['theme'];
     existingMeta?: ThemeMetaEntry;
     readThemesMeta: (contentDir: string) => Promise<ThemesMetaFile | null>;
     writeThemesMeta: (contentDir: string, data: ThemesMetaFile) => Promise<void>;
@@ -66,7 +63,7 @@ export declare function handleThemePushForAllScope(params: {
     themeSchema: {
         safeParse: (value: unknown) => {
             success: true;
-            data?: unknown;
+            data: ThemeUpsertUpdateInput['theme'];
         } | {
             success: false;
             error: {

package/dist/_dts/sdk/src/cli/commands/style.d.ts

@@ -5,22 +5,29 @@
  */
 import { Command } from 'commander';
 import { type CuratedSiteStyle } from '../../../../theme-core/src/site-styles/index';
-import type { ThemeStyleSelectionApplyInput } from '../../client/management';
-export type StyleApplyOptions = Readonly<{
+import type { ManagementClient, ThemeStyleSelectionApplyInput } from '../../client/management';
+import { type SiteStyleSelectionApplyCommand } from '../../client/management';
+import type { OutputContext } from '../output';
+type StyleSelectionOptions = Readonly<{
     siteStyleId: string;
-    baseSelectionVersion: string;
-    selectionId?: string;
     buttonPersonalityId?: string;
-    paletteVariantId?: string;
-    paletteOverrides?: string;
-    typographyPresetId?: string;
-    typographyBodyFontOverride?: string;
-    typographyHeadingFontOverride?: string;
+    paletteCommand?: string;
+    typography?: string;
     headerLookId?: string;
     headerLayoutId?: string;
     headerStyleId?: string;
     footerLookId?: string;
 }>;
+export type StyleApplyOptions = StyleSelectionOptions & Readonly<{
+    baseSelectionVersion: string;
+    selectionId?: string;
+}>;
+export type StyleInitOptions = StyleSelectionOptions;
+export type StyleInitCommandDeps = Readonly<{
+    upsertTheme: ManagementClient['theme']['upsert'];
+    info: OutputContext['info'];
+    success: OutputContext['success'];
+}>;
 export type StyleCatalogListOptions = Readonly<{
     siteStyleId?: string;
 }>;
@@ -33,13 +40,20 @@ export type StyleCatalogListRow = Readonly<{
     name: string;
     palettes: readonly StyleCatalogChoice[];
     buttonPersonalities: readonly StyleCatalogChoice[];
-    typographyPresets: readonly StyleCatalogChoice[];
+    typography: Readonly<{
+        body: string;
+        heading: string;
+    }>;
     headerLayouts: readonly StyleCatalogChoice[];
     headerStyles: readonly StyleCatalogChoice[];
     headerLooks: readonly StyleCatalogChoice[];
     footerLooks: readonly StyleCatalogChoice[];
 }>;
 export declare function buildStyleSelectionApplyInputFromOptions(options: StyleApplyOptions): ThemeStyleSelectionApplyInput;
+/** Builds the complete first-theme command without reading current selection state. */
+export declare function buildStyleSelectionInitializeCommandFromOptions(options: StyleInitOptions): SiteStyleSelectionApplyCommand;
 export declare function buildStyleCatalogListRows(styles?: readonly CuratedSiteStyle[], options?: StyleCatalogListOptions): readonly StyleCatalogListRow[];
 export declare function formatStyleCatalogListRow(row: StyleCatalogListRow): string[];
+export declare function executeStyleInitWithDeps(deps: StyleInitCommandDeps, options: StyleInitOptions): Promise<void>;
 export declare const styleCommand: Command;
+export {};

package/dist/_dts/sdk/src/cli/content/reader.d.ts

@@ -62,6 +62,7 @@ export interface LocalNavigationMenu {
     name: string;
     isPrimary?: boolean;
     isFooter?: boolean;
+    footerRole?: 'main' | 'legal-policy' | null;
     items: LocalNavigationItem[];
 }
 export interface LocalNavigation {

package/dist/_dts/sdk/src/cli/site-commands/oneOffCommands.d.ts

@@ -1,5 +1,5 @@
 import { type Result, type SiteId } from '../../../../core/src/index';
-import type { ManagementBlock, ManagementClient, ManagementEntry, ManagementNavigationMenu, ManagementPage, NavigationItemInput } from '../../client/management/types';
+import type { ManagementBlock, ManagementClient, ManagementNavigationMenu, ManagementPage, NavigationItemInput, UpsertedManagementEntry } from '../../client/management/types';
 import type { EnvTarget } from '../helpers';
 import { type CliCommandCompileBatchSuccessWithReports, type CliCommandValidationCompileError } from './commandRuntime';
 import { type EntryCommandReportSubject, type EntrySiteCommand, type EntrySiteCommandType } from './entryCommands';
@@ -73,8 +73,8 @@ export declare function executeOneOffNavigationCommand<TResult>(input: Readonly<
     client: Pick<ManagementClient, 'navigation'>;
     apply: (command: NavigationSiteCommand, client: Pick<ManagementClient, 'navigation'>) => Promise<TResult>;
 }>): Promise<TResult>;
-export declare function applyOneOffEntryCommand(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<ManagementEntry | void>;
-export declare function applyOneOffEntryCommandReturningEntry(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<ManagementEntry>;
+export declare function applyOneOffEntryCommand(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<UpsertedManagementEntry | void>;
+export declare function applyOneOffEntryCommandReturningEntry(command: EntrySiteCommand, client: Pick<ManagementClient, 'entries'>): Promise<UpsertedManagementEntry>;
 export declare function applyOneOffPageCommand(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementPage | ManagementBlock | void>;
 export declare function applyOneOffPageCommandReturningPage(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementPage>;
 export declare function applyOneOffPageCommandReturningBlock(command: PageSiteCommand, client: Pick<ManagementClient, 'pages' | 'blocks'>): Promise<ManagementBlock>;

package/dist/_dts/sdk/src/cli/sync/media.d.ts

@@ -13,6 +13,7 @@
  *
  * No path rewriting in content data is needed since paths are relative!
  */
+import { type StoragePathParseError } from '../../../../media-core/src/index';
 /**
  * Extract all unique storagePath values from content data.
  * Recursively walks through objects and arrays to find all media references.
@@ -30,7 +31,20 @@ export declare function extractMediaIdentifiers(data: unknown): Set<string>;
  * @param siteId - The site ID context for relative paths
  * @param bucket - Storage bucket name (default: "media")
  */
-export declare function buildStorageUrl(supabaseUrl: string, storagePath: string, siteId: string, bucket?: string): string;
+export type MediaStorageUrlBuildError = Readonly<{
+    tag: 'invalid_storage_path';
+    siteId: string;
+    storagePath: string;
+    cause: StoragePathParseError;
+}>;
+export type MediaStorageUrlBuildResult = Readonly<{
+    ok: true;
+    value: string;
+}> | Readonly<{
+    ok: false;
+    error: MediaStorageUrlBuildError;
+}>;
+export declare function buildStorageUrl(supabaseUrl: string, storagePath: string, siteId: string, bucket?: string): MediaStorageUrlBuildResult;
 /**
  * Check if a file path is an image that can be transformed by Supabase.
  * @param path - The file path or storage path
@@ -48,7 +62,7 @@ export declare function isTransformableImage(path: string): boolean;
 export declare function buildImageTransformUrl(supabaseUrl: string, storagePath: string, siteId: string, options?: {
     width?: number;
     quality?: number;
-}): string;
+}): MediaStorageUrlBuildResult;
 /**
  * Download a file from a public Supabase storage URL.
  * Returns the file data as a Buffer, or null if download fails after retries.