@morphika/andami 0.5.1 → 0.5.3

package/lib/builder/types-slices.ts

@@ -1,414 +1,428 @@
-// ============================================
-// Builder Store — Slice Types
-// ============================================
-// The builder store is composed of 7 logical slices. Each slice owns a
-// subset of the state and a subset of the actions. `BuilderState` and
-// `BuilderActions` in `./types.ts` are declared as intersections of
-// these slices, so the runtime shape stays flat — no `state.blocks.rows`
-// indirection. The split is purely a type-level organization.
-//
-// Slice owners (who writes what):
-// - MetaSlice        : page identity, draft/publish, dirty/saving flags
-// - SectionSlice     : rows (ContentItem[]), section editor mode, custom section cache, parallax groups
-// - BlockSlice       : block CRUD + debounced update (writes rows, too)
-// - CanvasSlice      : canvas viewport, preview mode, page/grid settings
-// - CoverSlice       : cover-section-specific row + background + settings ops
-// - SelectionSlice   : selection keys, color picker preview
-// - HistorySlice     : undo/redo + snapshot push
-//
-// Cross-slice writes are legitimate (e.g. deleteBlock clears selectedBlockKey).
-// Fase 1 does NOT narrow the `set` signature — that is Fase 2, when the
-// runtime shape is actually split into nested slice objects.
-//
-// Session 183 (Fase 1 / Nivel A).
-// ============================================
-
-import type {
-  Page,
-  PageType,
-  ContentBlock,
-  ContentItem,
-  PageSectionV2,
-  SectionV2Settings,
-  SectionV2Preset,
-  PageMetadata,
-  ColorField,
-  CoverSection,
-  CoverSectionSettings,
-  CoverRow,
-} from "../../lib/sanity/types";
-import type { BlockType } from "./types";
-import type { PageSettings, GridSettings, CanvasTool, DeviceViewport } from "./types";
-
-// ============================================
-// MetaSlice — page identity and persistence flags
-// ============================================
-
-export interface MetaSliceState {
-  pageId: string | null;
-  pageTitle: string;
-  pageSlug: string;
-  /** The slug as loaded from Sanity — used for API calls even if slug is edited. */
-  _originalSlug: string;
-  pageType: PageType;
-  metadata: PageMetadata;
-  publishedAt: string | null;
-  draftMode: boolean;
-
-  isDirty: boolean;
-  isSaving: boolean;
-  saveError: string | null;
-  lastSavedAt: string | null;
-}
-
-export interface MetaSliceActions {
-  setPageTitle: (title: string) => void;
-  setPageSlug: (slug: string) => void;
-  setMetadata: (metadata: Partial<PageMetadata>) => void;
-  setDraftMode: (draft: boolean) => void;
-  publishPage: () => void;
-  unpublishPage: () => void;
-
-  loadFromDocument: (doc: Page) => void;
-  save: () => Promise<void>;
-  reset: () => void;
-
-  markDirty: () => void;
-  markClean: () => void;
-}
-
-export type MetaSlice = MetaSliceState & MetaSliceActions;
-
-// ============================================
-// SectionSlice — content rows + section editor + custom sections + parallax
-// ============================================
-
-export interface SectionSliceState {
-  /** Content rows: V2 sections, custom section instances, parallax groups, cover sections. */
-  rows: ContentItem[];
-
-  /** Cache of fetched custom section base settings, keyed by custom_section_id. */
-  _customSectionCache: Record<string, SectionV2Settings>;
-
-  /** Counter incremented after a custom section is saved — triggers refetch in consumers. */
-  _customSectionRefetchTick: number;
-}
-
-export interface SectionSliceActions {
-  // Section-level (top-level row) operations
-  addSection: (
-    blockType: "projectGridBlock" | "projectCarouselBlock",
-    afterRowKey?: string | null,
-  ) => void;
-  reorderRows: (fromIndex: number, toIndex: number) => void;
-  deleteSection: (sectionKey: string) => void;
-  duplicateSection: (sectionKey: string) => void;
-
-  // V2 section operations
-  addSectionV2: (preset: SectionV2Preset, afterRowKey?: string | null) => void;
-  addColumnV2: (sectionKey: string, gridRow: number, gridColumn: number, span: number) => void;
-  deleteColumnV2: (sectionKey: string, columnKey: string) => void;
-  resizeColumnV2: (sectionKey: string, columnKey: string, newSpan: number) => void;
-  resizeColumnV2Left: (sectionKey: string, columnKey: string, newGridColumn: number) => void;
-  moveColumnV2: (
-    sectionKey: string,
-    columnKey: string,
-    targetRow: number,
-    targetColumn: number,
-  ) => void;
-  swapColumnV2: (sectionKey: string, draggedKey: string, targetKey: string) => void;
-  moveColumnToGapV2: (
-    sectionKey: string,
-    columnKey: string,
-    targetRow: number,
-    targetColumn: number,
-    targetSpan: number,
-  ) => void;
-  /**
-   * Move a column from one columnar section (V2 or Cover) to another.
-   * Blocks travel with the column. Responsive overrides for the moved
-   * column are stripped from the source section. Span/grid_column are
-   * clamped to the target's grid_columns. Returns the final landed span
-   * so the caller can adjust UI feedback (e.g. show clamped value).
-   */
-  moveColumnBetweenSections: (
-    sourceSectionKey: string,
-    columnKey: string,
-    targetSectionKey: string,
-    targetRow: number,
-    targetColumn: number,
-    targetSpan: number,
-  ) => void;
-  /**
-   * Swap two columns across different columnar sections (V2 ↔ Cover).
-   * Each column adopts the other's position/row/span. Blocks travel
-   * with the column. Responsive overrides for both swapped columns
-   * are stripped (overrides are per-section by `_key`).
-   */
-  swapColumnsBetweenSections: (
-    sourceSectionKey: string,
-    sourceColumnKey: string,
-    targetSectionKey: string,
-    targetColumnKey: string,
-  ) => void;
-  applyPresetV2: (sectionKey: string, preset: SectionV2Preset) => void;
-  updateSectionV2Settings: (sectionKey: string, settings: Partial<SectionV2Settings>) => void;
-  updateSectionV2Responsive: (
-    sectionKey: string,
-    responsive: PageSectionV2["responsive"],
-  ) => void;
-  addBlockV2: (
-    sectionKey: string,
-    columnKey: string,
-    blockType: BlockType,
-    insertIndex?: number,
-  ) => void;
-  updateColumnEnterAnimation: (
-    sectionKey: string,
-    colKey: string,
-    config: import("../../lib/animation/enter-types").EnterAnimationConfig | undefined,
-  ) => void;
-
-  /** Select a V2 column — sets selectedRowKey + selectedColumnKey. */
-  selectColumnV2: (sectionKey: string | null, columnKey: string | null) => void;
-
-  // Custom section instance operations (reference lifecycle on the page)
-  addCustomSectionInstance: (
-    id: string,
-    slug: string,
-    title: string,
-    afterRowKey?: string | null,
-  ) => void;
-  detachCustomSectionInstance: (instanceKey: string, sectionData: PageSectionV2) => void;
-  updateCustomSectionInstanceTitle: (instanceKey: string, newTitle: string) => void;
-  updateCustomSectionInstanceSettings: (
-    instanceKey: string,
-    updates: Partial<SectionV2Settings>,
-  ) => void;
-  cacheCustomSectionSettings: (sectionId: string, settings: SectionV2Settings) => void;
-
-  // Parallax Group operations (Session 123)
-  addParallaxGroup: (afterRowKey?: string | null) => void;
-  addParallaxSlide: (groupKey: string) => void;
-  removeParallaxSlide: (groupKey: string, slideKey: string) => void;
-  moveParallaxSlide: (groupKey: string, slideKey: string, direction: "up" | "down") => void;
-  updateParallaxSlideBackground: (
-    groupKey: string,
-    slideKey: string,
-    fields: Partial<import("../../lib/sanity/types").ParallaxSlideV2>,
-  ) => void;
-  updateParallaxGroupSettings: (
-    groupKey: string,
-    fields: Partial<
-      Pick<
-        import("../../lib/sanity/types").ParallaxGroup,
-        "transition_effect" | "snap_enabled" | "parallax_intensity"
-      >
-    >,
-  ) => void;
-}
-
-export type SectionSlice = SectionSliceState & SectionSliceActions;
-
-// ============================================
-// BlockSlice — block CRUD (no exclusive state; writes rows)
-// ============================================
-
-// Block slice has no exclusive state — all block data lives inside `rows`
-// (owned by SectionSlice). Block operations legitimately write to rows and
-// to selection keys (e.g. deleteBlock clears selectedBlockKey).
-
-export interface BlockSliceActions {
-  updateBlock: (blockKey: string, updates: Partial<ContentBlock>) => void;
-  deleteBlock: (blockKey: string) => void;
-  duplicateBlock: (blockKey: string) => void;
-  moveBlock: (
-    blockKey: string,
-    targetSectionKey: string,
-    targetColumnKey: string,
-    toIndex: number,
-  ) => void;
-  reorderBlocks: (
-    sectionKey: string,
-    columnKey: string,
-    fromIndex: number,
-    toIndex: number,
-  ) => void;
-  /** Debounced block update — batches keystrokes, does not push history per call. */
-  updateBlockDebounced: (blockKey: string, updates: Partial<ContentBlock>) => void;
-}
-
-export type BlockSlice = BlockSliceActions;
-
-// ============================================
-// CanvasSlice — viewport, preview mode, page + grid settings
-// ============================================
-
-export interface CanvasSliceState {
-  // Editor mode
-  previewMode: boolean;
-
-  // Custom section editor mode (Session 107) — the canvas swaps its
-  // rows between the current page and the custom section being edited,
-  // so this is modelled as a canvas concern.
-  editorMode: "page" | "customSection";
-  customSectionSlug: string | null;
-  customSectionTitle: string | null;
-  /** Stashed page state while editing a custom section */
-  savedPageState: { rows: ContentItem[]; selectedKey: string | null } | null;
-
-  // Page-level settings (global per page, persisted to Sanity)
-  pageSettings: PageSettings;
-
-  // Grid settings (from Customize — ephemeral, NOT saved per page)
-  gridSettings: GridSettings;
-
-  // Canvas viewport state (ephemeral)
-  canvasZoom: number;
-  canvasPanX: number;
-  canvasPanY: number;
-  canvasTool: CanvasTool;
-  activeViewport: DeviceViewport;
-
-  // BUG-014 fix: Track whether the Sanity document had page_settings.
-  // When true, applyGlobalStyles() won't overwrite user-chosen colors.
-  _hasDocumentPageSettings: boolean;
-}
-
-export interface CanvasSliceActions {
-  togglePreviewMode: () => void;
-  setPreviewMode: (preview: boolean) => void;
-
-  // Custom section editor mode (Session 107)
-  /** Enter section editor mode — stashes current page rows, replaces with a single V2 section */
-  enterSectionEditor: (
-    slug: string | null,
-    title: string | null,
-    sectionData: PageSectionV2 | null,
-  ) => void;
-  /** Exit section editor mode — restores page rows from stash. Pass wasSaved=true to mark page dirty. */
-  exitSectionEditor: (wasSaved?: boolean) => void;
-  /** Save the custom section being edited, then exit editor mode.
-   *  Returns { id, slug, title } on success (for instance insertion after creation). */
-  saveSectionEditor: (
-    title: string,
-  ) => Promise<{ id: string; slug: string; title: string } | null>;
-
-  updatePageSettings: (settings: Partial<PageSettings>) => void;
-  applyGlobalStyles: () => Promise<void>;
-
-  setCanvasZoom: (zoom: number) => void;
-  setCanvasPan: (x: number, y: number) => void;
-  setCanvasTool: (tool: CanvasTool) => void;
-  setActiveViewport: (viewport: DeviceViewport) => void;
-  zoomToFit: (viewportWidth: number, viewportHeight: number) => void;
-  zoomToPoint: (newZoom: number, cursorX: number, cursorY: number) => void;
-  zoomToFrame: (
-    device: DeviceViewport,
-    viewportWidth: number,
-    viewportHeight: number,
-  ) => void;
-}
-
-export type CanvasSlice = CanvasSliceState & CanvasSliceActions;
-
-// ============================================
-// CoverSlice — cover-section-specific row + background + settings ops
-// ============================================
-
-// Cover slice has no exclusive state — cover sections live inside `rows`
-// (SectionSlice). Column/block ops within cover sections reuse V2 actions
-// via findSectionPath() which supports cover sections.
-
-export interface CoverSliceActions {
-  addCoverSection: (afterRowKey?: string | null) => void;
-  addCoverRow: (sectionKey: string) => void;
-  removeCoverRow: (sectionKey: string, rowKey: string) => void;
-  resizeCoverRow: (
-    sectionKey: string,
-    handleIndex: number,
-    deltaPercent: number,
-    startAbove: number,
-    startBelow: number,
-  ) => void;
-  updateCoverRowAlign: (
-    sectionKey: string,
-    rowKey: string,
-    align: CoverRow["vertical_align"],
-  ) => void;
-  updateCoverBackground: (
-    sectionKey: string,
-    fields: Partial<
-      Pick<
-        CoverSection,
-        | "background_type"
-        | "background_color"
-        | "background_image"
-        | "background_video"
-        | "background_position"
-        | "background_size"
-        | "background_overlay_color"
-        | "background_overlay_opacity"
-        | "nav_color"
-      >
-    >,
-  ) => void;
-  updateCoverSettings: (sectionKey: string, settings: Partial<CoverSectionSettings>) => void;
-  updateCoverHeight: (sectionKey: string, height: CoverSection["height"]) => void;
-}
-
-export type CoverSlice = CoverSliceActions;
-
-// ============================================
-// SelectionSlice — selection keys + color picker preview
-// ============================================
-
-export interface SelectionSliceState {
-  selectedRowKey: string | null;
-  selectedColumnKey: string | null;
-  selectedBlockKey: string | null;
-  /** Sub-selection: which project card is selected within a ProjectGrid block */
-  selectedProjectCardKey: string | null;
-
-  /** Live preview overlay from color picker — shown on canvas without persisting to Sanity.
-   *  Set while user is dragging in the color picker; cleared on close. */
-  colorPickerPreview: {
-    blockKey?: string;
-    sectionKey?: string;
-    field: string;
-    value: ColorField;
-  } | null;
-}
-
-export interface SelectionSliceActions {
-  selectRow: (key: string | null) => void;
-  selectColumn: (rowKey: string | null, colKey: string | null) => void;
-  selectBlock: (key: string | null) => void;
-  selectProjectCard: (key: string | null) => void;
-  clearSelection: () => void;
-
-  setColorPickerPreview: (preview: SelectionSliceState["colorPickerPreview"]) => void;
-  clearColorPickerPreview: () => void;
-}
-
-export type SelectionSlice = SelectionSliceState & SelectionSliceActions;
-
-// ============================================
-// HistorySlice — undo/redo + snapshot push
-// ============================================
-
-export interface HistorySliceState {
-  _history: import("./history").HistorySnapshot[];
-  _future: import("./history").HistorySnapshot[];
-}
-
-export interface HistorySliceActions {
-  undo: () => void;
-  redo: () => void;
-  canUndo: () => boolean;
-  canRedo: () => boolean;
-  /** Push a snapshot before a mutation (called internally by block/section mutations). */
-  _pushSnapshot: () => void;
-}
-
-export type HistorySlice = HistorySliceState & HistorySliceActions;
+// ============================================
+// Builder Store — Slice Types
+// ============================================
+// The builder store is composed of 7 logical slices. Each slice owns a
+// subset of the state and a subset of the actions. `BuilderState` and
+// `BuilderActions` in `./types.ts` are declared as intersections of
+// these slices, so the runtime shape stays flat — no `state.blocks.rows`
+// indirection. The split is purely a type-level organization.
+//
+// Slice owners (who writes what):
+// - MetaSlice        : page identity, draft/publish, dirty/saving flags
+// - SectionSlice     : rows (ContentItem[]), section editor mode, custom section cache, parallax groups
+// - BlockSlice       : block CRUD + debounced update (writes rows, too)
+// - CanvasSlice      : canvas viewport, preview mode, page/grid settings
+// - CoverSlice       : cover-section-specific row + background + settings ops
+// - SelectionSlice   : selection keys, color picker preview
+// - HistorySlice     : undo/redo + snapshot push
+//
+// Cross-slice writes are legitimate (e.g. deleteBlock clears selectedBlockKey).
+// Fase 1 does NOT narrow the `set` signature — that is Fase 2, when the
+// runtime shape is actually split into nested slice objects.
+//
+// Session 183 (Fase 1 / Nivel A).
+// ============================================
+
+import type {
+  Page,
+  PageType,
+  ContentBlock,
+  ContentItem,
+  PageSectionV2,
+  SectionV2Settings,
+  SectionV2Preset,
+  SectionColumn,
+  PageMetadata,
+  ColorField,
+  CoverSection,
+  CoverSectionSettings,
+  CoverRow,
+} from "../../lib/sanity/types";
+import type { BlockType, SectionBlockType } from "./types";
+import type { PageSettings, GridSettings, CanvasTool, DeviceViewport } from "./types";
+
+// ============================================
+// MetaSlice — page identity and persistence flags
+// ============================================
+
+export interface MetaSliceState {
+  pageId: string | null;
+  pageTitle: string;
+  pageSlug: string;
+  /** The slug as loaded from Sanity — used for API calls even if slug is edited. */
+  _originalSlug: string;
+  pageType: PageType;
+  metadata: PageMetadata;
+  publishedAt: string | null;
+  draftMode: boolean;
+
+  isDirty: boolean;
+  isSaving: boolean;
+  saveError: string | null;
+  lastSavedAt: string | null;
+}
+
+export interface MetaSliceActions {
+  setPageTitle: (title: string) => void;
+  setPageSlug: (slug: string) => void;
+  setMetadata: (metadata: Partial<PageMetadata>) => void;
+  setDraftMode: (draft: boolean) => void;
+  publishPage: () => void;
+  unpublishPage: () => void;
+
+  loadFromDocument: (doc: Page) => void;
+  save: () => Promise<void>;
+  reset: () => void;
+
+  markDirty: () => void;
+  markClean: () => void;
+}
+
+export type MetaSlice = MetaSliceState & MetaSliceActions;
+
+// ============================================
+// SectionSlice — content rows + section editor + custom sections + parallax
+// ============================================
+
+export interface SectionSliceState {
+  /** Content rows: V2 sections, custom section instances, parallax groups, cover sections. */
+  rows: ContentItem[];
+
+  /** Cache of fetched custom section base settings, keyed by custom_section_id. */
+  _customSectionCache: Record<string, SectionV2Settings>;
+
+  /** Counter incremented after a custom section is saved — triggers refetch in consumers. */
+  _customSectionRefetchTick: number;
+}
+
+export interface SectionSliceActions {
+  // Section-level (top-level row) operations
+  addSection: (
+    blockType: SectionBlockType,
+    afterRowKey?: string | null,
+  ) => void;
+  reorderRows: (fromIndex: number, toIndex: number) => void;
+  deleteSection: (sectionKey: string) => void;
+  duplicateSection: (sectionKey: string) => void;
+
+  // V2 section operations
+  addSectionV2: (preset: SectionV2Preset, afterRowKey?: string | null) => void;
+  addColumnV2: (sectionKey: string, gridRow: number, gridColumn: number, span: number) => void;
+  deleteColumnV2: (sectionKey: string, columnKey: string) => void;
+  resizeColumnV2: (sectionKey: string, columnKey: string, newSpan: number) => void;
+  resizeColumnV2Left: (sectionKey: string, columnKey: string, newGridColumn: number) => void;
+  moveColumnV2: (
+    sectionKey: string,
+    columnKey: string,
+    targetRow: number,
+    targetColumn: number,
+  ) => void;
+  swapColumnV2: (sectionKey: string, draggedKey: string, targetKey: string) => void;
+  moveColumnToGapV2: (
+    sectionKey: string,
+    columnKey: string,
+    targetRow: number,
+    targetColumn: number,
+    targetSpan: number,
+  ) => void;
+  /**
+   * Move a column from one columnar section (V2 or Cover) to another.
+   * Blocks travel with the column. Responsive overrides for the moved
+   * column are stripped from the source section. Span/grid_column are
+   * clamped to the target's grid_columns. Returns the final landed span
+   * so the caller can adjust UI feedback (e.g. show clamped value).
+   */
+  moveColumnBetweenSections: (
+    sourceSectionKey: string,
+    columnKey: string,
+    targetSectionKey: string,
+    targetRow: number,
+    targetColumn: number,
+    targetSpan: number,
+  ) => void;
+  /**
+   * Swap two columns across different columnar sections (V2 ↔ Cover).
+   * Each column adopts the other's position/row/span. Blocks travel
+   * with the column. Responsive overrides for both swapped columns
+   * are stripped (overrides are per-section by `_key`).
+   */
+  swapColumnsBetweenSections: (
+    sourceSectionKey: string,
+    sourceColumnKey: string,
+    targetSectionKey: string,
+    targetColumnKey: string,
+  ) => void;
+  applyPresetV2: (sectionKey: string, preset: SectionV2Preset) => void;
+  updateSectionV2Settings: (sectionKey: string, settings: Partial<SectionV2Settings>) => void;
+  updateSectionV2Responsive: (
+    sectionKey: string,
+    responsive: PageSectionV2["responsive"],
+  ) => void;
+  addBlockV2: (
+    sectionKey: string,
+    columnKey: string,
+    blockType: BlockType,
+    insertIndex?: number,
+  ) => void;
+  updateColumnEnterAnimation: (
+    sectionKey: string,
+    colKey: string,
+    config: import("../../lib/animation/enter-types").EnterAnimationConfig | undefined,
+  ) => void;
+  /** Update desktop-level layout fields on a V2/cover/parallax-slide column.
+   *  Columns only support background + border — spacing belongs to the
+   *  section (row_gap/col_gap) or to block-level padding. */
+  updateColumnV2Layout: (
+    sectionKey: string,
+    colKey: string,
+    updates: Partial<Pick<
+      SectionColumn,
+      | "background_color" | "background_opacity" | "background_image"
+      | "background_size" | "background_position" | "background_repeat"
+      | "border_color" | "border_width" | "border_style" | "border_sides" | "border_radius"
+    >>,
+  ) => void;
+
+  /** Select a V2 column — sets selectedRowKey + selectedColumnKey. */
+  selectColumnV2: (sectionKey: string | null, columnKey: string | null) => void;
+
+  // Custom section instance operations (reference lifecycle on the page)
+  addCustomSectionInstance: (
+    id: string,
+    slug: string,
+    title: string,
+    afterRowKey?: string | null,
+  ) => void;
+  detachCustomSectionInstance: (instanceKey: string, sectionData: PageSectionV2) => void;
+  updateCustomSectionInstanceTitle: (instanceKey: string, newTitle: string) => void;
+  updateCustomSectionInstanceSettings: (
+    instanceKey: string,
+    updates: Partial<SectionV2Settings>,
+  ) => void;
+  cacheCustomSectionSettings: (sectionId: string, settings: SectionV2Settings) => void;
+
+  // Parallax Group operations (Session 123)
+  addParallaxGroup: (afterRowKey?: string | null) => void;
+  addParallaxSlide: (groupKey: string) => void;
+  removeParallaxSlide: (groupKey: string, slideKey: string) => void;
+  moveParallaxSlide: (groupKey: string, slideKey: string, direction: "up" | "down") => void;
+  updateParallaxSlideBackground: (
+    groupKey: string,
+    slideKey: string,
+    fields: Partial<import("../../lib/sanity/types").ParallaxSlideV2>,
+  ) => void;
+  updateParallaxGroupSettings: (
+    groupKey: string,
+    fields: Partial<
+      Pick<
+        import("../../lib/sanity/types").ParallaxGroup,
+        "transition_effect" | "snap_enabled" | "parallax_intensity"
+      >
+    >,
+  ) => void;
+}
+
+export type SectionSlice = SectionSliceState & SectionSliceActions;
+
+// ============================================
+// BlockSlice — block CRUD (no exclusive state; writes rows)
+// ============================================
+
+// Block slice has no exclusive state — all block data lives inside `rows`
+// (owned by SectionSlice). Block operations legitimately write to rows and
+// to selection keys (e.g. deleteBlock clears selectedBlockKey).
+
+export interface BlockSliceActions {
+  updateBlock: (blockKey: string, updates: Partial<ContentBlock>) => void;
+  deleteBlock: (blockKey: string) => void;
+  duplicateBlock: (blockKey: string) => void;
+  moveBlock: (
+    blockKey: string,
+    targetSectionKey: string,
+    targetColumnKey: string,
+    toIndex: number,
+  ) => void;
+  reorderBlocks: (
+    sectionKey: string,
+    columnKey: string,
+    fromIndex: number,
+    toIndex: number,
+  ) => void;
+  /** Debounced block update — batches keystrokes, does not push history per call. */
+  updateBlockDebounced: (blockKey: string, updates: Partial<ContentBlock>) => void;
+}
+
+export type BlockSlice = BlockSliceActions;
+
+// ============================================
+// CanvasSlice — viewport, preview mode, page + grid settings
+// ============================================
+
+export interface CanvasSliceState {
+  // Editor mode
+  previewMode: boolean;
+
+  // Custom section editor mode (Session 107) — the canvas swaps its
+  // rows between the current page and the custom section being edited,
+  // so this is modelled as a canvas concern.
+  editorMode: "page" | "customSection";
+  customSectionSlug: string | null;
+  customSectionTitle: string | null;
+  /** Stashed page state while editing a custom section */
+  savedPageState: { rows: ContentItem[]; selectedKey: string | null } | null;
+
+  // Page-level settings (global per page, persisted to Sanity)
+  pageSettings: PageSettings;
+
+  // Grid settings (from Customize — ephemeral, NOT saved per page)
+  gridSettings: GridSettings;
+
+  // Canvas viewport state (ephemeral)
+  canvasZoom: number;
+  canvasPanX: number;
+  canvasPanY: number;
+  canvasTool: CanvasTool;
+  activeViewport: DeviceViewport;
+
+  // BUG-014 fix: Track whether the Sanity document had page_settings.
+  // When true, applyGlobalStyles() won't overwrite user-chosen colors.
+  _hasDocumentPageSettings: boolean;
+}
+
+export interface CanvasSliceActions {
+  togglePreviewMode: () => void;
+  setPreviewMode: (preview: boolean) => void;
+
+  // Custom section editor mode (Session 107)
+  /** Enter section editor mode — stashes current page rows, replaces with a single V2 section */
+  enterSectionEditor: (
+    slug: string | null,
+    title: string | null,
+    sectionData: PageSectionV2 | null,
+  ) => void;
+  /** Exit section editor mode — restores page rows from stash. Pass wasSaved=true to mark page dirty. */
+  exitSectionEditor: (wasSaved?: boolean) => void;
+  /** Save the custom section being edited, then exit editor mode.
+   *  Returns { id, slug, title } on success (for instance insertion after creation). */
+  saveSectionEditor: (
+    title: string,
+  ) => Promise<{ id: string; slug: string; title: string } | null>;
+
+  updatePageSettings: (settings: Partial<PageSettings>) => void;
+  applyGlobalStyles: () => Promise<void>;
+
+  setCanvasZoom: (zoom: number) => void;
+  setCanvasPan: (x: number, y: number) => void;
+  setCanvasTool: (tool: CanvasTool) => void;
+  setActiveViewport: (viewport: DeviceViewport) => void;
+  zoomToFit: (viewportWidth: number, viewportHeight: number) => void;
+  zoomToPoint: (newZoom: number, cursorX: number, cursorY: number) => void;
+  zoomToFrame: (
+    device: DeviceViewport,
+    viewportWidth: number,
+    viewportHeight: number,
+  ) => void;
+}
+
+export type CanvasSlice = CanvasSliceState & CanvasSliceActions;
+
+// ============================================
+// CoverSlice — cover-section-specific row + background + settings ops
+// ============================================
+
+// Cover slice has no exclusive state — cover sections live inside `rows`
+// (SectionSlice). Column/block ops within cover sections reuse V2 actions
+// via findSectionPath() which supports cover sections.
+
+export interface CoverSliceActions {
+  addCoverSection: (afterRowKey?: string | null) => void;
+  addCoverRow: (sectionKey: string) => void;
+  removeCoverRow: (sectionKey: string, rowKey: string) => void;
+  resizeCoverRow: (
+    sectionKey: string,
+    handleIndex: number,
+    deltaPercent: number,
+    startAbove: number,
+    startBelow: number,
+  ) => void;
+  updateCoverRowAlign: (
+    sectionKey: string,
+    rowKey: string,
+    align: CoverRow["vertical_align"],
+  ) => void;
+  updateCoverBackground: (
+    sectionKey: string,
+    fields: Partial<
+      Pick<
+        CoverSection,
+        | "background_type"
+        | "background_color"
+        | "background_image"
+        | "background_video"
+        | "background_position"
+        | "background_size"
+        | "background_overlay_color"
+        | "background_overlay_opacity"
+        | "nav_color"
+      >
+    >,
+  ) => void;
+  updateCoverSettings: (sectionKey: string, settings: Partial<CoverSectionSettings>) => void;
+  updateCoverHeight: (sectionKey: string, height: CoverSection["height"]) => void;
+}
+
+export type CoverSlice = CoverSliceActions;
+
+// ============================================
+// SelectionSlice — selection keys + color picker preview
+// ============================================
+
+export interface SelectionSliceState {
+  selectedRowKey: string | null;
+  selectedColumnKey: string | null;
+  selectedBlockKey: string | null;
+  /** Sub-selection: which project card is selected within a ProjectGrid block */
+  selectedProjectCardKey: string | null;
+
+  /** Live preview overlay from color picker — shown on canvas without persisting to Sanity.
+   *  Set while user is dragging in the color picker; cleared on close. */
+  colorPickerPreview: {
+    blockKey?: string;
+    sectionKey?: string;
+    field: string;
+    value: ColorField;
+  } | null;
+}
+
+export interface SelectionSliceActions {
+  selectRow: (key: string | null) => void;
+  selectColumn: (rowKey: string | null, colKey: string | null) => void;
+  selectBlock: (key: string | null) => void;
+  selectProjectCard: (key: string | null) => void;
+  clearSelection: () => void;
+
+  setColorPickerPreview: (preview: SelectionSliceState["colorPickerPreview"]) => void;
+  clearColorPickerPreview: () => void;
+}
+
+export type SelectionSlice = SelectionSliceState & SelectionSliceActions;
+
+// ============================================
+// HistorySlice — undo/redo + snapshot push
+// ============================================
+
+export interface HistorySliceState {
+  _history: import("./history").HistorySnapshot[];
+  _future: import("./history").HistorySnapshot[];
+}
+
+export interface HistorySliceActions {
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  /** Push a snapshot before a mutation (called internally by block/section mutations). */
+  _pushSnapshot: () => void;
+}
+
+export type HistorySlice = HistorySliceState & HistorySliceActions;