@riverbankcms/sdk 0.80.0 → 0.82.0

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

@@ -1,12 +1,56 @@
-import { type ReactNode } from 'react';
-import type { ApiClient } from '../../../../api/src/request';
+import React, { type ReactNode } 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 { PaletteOverrides, PaletteVariantId } from '../../../../theme-core/src/palette/index';
-import type { FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId, TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
+import type { BrandDisplayMode, FooterLookId, FooterSelectionContext, HeaderLayoutId, HeaderLookId, HeaderSelectionContext, HeaderStyleId, LogoSizePolicy, SiteChromeBackgroundColorToken, SiteChromeBackgroundOverride, TypographyPresetId } from '../../../../theme-core/src/site-styles/index';
+import { type StyleConfiguratorHistoryEntry } from './StyleConfigurator.state';
 import type { SiteStyleAccess } from './siteStyleAccess';
 import { type SiteChromeLookOption } from './siteChromeLookRows';
 import type { SiteChromeEditableSurfaceKind } from './SiteChromeEditableSurface';
+import { type HeaderBrandDisplayOption, type HeaderLogoSizeOption } from './siteChromeBrandPreferences';
+import { type SiteStyleHistoryFailure, type SiteStyleHistorySkipReason } from './siteStyleHistoryState';
+import { type SiteChromeQuickControlHistoryFailure, type SiteChromeQuickControlHistorySkipReason } from './siteChromeQuickControlHistoryState';
+type SiteStyleHistoryController = Readonly<{
+    recordAppliedSelection: (entry: StyleConfiguratorHistoryEntry) => void;
+    setStagedPreviewActive: (active: boolean) => void;
+    undo: () => Promise<SiteStyleHistoryApplyOutcome>;
+    redo: () => Promise<SiteStyleHistoryApplyOutcome>;
+    canUndo: boolean;
+    canRedo: boolean;
+    isHistoryPending: boolean;
+    isHistoryStale: boolean;
+    historyFailure: string | null;
+    hasActiveStagedPreview: boolean;
+}>;
+type SiteStyleHistoryApplyOutcome = Readonly<{
+    kind: 'saved';
+}> | Readonly<{
+    kind: 'skipped';
+    reason: SiteStyleHistorySkipReason | 'not-ready' | 'staged-preview-active';
+}> | SiteStyleHistoryFailure;
+type SiteChromeQuickControlHistoryController = Readonly<{
+    undo: () => Promise<SiteChromeQuickControlApplyOutcome>;
+    redo: () => Promise<SiteChromeQuickControlApplyOutcome>;
+    canUndo: boolean;
+    canRedo: boolean;
+    isHistoryPending: boolean;
+    isHistoryStale: boolean;
+    historyFailure: string | null;
+}>;
+type SiteChromeQuickControlApplyOutcome = Readonly<{
+    kind: 'saved';
+}> | Readonly<{
+    kind: 'skipped';
+    reason: SiteChromeQuickControlHistorySkipReason | 'superseded';
+}> | SiteChromeQuickControlHistoryFailure;
+export type SiteChromeBackgroundControlState = Readonly<{
+    available: boolean;
+    current: SiteChromeBackgroundOverride;
+    currentLabel: string;
+    quickTokens: readonly SiteChromeBackgroundColorToken[];
+    advancedTokens: readonly SiteChromeBackgroundColorToken[];
+}>;
 type SiteChromeCustomizeSurfaceState = Readonly<{
     kind: 'unavailable';
 }> | Readonly<{
@@ -19,8 +63,12 @@ type SiteChromeCustomizeSurfaceState = Readonly<{
     currentId: HeaderStyleId;
     currentLabel: string;
     options: readonly SiteChromeLookOption<HeaderStyleId>[];
+    brandDisplay: BrandDisplayMode;
+    brandDisplayOptions: readonly HeaderBrandDisplayOption[];
+    logoSize: LogoSizePolicy;
+    logoSizeOptions: readonly HeaderLogoSizeOption[];
     diagnostics: readonly string[];
-    saving: boolean;
+    background: SiteChromeBackgroundControlState;
     failure: string | null;
     applyAllowed: boolean;
 }> | Readonly<{
@@ -31,7 +79,7 @@ type SiteChromeCustomizeSurfaceState = Readonly<{
     currentLabel: string;
     options: readonly SiteChromeLookOption<FooterLookId | null>[];
     diagnostics: readonly string[];
-    saving: boolean;
+    background: SiteChromeBackgroundControlState;
     failure: string | null;
     applyAllowed: boolean;
 }>;
@@ -39,6 +87,12 @@ type SiteChromeCustomizeContextValue = Readonly<{
     getSurfaceState: (surface: SiteChromeEditableSurfaceKind) => SiteChromeCustomizeSurfaceState;
     cycleSurfaceLook: (surface: SiteChromeEditableSurfaceKind, direction: 'prev' | 'next') => void;
     cycleSurfaceLayout: (surface: SiteChromeEditableSurfaceKind, direction: 'prev' | 'next') => void;
+    setHeaderBrandDisplay: (value: BrandDisplayMode) => void;
+    setHeaderLogoSize: (value: LogoSizePolicy) => void;
+    cycleSurfaceBackground: (surface: SiteChromeEditableSurfaceKind, direction: 'prev' | 'next') => void;
+    chooseSurfaceBackground: (surface: SiteChromeEditableSurfaceKind, override: SiteChromeBackgroundOverride) => void;
+    siteStyleHistory: SiteStyleHistoryController;
+    quickControlHistory: SiteChromeQuickControlHistoryController;
 }>;
 export type SiteChromeCustomizeProviderProps = Readonly<{
     children: ReactNode;
@@ -67,6 +121,6 @@ export type SiteChromeCustomizeProviderProps = Readonly<{
     footerSelectionContext?: Partial<FooterSelectionContext>;
     siteStyleAccess?: SiteStyleAccess;
 }>;
-export declare function SiteChromeCustomizeProvider({ children, siteId, apiClient, theme, themeId, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, siteStyleAccess, }: SiteChromeCustomizeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SiteChromeCustomizeProvider({ children, siteId, apiClient, theme, themeId, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, siteStyleAccess, }: SiteChromeCustomizeProviderProps): React.JSX.Element;
 export declare function useSiteChromeCustomizeOptional(): SiteChromeCustomizeContextValue | null;
 export {};

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

@@ -1,3 +1,4 @@
+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';
@@ -37,4 +38,4 @@ export type StyleConfiguratorProps = Readonly<{
     }> | null;
     siteStyleAccess: VisibleSiteStyleAccess;
 }>;
-export declare function StyleConfigurator({ siteId, apiClient, theme, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, expandedRowRequest, siteStyleAccess, }: StyleConfiguratorProps): import("react/jsx-runtime").JSX.Element;
+export declare function StyleConfigurator({ siteId, apiClient, theme, selectionId, selectionVersion, selectionUpdatedAt, initialSelections, headerSelectionContext, footerSelectionContext, expandedRowRequest, siteStyleAccess, }: StyleConfiguratorProps): React.JSX.Element;

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

@@ -14,6 +14,7 @@ import type { ButtonPersonalityId } from '../../../../theme-core/src/buttons/ind
 import type { PaletteOverrides, PaletteVariantId } 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 { SelectionFallbackWarning, SiteStyleId } from '../../../../theme-core/src/site-styles/previewCompiler';
+import { type EditorStagedSessionCapabilities, type EditorStagedSessionState } from '../../../../content-editor/src/editorTransactionState';
 export type StyleConfiguratorSaveStatus = Readonly<{
     kind: 'idle';
 }> | Readonly<{
@@ -52,6 +53,14 @@ export type SelectionSnapshot = Readonly<{
     typographyHeadingFontOverride: string | null;
 }>;
 type PaletteOverrideDrafts = Readonly<Partial<Record<PaletteVariantId, PaletteOverrides>>>;
+type StyleConfiguratorTargetKey = 'design:site-style';
+export type StyleConfiguratorHistoryEntry = Readonly<{
+    kind: 'site-style-design';
+    label: string;
+    previous: SelectionSnapshot;
+    next: SelectionSnapshot;
+}>;
+export type StyleConfiguratorStagedSession = EditorStagedSessionState<SelectionSnapshot, StyleConfiguratorHistoryEntry, StyleConfiguratorTargetKey>;
 export type StyleConfiguratorState = Readonly<{
     /**
      * Last persisted server snapshot. Updated on apply-success (and on
@@ -68,6 +77,7 @@ export type StyleConfiguratorState = Readonly<{
     notices: ReadonlyArray<StyleConfiguratorNotice>;
     paletteOverrideDrafts: PaletteOverrideDrafts;
     expandedRow: StyleConfiguratorExpandedRow;
+    stagedSession: StyleConfiguratorStagedSession;
 }>;
 export declare function createStyleConfiguratorState(base: SelectionSnapshot): StyleConfiguratorState;
 export declare function openRow(state: StyleConfiguratorState, row: Exclude<StyleConfiguratorExpandedRow, null>): StyleConfiguratorState;
@@ -77,6 +87,8 @@ export declare function openRow(state: StyleConfiguratorState, row: Exclude<Styl
  * `setOverrideTheme` call.
  */
 export declare function isPreviewingChange(state: StyleConfiguratorState): boolean;
+export declare function deriveStyleConfiguratorCapabilities(state: StyleConfiguratorState): EditorStagedSessionCapabilities;
+export declare function styleConfiguratorHistoryEntryForPersistedSelection(state: StyleConfiguratorState, persisted: SelectionSnapshot): StyleConfiguratorHistoryEntry | null;
 export declare function previewSiteStyle(state: StyleConfiguratorState, siteStyleId: SiteStyleId): StyleConfiguratorState;
 export declare function previewButtonPersonality(state: StyleConfiguratorState, buttonPersonalityId: ButtonPersonalityId): StyleConfiguratorState;
 export declare function previewHeaderLayout(state: StyleConfiguratorState, headerLayoutId: HeaderLayoutId): StyleConfiguratorState;
@@ -106,7 +118,7 @@ export declare function applyResolvedSelections(state: StyleConfiguratorState, i
 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): StyleConfiguratorState;
+export declare function markApplyFailed(state: StyleConfiguratorState, message: string, failureKind?: 'retryable' | 'stale'): StyleConfiguratorState;
 export declare function toggleRow(state: StyleConfiguratorState, row: StyleConfiguratorExpandedRow): StyleConfiguratorState;
 export declare function dismissWarnings(state: StyleConfiguratorState): StyleConfiguratorState;
 export declare function dismissNotices(state: StyleConfiguratorState): StyleConfiguratorState;
@@ -116,5 +128,6 @@ export declare function dismissNotices(state: StyleConfiguratorState): StyleConf
  * changes the persisted selection out-of-band.
  */
 export declare function syncStyleConfiguratorState(state: StyleConfiguratorState, base: SelectionSnapshot): StyleConfiguratorState;
+export declare function selectionSnapshotsEqual(a: SelectionSnapshot, b: SelectionSnapshot): boolean;
 export declare function paletteOverridesEqual(a: PaletteOverrides | null, b: PaletteOverrides | null): boolean;
 export {};

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

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { SubrouteNoticeModel } from './subrouteNotice';
 type SubrouteNoticeProps = {
     model: SubrouteNoticeModel;
@@ -9,5 +10,5 @@ type SubrouteNoticeProps = {
  * Render-only — all wording and the CTA target are produced by
  * {@link resolveSubrouteNotice}.
  */
-export declare function SubrouteNotice({ model }: SubrouteNoticeProps): import("react/jsx-runtime").JSX.Element;
+export declare function SubrouteNotice({ model }: SubrouteNoticeProps): React.JSX.Element;
 export {};

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

@@ -0,0 +1,9 @@
+import type { LinkedContentEditTarget, PreviewLinkedEntryFieldBinding } from '../../../../blocks/src/system/data/index';
+export declare const LINKED_ENTRY_EDIT_EVENT: "riverbank:preview:linked-entry-edit";
+export declare const LINKED_ENTRY_FIELD_FOCUS_EVENT: "riverbank:preview:linked-entry-field-focus";
+export type LinkedEntryEditEvent = CustomEvent<LinkedContentEditTarget>;
+export type LinkedEntryFieldFocusEvent = CustomEvent<PreviewLinkedEntryFieldBinding>;
+export declare function dispatchLinkedEntryEditEvent(target: LinkedContentEditTarget): void;
+export declare function dispatchLinkedEntryFieldFocusEvent(binding: PreviewLinkedEntryFieldBinding): void;
+export declare function isLinkedEntryEditEvent(event: Event): event is LinkedEntryEditEvent;
+export declare function isLinkedEntryFieldFocusEvent(event: Event): event is LinkedEntryFieldFocusEvent;

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

@@ -0,0 +1,51 @@
+import type { BlockItem } from '../../../../editor-blocks/src/index';
+export declare const PREVIEW_CHROME_EDGE_OFFSET_PX = 8;
+export declare const DEFAULT_PREVIEW_CHROME_FLOATING_PLACEMENT: PreviewChromeFloatingPlacement;
+export type HeaderClearance = Readonly<{
+    kind: 'none';
+}> | Readonly<{
+    kind: 'overlay';
+    px: number;
+}>;
+export type PreviewChromeAnchorBox = Readonly<{
+    top: number;
+    right: number;
+    bottom: number;
+    height: number;
+}>;
+export type PreviewChromeFloatingPlacement = Readonly<{
+    kind: 'anchor-top-right';
+    topPx: number;
+    rightPx: number;
+}> | Readonly<{
+    kind: 'anchor-top-right-clamped';
+    topPx: number;
+    rightPx: number;
+    minTopPx: number;
+}> | Readonly<{
+    kind: 'viewport-top-right';
+    topPx: number;
+    rightPx: number;
+}>;
+export type PreviewChromeFloatingPosition = Readonly<{
+    topPx: number;
+    rightPx: number;
+}>;
+export declare function headerClearanceFromPx(px: number): HeaderClearance;
+export declare function findFirstEditableContentBlockIndex(blocks: readonly Pick<BlockItem, 'kind'>[]): number | null;
+export declare function blockReceivesHeaderClearance(blocks: readonly Pick<BlockItem, 'kind'>[], blockIndex: number): boolean;
+export declare function planBlockToolbarPlacement(input: Readonly<{
+    blocks: readonly Pick<BlockItem, 'kind'>[];
+    blockIndex: number;
+    headerClearance: HeaderClearance;
+}>): PreviewChromeFloatingPlacement;
+export declare function planSiteChromeCustomizePlacement(input: Readonly<{
+    surface: 'header' | 'footer';
+    anchorBox: PreviewChromeAnchorBox | null;
+}>): PreviewChromeFloatingPlacement;
+export declare function resolvePreviewChromeFloatingPosition(input: Readonly<{
+    anchorBox: PreviewChromeAnchorBox | null;
+    containerTopEdgePx?: number;
+    containerRightEdgePx: number;
+    placement: PreviewChromeFloatingPlacement;
+}>): PreviewChromeFloatingPosition;

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

@@ -0,0 +1,68 @@
+import React, { type KeyboardEvent, type MouseEvent, type ReactNode, type Ref } from 'react';
+export type CustomizeControlUnavailableReason = 'single-option' | 'preview-only';
+export type CustomizeControlAvailability = Readonly<{
+    kind: 'available';
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: CustomizeControlUnavailableReason;
+}>;
+export type CustomizeCycleAvailabilityInput = Readonly<{
+    kind: 'available';
+}> | Readonly<{
+    kind: CustomizeControlUnavailableReason;
+}>;
+export type CustomizePopoverController = Readonly<{
+    open: boolean;
+    close: () => void;
+    toggle: (event: MouseEvent<HTMLElement>) => void;
+    buttonRef: Ref<HTMLButtonElement>;
+    panelId: string;
+    descriptionId: string;
+    dialogRef: Ref<HTMLDivElement>;
+    registerInitialFocus: Ref<HTMLButtonElement>;
+    handleDialogKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+}>;
+export declare function useCustomizePopoverController(): CustomizePopoverController;
+export type CustomizePillButtonProps = Readonly<{
+    buttonRef: Ref<HTMLButtonElement>;
+    ariaLabel: string;
+    open: boolean;
+    controlsId: string;
+    onClick: (event: MouseEvent<HTMLButtonElement>) => void;
+    disabled?: boolean;
+}>;
+export declare function CustomizePillButton({ buttonRef, ariaLabel, open, controlsId, onClick, disabled, }: CustomizePillButtonProps): React.JSX.Element;
+export type CustomizePopoverShellProps = Readonly<{
+    panelId: string;
+    descriptionId: string;
+    dialogLabel: string;
+    eyebrow: string;
+    title: string;
+    dialogRef: Ref<HTMLDivElement>;
+    closeButtonRef: Ref<HTMLButtonElement>;
+    onClose: () => void;
+    onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    spacing?: 'normal' | 'compact';
+    children: ReactNode;
+}>;
+export declare function CustomizePopoverShell({ panelId, descriptionId, dialogLabel, eyebrow, title, dialogRef, closeButtonRef, onClose, onKeyDown, spacing, children, }: CustomizePopoverShellProps): React.JSX.Element;
+export type CustomizeCycleRowProps = Readonly<{
+    label: string;
+    valueLabel: string;
+    previousLabel: string;
+    nextLabel: string;
+    availability: CustomizeControlAvailability;
+    onPrevious: () => void;
+    onNext: () => void;
+}>;
+export type CustomizeCycleControlPlan = CustomizeCycleRowProps;
+export type CustomizePopoverControlPlan = Readonly<{
+    cycleRows: readonly CustomizeCycleControlPlan[];
+}>;
+export declare function CustomizeCycleRow({ label, valueLabel, previousLabel, nextLabel, availability, onPrevious, onNext, }: CustomizeCycleRowProps): React.JSX.Element;
+export declare function cycleAvailability(input: CustomizeCycleAvailabilityInput): CustomizeControlAvailability;
+export declare function cycleUnavailableReasonLabel(reason: CustomizeControlUnavailableReason): string;
+export declare function cycleAvailabilityFromFlags(input: Readonly<{
+    canCycle: boolean;
+    applyAllowed: boolean;
+}>): CustomizeControlAvailability;

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

@@ -4,7 +4,7 @@ import type { PreviewCustomizeAction } from '../blocks/previewCustomizeActions';
 import type { SystemCustomizeFacetHistorySelection } from '../../../../blocks/src/system/customize/facets';
 import { type BackgroundOverride } from '../../../../blocks/src/system/customize/backgrounds';
 type PreviewLoadedEditorModel = PageDesignEditorReadModel;
-export type PreviewCustomizeHistoryEntry = Readonly<{
+export type PreviewCustomizeAtomicHistoryEntry = Readonly<{
     kind: 'layout';
     blockId: PreviewCustomizeActionBlockId;
     fromLayoutVariantKey: LayoutVariantKey;
@@ -30,6 +30,10 @@ export type PreviewCustomizeHistoryEntry = Readonly<{
     fromBoundaryOptionId: BoundaryOptionId | null;
     toBoundaryOptionId: BoundaryOptionId | null;
 }>;
+export type PreviewCustomizeHistoryEntry = PreviewCustomizeAtomicHistoryEntry | Readonly<{
+    kind: 'batch';
+    entries: readonly PreviewCustomizeAtomicHistoryEntry[];
+}>;
 type PreviewCustomizeActionBlockId = DesignBlockId;
 export type PreviewCustomizeHistoryPresent = Readonly<{
     editorModel: PreviewLoadedEditorModel;
@@ -40,12 +44,15 @@ export declare function createPreviewCustomizeHistoryState(editorModel: PreviewL
 export declare function canUndoPreviewCustomizeHistory(state: PreviewCustomizeHistoryState): boolean;
 export declare function canRedoPreviewCustomizeHistory(state: PreviewCustomizeHistoryState): boolean;
 export declare function pushPreviewCustomizeHistoryEntry(state: PreviewCustomizeHistoryState, entry: PreviewCustomizeHistoryEntry, editorModel: PreviewLoadedEditorModel): PreviewCustomizeHistoryState;
+export declare function previewCustomizeBatchHistoryEntry(entries: readonly (PreviewCustomizeHistoryEntry | null)[]): PreviewCustomizeHistoryEntry | null;
 export declare function replacePreviewCustomizeHistoryModel(state: PreviewCustomizeHistoryState, editorModel: PreviewLoadedEditorModel): PreviewCustomizeHistoryState;
 export declare function undoPreviewCustomizeHistory(state: PreviewCustomizeHistoryState): PreviewCustomizeHistoryState;
 export declare function redoPreviewCustomizeHistory(state: PreviewCustomizeHistoryState): PreviewCustomizeHistoryState;
 export declare function previewCustomizeHistoryEntryFromAction(editorModel: PreviewLoadedEditorModel, action: PreviewCustomizeAction): PreviewCustomizeHistoryEntry | null;
 export declare function previewCustomizeUndoActionForEntry(entry: PreviewCustomizeHistoryEntry, editorModel: PreviewLoadedEditorModel): PreviewCustomizeAction;
 export declare function previewCustomizeRedoActionForEntry(entry: PreviewCustomizeHistoryEntry, editorModel: PreviewLoadedEditorModel): PreviewCustomizeAction;
+export declare function previewCustomizeUndoActionsForEntry(entry: PreviewCustomizeHistoryEntry, editorModel: PreviewLoadedEditorModel): readonly PreviewCustomizeAction[];
+export declare function previewCustomizeRedoActionsForEntry(entry: PreviewCustomizeHistoryEntry, editorModel: PreviewLoadedEditorModel): readonly PreviewCustomizeAction[];
 export declare function previewCustomizeHistoryPresentEquals(left: PreviewCustomizeHistoryPresent, right: PreviewCustomizeHistoryPresent): boolean;
 export declare function contentRevisionIdForBlock(editorModel: PreviewLoadedEditorModel, blockId: PreviewCustomizeActionBlockId): string | null;
 export {};

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

@@ -1,6 +1,7 @@
 import type { APIEndpoints } from '../../../../api/src/index';
 import type { PreviewCustomizeAction } from '../blocks/previewCustomizeActions';
 import { type PreviewCustomizeHistoryEntry, type PreviewCustomizeHistoryState } from './previewCustomizeHistory';
+import { type EditorSaveBatch, type EditorTransaction } from '../../../../content-editor/src/editorTransactionState';
 type ApiPageDesignEditorStateResponse = NonNullable<APIEndpoints['getPageDesignEditorState']['response']>;
 type LoadedPageDesignEditorState = Extract<ApiPageDesignEditorStateResponse, Readonly<{
     kind: 'loaded';
@@ -45,23 +46,24 @@ export type PreviewCustomizeMutationState = Readonly<{
     actions: readonly PreviewCustomizePendingAction[];
 }> | Readonly<{
     kind: 'applying';
-    action: PreviewCustomizeAction;
-    historyEntry: PreviewCustomizeHistoryEntry | null;
+    batch: PreviewCustomizeSaveBatch;
     queuedActions: readonly PreviewCustomizePendingAction[];
 }> | Readonly<{
     kind: 'undoing';
-    action: PreviewCustomizeAction;
+    actions: readonly PreviewCustomizeAction[];
     entry: PreviewCustomizeHistoryEntry;
 }> | Readonly<{
     kind: 'redoing';
-    action: PreviewCustomizeAction;
+    actions: readonly PreviewCustomizeAction[];
     entry: PreviewCustomizeHistoryEntry;
 }> | Readonly<{
     kind: 'stale';
     message: string;
+    actions: readonly PreviewCustomizePendingAction[];
 }> | Readonly<{
     kind: 'failed';
     message: string;
+    actions: readonly PreviewCustomizePendingAction[];
 }>;
 export type PreviewCustomizeWorkflowState = Readonly<{
     kind: 'unsupported';
@@ -79,14 +81,14 @@ export type PreviewCustomizeWorkflowState = Readonly<{
     history: PreviewCustomizeHistoryState;
     mutation: PreviewCustomizeMutationState;
 }>;
-type PreviewCustomizePendingAction = Readonly<{
-    action: PreviewCustomizeAction;
-    historyEntry: PreviewCustomizeHistoryEntry | null;
-}>;
+type PreviewCustomizeTargetKey = `block:${string}:layout` | `block:${string}:look` | `block:${string}:facet:${string}` | `block:${string}:background` | `boundary:${string}:${string}`;
+type PreviewCustomizePendingAction = EditorTransaction<PreviewCustomizeAction, PreviewCustomizeHistoryEntry, PreviewCustomizeTargetKey>;
+type PreviewCustomizeSaveBatch = EditorSaveBatch<PreviewCustomizeAction, PreviewCustomizeHistoryEntry, PreviewCustomizeTargetKey>;
 export type PreviewCustomizeBeginResult = Readonly<{
     kind: 'started';
     state: PreviewCustomizeWorkflowState;
-    action: PreviewCustomizeAction;
+    actions: readonly PreviewCustomizeAction[];
+    recordsHistoryEntry: boolean;
 }> | Readonly<{
     kind: 'skipped';
     reason: PreviewCustomizeSkipReason;

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

@@ -0,0 +1,18 @@
+export type PreviewDesignHistoryDomainId = 'site-style-design' | 'site-chrome-quick-controls' | 'theme-customize';
+export type PreviewDesignHistoryOrderState = Readonly<{
+    past: readonly PreviewDesignHistoryDomainId[];
+    future: readonly PreviewDesignHistoryDomainId[];
+}>;
+export type PreviewDesignHistoryCommand = 'undo' | 'redo';
+export type PreviewDesignHistoryDomainCapabilities = Readonly<{
+    canUndo: boolean;
+    canRedo: boolean;
+    isPending: boolean;
+    isStale: boolean;
+}>;
+export declare function createPreviewDesignHistoryOrderState(): PreviewDesignHistoryOrderState;
+export declare function recordPreviewDesignHistoryDomain(state: PreviewDesignHistoryOrderState, domainId: PreviewDesignHistoryDomainId): PreviewDesignHistoryOrderState;
+export declare function confirmPreviewDesignHistoryUndo(state: PreviewDesignHistoryOrderState, domainId: PreviewDesignHistoryDomainId): PreviewDesignHistoryOrderState;
+export declare function confirmPreviewDesignHistoryRedo(state: PreviewDesignHistoryOrderState, domainId: PreviewDesignHistoryDomainId): PreviewDesignHistoryOrderState;
+export declare function selectPreviewDesignHistoryDomain(state: PreviewDesignHistoryOrderState, command: PreviewDesignHistoryCommand, capabilities: Readonly<Record<PreviewDesignHistoryDomainId, PreviewDesignHistoryDomainCapabilities>>): PreviewDesignHistoryDomainId | null;
+export declare function previewDesignHistoryDomainForCommand(state: PreviewDesignHistoryOrderState, command: PreviewDesignHistoryCommand): PreviewDesignHistoryDomainId | null;

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

@@ -1,4 +1,4 @@
-export type PreviewUndoDomainId = 'content' | 'theme-customize';
+export type PreviewUndoDomainId = 'content' | 'preview-design-history' | 'theme-customize' | 'site-style-design';
 export type PreviewUndoDomainStatus = 'idle' | 'pending' | 'stale' | 'failed';
 export type PreviewUndoFocusOwner = 'preview-customize' | 'content' | 'native';
 export type PreviewUndoDomainOwnership = Readonly<{

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

@@ -0,0 +1,41 @@
+import type { Theme } from '../../../../blocks/src/index';
+import type { BrandDisplayMode, HeaderSelectionContext, LogoSizePolicy } from '../../../../theme-core/src/site-styles/index';
+export type HeaderBrandPreferences = Readonly<{
+    brandDisplay: BrandDisplayMode;
+    logoSize: LogoSizePolicy;
+}>;
+export type HeaderBrandDisplayOption = Readonly<{
+    value: BrandDisplayMode;
+    label: string;
+    disabled?: boolean;
+}>;
+export type HeaderLogoSizeOption = Readonly<{
+    value: LogoSizePolicy;
+    label: string;
+}>;
+export type HeaderBrandControlState = Readonly<{
+    kind: 'logo-available';
+    preferences: HeaderBrandPreferences;
+    brandDisplayOptions: readonly HeaderBrandDisplayOption[];
+    logoSizeOptions: readonly HeaderLogoSizeOption[];
+}> | Readonly<{
+    kind: 'no-logo';
+    preferences: HeaderBrandPreferences;
+    brandDisplayOptions: readonly HeaderBrandDisplayOption[];
+    logoSizeOptions: readonly HeaderLogoSizeOption[];
+}>;
+export declare const DEFAULT_HEADER_BRAND_PREFERENCES: HeaderBrandPreferences;
+export declare const HEADER_LOGO_SIZE_OPTIONS: readonly HeaderLogoSizeOption[];
+export declare function createHeaderBrandControlState({ theme, headerSelectionContext, }: {
+    theme: Theme | null;
+    headerSelectionContext: Partial<HeaderSelectionContext> | undefined;
+}): HeaderBrandControlState;
+export declare function createHeaderBrandControlStateFromPreferences({ preferences, headerSelectionContext, }: {
+    preferences: HeaderBrandPreferences;
+    headerSelectionContext: Partial<HeaderSelectionContext> | undefined;
+}): HeaderBrandControlState;
+export declare function readHeaderBrandPreferences(theme: Theme | null): HeaderBrandPreferences;
+export declare function normalizeHeaderBrandPreferences(preferences: HeaderBrandPreferences, hasLogo: boolean): HeaderBrandPreferences;
+export declare function withHeaderBrandThemePreferences(theme: Theme, preferences: HeaderBrandPreferences): Theme;
+export declare function withHeaderBrandPreferences(context: Partial<HeaderSelectionContext> | undefined, preferences: HeaderBrandPreferences): Partial<HeaderSelectionContext> | undefined;
+export declare function hasLogoInHeaderSelectionContext(context: Partial<HeaderSelectionContext> | undefined): boolean;

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

@@ -0,0 +1,120 @@
+import { type HistoryState } from '../../../../content-editor/src/index';
+import { type BrandDisplayMode, type FooterLookId, type LogoSizePolicy, type SiteChromeBackgroundOverride, type SiteChromeBackgroundPreferences } from '../../../../theme-core/src/site-styles/index';
+import type { SelectionSnapshot } from './StyleConfigurator.state';
+import type { HeaderBrandPreferences } from './siteChromeBrandPreferences';
+type HeaderLayoutSelection = Pick<SelectionSnapshot, 'headerLayoutId' | 'headerStyleId' | 'headerLookId'>;
+type HeaderStyleSelection = Pick<SelectionSnapshot, 'headerStyleId' | 'headerLookId'>;
+export type SiteChromeQuickControlHistoryEntry = Readonly<{
+    kind: 'header-layout';
+    previous: HeaderLayoutSelection;
+    next: HeaderLayoutSelection;
+}> | Readonly<{
+    kind: 'header-style';
+    previous: HeaderStyleSelection;
+    next: HeaderStyleSelection;
+}> | Readonly<{
+    kind: 'footer-look';
+    previous: FooterLookId | null;
+    next: FooterLookId | null;
+}> | Readonly<{
+    kind: 'header-background';
+    previous: SiteChromeBackgroundOverride;
+    next: SiteChromeBackgroundOverride;
+}> | Readonly<{
+    kind: 'footer-background';
+    previous: SiteChromeBackgroundOverride;
+    next: SiteChromeBackgroundOverride;
+}> | Readonly<{
+    kind: 'header-brand-display';
+    previous: BrandDisplayMode;
+    next: BrandDisplayMode;
+}> | Readonly<{
+    kind: 'header-logo-size';
+    previous: LogoSizePolicy;
+    next: LogoSizePolicy;
+}>;
+export type SiteChromeQuickControlHistoryPresent = Readonly<{
+    selection: SelectionSnapshot;
+    headerBrandPreferences: HeaderBrandPreferences;
+    backgroundPreferences: SiteChromeBackgroundPreferences;
+    entry: SiteChromeQuickControlHistoryEntry | null;
+}>;
+type SiteChromeQuickControlHistoryPresentInput = Readonly<{
+    selection: SelectionSnapshot;
+    headerBrandPreferences: HeaderBrandPreferences;
+    backgroundPreferences?: SiteChromeBackgroundPreferences;
+}>;
+export type SiteChromeQuickControlReplayPlan = Readonly<{
+    kind: 'selection';
+    surface: 'header' | 'footer';
+    selection: SelectionSnapshot;
+}> | Readonly<{
+    kind: 'brand-preferences';
+    preferences: HeaderBrandPreferences;
+}> | Readonly<{
+    kind: 'background-preferences';
+    preferences: SiteChromeBackgroundPreferences;
+}>;
+export type SiteChromeQuickControlHistoryMutation = Readonly<{
+    kind: 'idle';
+}> | Readonly<{
+    kind: 'undoing';
+    entry: SiteChromeQuickControlHistoryEntry;
+    base: SiteChromeQuickControlHistoryPresent;
+    target: SiteChromeQuickControlReplayPlan;
+}> | Readonly<{
+    kind: 'redoing';
+    entry: SiteChromeQuickControlHistoryEntry;
+    base: SiteChromeQuickControlHistoryPresent;
+    target: SiteChromeQuickControlReplayPlan;
+}> | Readonly<{
+    kind: 'failed';
+    message: string;
+}> | Readonly<{
+    kind: 'stale';
+    message: string;
+}>;
+export type SiteChromeQuickControlHistoryState = Readonly<{
+    history: HistoryState<SiteChromeQuickControlHistoryPresent>;
+    mutation: SiteChromeQuickControlHistoryMutation;
+}>;
+export type SiteChromeQuickControlHistoryBeginResult = Readonly<{
+    kind: 'started';
+    state: SiteChromeQuickControlHistoryState;
+    entry: SiteChromeQuickControlHistoryEntry;
+    base: SiteChromeQuickControlHistoryPresent;
+    target: SiteChromeQuickControlReplayPlan;
+}> | Readonly<{
+    kind: 'skipped';
+    reason: SiteChromeQuickControlHistorySkipReason;
+}>;
+export type SiteChromeQuickControlHistorySkipReason = 'not-ready' | 'mutation-pending' | 'stale' | 'cannot-undo' | 'cannot-redo' | 'no-history-entry';
+export type SiteChromeQuickControlHistoryFailure = Readonly<{
+    kind: 'retryable' | 'stale';
+    message: string;
+}>;
+export type SiteChromeQuickControlSelectionTarget = 'header-layout' | 'header-style' | 'footer-look';
+export type SiteChromeQuickControlBrandTarget = 'header-brand-display' | 'header-logo-size';
+export type SiteChromeQuickControlBackgroundTarget = 'header-background' | 'footer-background';
+export declare function createSiteChromeQuickControlHistoryState(present: SiteChromeQuickControlHistoryPresentInput): SiteChromeQuickControlHistoryState;
+export declare function recordSiteChromeQuickControlHistoryEntry(state: SiteChromeQuickControlHistoryState, input: Readonly<{
+    entry: SiteChromeQuickControlHistoryEntry;
+    previous?: SiteChromeQuickControlHistoryPresentInput;
+    persisted: SiteChromeQuickControlHistoryPresentInput;
+}>): SiteChromeQuickControlHistoryState;
+export declare function quickControlHistoryEntryFromSelectionChange(previous: SelectionSnapshot, next: SelectionSnapshot, target: SiteChromeQuickControlSelectionTarget): SiteChromeQuickControlHistoryEntry | null;
+export declare function quickControlHistoryEntryFromBrandPreferenceChange(previous: HeaderBrandPreferences, next: HeaderBrandPreferences, target: SiteChromeQuickControlBrandTarget): SiteChromeQuickControlHistoryEntry | null;
+export declare function quickControlHistoryEntryFromBackgroundPreferenceChange(previous: SiteChromeBackgroundPreferences, next: SiteChromeBackgroundPreferences, target: SiteChromeQuickControlBackgroundTarget): SiteChromeQuickControlHistoryEntry | null;
+export declare function beginSiteChromeQuickControlHistoryUndo(state: SiteChromeQuickControlHistoryState): SiteChromeQuickControlHistoryBeginResult;
+export declare function beginSiteChromeQuickControlHistoryRedo(state: SiteChromeQuickControlHistoryState): SiteChromeQuickControlHistoryBeginResult;
+export declare function confirmSiteChromeQuickControlHistoryMutation(state: SiteChromeQuickControlHistoryState, persisted: SiteChromeQuickControlHistoryPresentInput): SiteChromeQuickControlHistoryState;
+export declare function rejectSiteChromeQuickControlHistoryMutation(state: SiteChromeQuickControlHistoryState, failure: SiteChromeQuickControlHistoryFailure): SiteChromeQuickControlHistoryState;
+export declare function cancelSiteChromeQuickControlHistoryMutation(state: SiteChromeQuickControlHistoryState, mutation: Extract<SiteChromeQuickControlHistoryMutation, {
+    kind: 'undoing' | 'redoing';
+}>): SiteChromeQuickControlHistoryState;
+export declare function siteChromeQuickControlHistoryCanUndo(state: SiteChromeQuickControlHistoryState | null): boolean;
+export declare function siteChromeQuickControlHistoryCanRedo(state: SiteChromeQuickControlHistoryState | null): boolean;
+export declare function siteChromeQuickControlHistoryIsPending(state: SiteChromeQuickControlHistoryState | null): boolean;
+export declare function siteChromeQuickControlHistoryIsStale(state: SiteChromeQuickControlHistoryState | null): boolean;
+export declare function siteChromeQuickControlHistoryFailureMessage(state: SiteChromeQuickControlHistoryState | null): string | null;
+export {};

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

@@ -0,0 +1,30 @@
+import type { APIEndpoints } from '../../../../api/src/index';
+import type { Theme } from '../../../../blocks/src/index';
+import type { FooterSelectionContext, HeaderSelectionContext, SiteChromeBackgroundPreferences } from '../../../../theme-core/src/site-styles/index';
+import type { CuratedSiteStyle } from '../../../../theme-core/src/site-styles/previewCompiler';
+import type { SelectionSnapshot } from './StyleConfigurator.state';
+import { type SiteStylePreviewPlan } from './siteStylePreviewPlanner';
+import type { SiteChromeEditableSurfaceKind } from './SiteChromeEditableSurface';
+import { type HeaderBrandPreferences } from './siteChromeBrandPreferences';
+type SaveSiteChromeLookSelectionBody = NonNullable<APIEndpoints['saveSiteChromeLookSelection']['body']>;
+export type SiteChromeSavePlan = Readonly<{
+    compiled: SiteStylePreviewPlan;
+    themeOverlay: Theme;
+    body: SaveSiteChromeLookSelectionBody;
+}>;
+export type BuildSiteChromeSavePlanInput = Readonly<{
+    surface: SiteChromeEditableSurfaceKind;
+    siteStyle: CuratedSiteStyle;
+    selection: SelectionSnapshot;
+    baseTheme: Theme | null | undefined;
+    headerSelectionContext: Partial<HeaderSelectionContext> | undefined;
+    footerSelectionContext: Partial<FooterSelectionContext> | undefined;
+    headerBrandPreferences: HeaderBrandPreferences;
+    backgroundPreferences: SiteChromeBackgroundPreferences;
+    themeId: string | null;
+    selectionId: string | null;
+    baseSelectionUpdatedAt: string | null;
+}>;
+export declare function buildSiteChromeSavePlan({ surface, siteStyle, selection, baseTheme, headerSelectionContext, footerSelectionContext, headerBrandPreferences, backgroundPreferences, themeId, selectionId, baseSelectionUpdatedAt, }: BuildSiteChromeSavePlanInput): SiteChromeSavePlan;
+export declare function siteChromeSavePlanBodyForBaseRevision(plan: SiteChromeSavePlan, baseSelectionUpdatedAt: string | null): SaveSiteChromeLookSelectionBody;
+export {};