@morphika/andami 0.4.1 → 0.4.2

package/README.md

@@ -7,7 +7,8 @@ A reusable Visual Page Builder framework for Next.js. Build custom websites with
 ## Features
 
 - **Visual Page Builder** — Infinite canvas editor with device previews (desktop, tablet, phone)
-- **7 Content Blocks** — Text, Image, Image Grid, Video, Spacer, Button, Project Grid
+- **6 Content Blocks** — Text, Image, Image Grid, Video, Spacer, Button (added via "+ Add Block" inside columns)
+- **2 Section-level Blocks** — Project Grid (masonry) and Project Carousel (horizontal "keep browsing" at end of project pages). Added via "+ Add Section"
 - **Cover Sections** — Full-viewport hero sections with proportional rows, background media, and drag-to-resize
 - **V2 Grid System** — 12-column CSS grid with push cascade engine and responsive overrides
 - **Custom Sections** — Create reusable sections with per-instance setting overrides

package/components/builder/ColumnDragOverlay.tsx

@@ -3,8 +3,8 @@
 import { memo } from "react";
 import { createPortal } from "react-dom";
 import { useBuilderStore } from "../../lib/builder/store";
-import type { PageSectionV2 } from "../../lib/sanity/types";
-import { isPageSectionV2 } from "../../lib/sanity/types";
+import type { PageSectionV2, CoverSection, SectionColumn } from "../../lib/sanity/types";
+import { isPageSectionV2, isCoverSection } from "../../lib/sanity/types";
 import { BUILDER_BLUE } from "../../lib/builder/constants";
 
 interface ColumnDragOverlayProps {
@@ -20,14 +20,29 @@ const ColumnDragOverlay = memo(function ColumnDragOverlay({
 }: ColumnDragOverlayProps) {
   const rows = useBuilderStore((s) => s.rows);
   const item = rows.find((r) => r._key === sectionKey);
-  if (!item || !isPageSectionV2(item)) return null;
+  if (!item) return null;
 
-  const v2Section = item as PageSectionV2;
-  const col = v2Section.columns?.find((c) => c._key === columnKey);
+  // Accept both PageSectionV2 and CoverSection — both expose `columns:
+  // SectionColumn[]` and `settings.grid_columns`. Other section types
+  // (parallax, custom instance) are not column-draggable targets.
+  let columns: SectionColumn[] | undefined;
+  let gridColumns = 12;
+  if (isPageSectionV2(item)) {
+    const v2 = item as PageSectionV2;
+    columns = v2.columns;
+    gridColumns = v2.settings?.grid_columns || 12;
+  } else if (isCoverSection(item)) {
+    const cover = item as CoverSection;
+    columns = cover.columns;
+    gridColumns = cover.settings?.grid_columns || 12;
+  } else {
+    return null;
+  }
+
+  const col = columns?.find((c) => c._key === columnKey);
   if (!col) return null;
 
   const blockCount = (col.blocks || []).length;
-  const gridColumns = v2Section.settings.grid_columns || 12;
 
   const overlay = (
     <div

package/components/builder/hooks/useColumnDrag.ts

@@ -2,12 +2,68 @@
 
 import { useState, useCallback, useRef, useEffect } from "react";
 import { useBuilderStore } from "../../../lib/builder/store";
-import type { PageSectionV2 } from "../../../lib/sanity/types";
-import { isPageSectionV2 } from "../../../lib/sanity/types";
+import type { PageSectionV2, CoverSection, ContentItem } from "../../../lib/sanity/types";
+import { isPageSectionV2, isCoverSection } from "../../../lib/sanity/types";
 import { getEffectiveColumnsV2, buildColumnV2Overrides } from "../settings-panel/responsive-helpers";
 import { moveColumn as cascadeMoveColumn } from "../../../lib/builder/cascade";
 import type { DeviceViewport } from "../../../lib/builder/types";
 
+/**
+ * View a Cover section as a PageSectionV2 for DnD purposes.
+ *
+ * Cover and V2 share the same column shape, grid_columns, and
+ * `responsive[vp].columns` shape — the fields read/written by column
+ * DnD. This shim lets us reuse getEffectiveColumnsV2/buildColumnV2Overrides
+ * without duplicating logic. Only `columns`, `settings.grid_columns`, and
+ * `responsive[vp].columns` are exposed; Cover-specific fields
+ * (`cover_rows`, Cover-specific `settings`) are hidden from the V2 helpers.
+ *
+ * The write-back path (`updateSectionV2Responsive` → `updateSectionAtPath`)
+ * merges column overrides back into the cover, preserving Cover-specific
+ * fields. See `store-helpers.ts :: updateSectionAtPath` cover branch.
+ */
+function coverAsV2(cover: CoverSection): PageSectionV2 {
+  return {
+    _type: "pageSectionV2",
+    _key: cover._key,
+    section_type: "empty-v2",
+    columns: cover.columns,
+    settings: {
+      preset: "custom",
+      grid_columns: cover.settings.grid_columns,
+      col_gap: cover.settings.col_gap,
+      row_gap: cover.settings.row_gap,
+    },
+    responsive:
+      cover.responsive?.tablet?.columns || cover.responsive?.phone?.columns
+        ? {
+            ...(cover.responsive.tablet?.columns
+              ? { tablet: { columns: cover.responsive.tablet.columns } }
+              : {}),
+            ...(cover.responsive.phone?.columns
+              ? { phone: { columns: cover.responsive.phone.columns } }
+              : {}),
+          }
+        : undefined,
+  };
+}
+
+/**
+ * Find the section by key and return a V2-shaped view of it (PageSectionV2
+ * directly, or Cover adapted via `coverAsV2`). Returns null if the section
+ * doesn't exist or is an unsupported type (parallax, custom instance).
+ */
+function findColumnarSection(
+  rows: ContentItem[],
+  sectionKey: string,
+): PageSectionV2 | null {
+  const section = rows.find((r) => r._key === sectionKey);
+  if (!section) return null;
+  if (isPageSectionV2(section)) return section as PageSectionV2;
+  if (isCoverSection(section)) return coverAsV2(section as CoverSection);
+  return null;
+}
+
 // ============================================
 // Types
 // ============================================
@@ -57,9 +113,8 @@ function executeResponsiveSwap(
   updateSectionV2Responsive: (sectionKey: string, responsive: PageSectionV2["responsive"]) => void
 ): void {
   const rows = useBuilderStore.getState().rows;
-  const section = rows.find((r) => r._key === sectionKey);
-  if (!section || !isPageSectionV2(section)) return;
-  const v2Section = section as PageSectionV2;
+  const v2Section = findColumnarSection(rows, sectionKey);
+  if (!v2Section) return;
 
   const effectiveCols = getEffectiveColumnsV2(v2Section, viewport);
   const draggedCol = effectiveCols.find((c) => c._key === draggedKey);
@@ -109,9 +164,8 @@ function executeResponsiveGapMove(
   updateSectionV2Responsive: (sectionKey: string, responsive: PageSectionV2["responsive"]) => void
 ): void {
   const rows = useBuilderStore.getState().rows;
-  const section = rows.find((r) => r._key === sectionKey);
-  if (!section || !isPageSectionV2(section)) return;
-  const v2Section = section as PageSectionV2;
+  const v2Section = findColumnarSection(rows, sectionKey);
+  if (!v2Section) return;
 
   const effectiveCols = getEffectiveColumnsV2(v2Section, viewport);
   const columnOverrides = effectiveCols.map((c) => {
@@ -147,9 +201,8 @@ function executeResponsiveInsert(
   updateSectionV2Responsive: (sectionKey: string, responsive: PageSectionV2["responsive"]) => void
 ): void {
   const rows = useBuilderStore.getState().rows;
-  const section = rows.find((r) => r._key === sectionKey);
-  if (!section || !isPageSectionV2(section)) return;
-  const v2Section = section as PageSectionV2;
+  const v2Section = findColumnarSection(rows, sectionKey);
+  if (!v2Section) return;
 
   const effectiveCols = getEffectiveColumnsV2(v2Section, viewport);
   const cascadeResult = cascadeMoveColumn(effectiveCols, columnKey, targetRow, targetCol, v2Section.settings.grid_columns);

package/lib/builder/store-blocks.ts

@@ -1,4 +1,4 @@
-import type { BuilderStore, BuilderState } from "./types";
+import type { BuilderStore, BuilderState, BlockSliceActions } from "./types";
 import type { ContentBlock, ContentItem, PageSectionV2, ParallaxGroup, CoverSection } from "../../lib/sanity/types";
 import { isPageSectionV2, isParallaxGroup, isCoverSection } from "../../lib/sanity/types";
 import { createDefaultBlock } from "./defaults";
@@ -47,7 +47,7 @@ function applyBlockUpdate(
   });
 }
 
-export function createBlockActions(set: StoreSet, get: StoreGet) {
+export function createBlockActions(set: StoreSet, get: StoreGet): BlockSliceActions {
   return {
     // ---- Block operations ----
 

package/lib/builder/store-canvas.ts

@@ -1,4 +1,4 @@
-import type { BuilderStore, BuilderState, CanvasTool, DeviceViewport, PageSettings } from "./types";
+import type { BuilderStore, BuilderState, CanvasTool, DeviceViewport, PageSettings, CanvasSliceActions } from "./types";
 import { DEFAULT_PAGE_SETTINGS, DEFAULT_GRID_SETTINGS, DEVICE_WIDTHS } from "./types";
 import type { PageSectionV2 } from "../../lib/sanity/types";
 import { isPageSectionV2 } from "../../lib/sanity/types";
@@ -11,7 +11,7 @@ type StoreSet = (
 ) => void;
 type StoreGet = () => BuilderStore;
 
-export function createCanvasActions(set: StoreSet, get: StoreGet) {
+export function createCanvasActions(set: StoreSet, get: StoreGet): CanvasSliceActions {
   return {
     // ---- Editor mode ----
 

package/lib/builder/store-cover.ts

@@ -9,7 +9,7 @@
  * Session 176: Cover Sections — Phase 3 (Store).
  */
 
-import type { BuilderState } from "./types";
+import type { BuilderState, CoverSliceActions } from "./types";
 import type {
   ContentItem,
   CoverSection,
@@ -79,7 +79,7 @@ function updateCoverInRows(
   });
 }
 
-export function createCoverActions(set: StoreSet, get: StoreGet) {
+export function createCoverActions(set: StoreSet, get: StoreGet): CoverSliceActions {
   return {
     addCoverSection: (afterRowKey?: string | null): void => {
       get()._pushSnapshot();

package/lib/builder/store-helpers.ts

@@ -16,6 +16,7 @@ import type {
   SectionColumn,
   SectionV2Preset,
   CoverSection,
+  CoverSectionResponsiveOverride,
 } from "../../lib/sanity/types";
 import { isPageSectionV2, isParallaxGroup, isCoverSection } from "../../lib/sanity/types";
 import { columnsFromPreset, detectPreset } from "./cascade";
@@ -480,6 +481,25 @@ export function updateSectionAtPath(
     return rows.map((item, i) => {
       if (i !== path.index || !isCoverSection(item)) return item;
       const cover = item as CoverSection;
+
+      // Passthrough of `responsive.tablet/phone.columns` only — V2 operations
+      // (column DnD, resize) read and write this field, and its shape
+      // (`ColumnOverride[]`) is identical between V2 and Cover. We do NOT
+      // expose Cover-specific fields (`cover_rows`, Cover `settings`) to the
+      // updater via virtualSection.responsive — those stay on the cover
+      // unchanged. This keeps the virtualSection's shape a true V2.
+      const virtualResponsive: PageSectionV2["responsive"] =
+        cover.responsive?.tablet?.columns || cover.responsive?.phone?.columns
+          ? {
+              ...(cover.responsive.tablet?.columns
+                ? { tablet: { columns: cover.responsive.tablet.columns } }
+                : {}),
+              ...(cover.responsive.phone?.columns
+                ? { phone: { columns: cover.responsive.phone.columns } }
+                : {}),
+            }
+          : undefined;
+
       const virtualSection: PageSectionV2 = {
         _type: "pageSectionV2",
         _key: cover._key,
@@ -497,11 +517,34 @@ export function updateSectionAtPath(
           enter_animation: cover.settings.enter_animation,
           stagger: cover.settings.stagger,
         },
+        responsive: virtualResponsive,
       };
       const updated = updater(virtualSection);
+
+      // Merge updated `responsive.columns` back into cover.responsive,
+      // preserving `cover_rows` and Cover-specific `settings` per viewport.
+      const mergedResponsive: CoverSection["responsive"] = {};
+      for (const vp of ["tablet", "phone"] as const) {
+        const existing: CoverSectionResponsiveOverride = {
+          ...(cover.responsive?.[vp] || {}),
+        };
+        const updatedCols = updated.responsive?.[vp]?.columns;
+        if (updatedCols === undefined) {
+          delete existing.columns;
+        } else {
+          existing.columns = updatedCols;
+        }
+        if (existing.columns || existing.cover_rows || existing.settings) {
+          mergedResponsive[vp] = existing;
+        }
+      }
+
       return {
         ...cover,
         columns: updated.columns,
+        responsive: Object.keys(mergedResponsive).length
+          ? mergedResponsive
+          : undefined,
         settings: {
           ...cover.settings,
           grid_columns: updated.settings.grid_columns,

package/lib/builder/store-sections.ts

@@ -1,4 +1,4 @@
-import type { BuilderStore, BuilderState, BlockType } from "./types";
+import type { BuilderStore, BuilderState, BlockType, SectionSliceActions } from "./types";
 import type {
   ContentBlock,
   ContentItem,
@@ -45,7 +45,7 @@ type StoreSet = (
 ) => void;
 type StoreGet = () => BuilderStore;
 
-export function createSectionActions(set: StoreSet, get: StoreGet) {
+export function createSectionActions(set: StoreSet, get: StoreGet): SectionSliceActions {
   return {
     // ---- Section operations ----
 

package/lib/builder/types-slices.ts

@@ -0,0 +1,387 @@
+// ============================================
+// 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;
+  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;

package/lib/builder/types.ts

@@ -182,231 +182,83 @@ export const DEFAULT_GRID_SETTINGS: GridSettings = {
   gutter_phone: "16",
 };
 
-export interface BuilderState {
-  // Page metadata
-  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;
-
-  // Content — V2 sections, custom sections, parallax groups
-  rows: ContentItem[];
-
-  // Selection
-  selectedRowKey: string | null;
-  selectedColumnKey: string | null;
-  selectedBlockKey: string | null;
-  /** Sub-selection: which project card is selected within a ProjectGrid block */
-  selectedProjectCardKey: string | null;
-
-  // UI state
-  isDirty: boolean;
-  isSaving: boolean;
-  saveError: string | null;
-  lastSavedAt: string | null;
-
-  // Editor mode
-  previewMode: boolean;
-
-  // Custom section editor mode (Session 107)
-  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
-  pageSettings: PageSettings;
-
-  // Grid settings (from Customize, ephemeral — NOT saved per page)
-  gridSettings: GridSettings;
-
-  // Canvas state (ephemeral — NOT saved to Sanity)
-  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;
-
-  // History (Undo/Redo) — BUG-010 fix: snapshots include pageSettings
-  _history: import("./history").HistorySnapshot[];
-  _future: import("./history").HistorySnapshot[];
-
-  /** Cache of fetched custom section base settings, keyed by custom_section_id.
-   *  Populated by CustomSectionInstanceCard/ReadOnlyCustomSection on fetch.
-   *  Used by SortableRow to merge base settings with per-instance overrides. */
-  _customSectionCache: Record<string, import("../../lib/sanity/types").SectionV2Settings>;
-
-  /** Counter incremented after a custom section is saved via the section editor.
-   *  Used as a useEffect dependency in CustomSectionInstanceCard to trigger refetch. */
-  _customSectionRefetchTick: number;
-
-  /** 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;
-}
+// ============================================
+// BuilderState & BuilderActions — composed from slices
+// ============================================
+// Session 183 (Fase 1 / Nivel A): state and actions are declared as
+// intersections of per-slice types defined in `./types-slices.ts`.
+// The runtime shape is still a flat object — no `state.blocks.rows`
+// indirection. This split is purely a type-level organization that:
+//   1. Documents which slice owns which state field / action
+//   2. Provides a clear template for adding a new slice
+//   3. Prepares for Fase 2 (actual shape split) without forcing it now
+// ============================================
 
-export interface BuilderActions {
-  // Page metadata
-  setPageTitle: (title: string) => void;
-  setPageSlug: (slug: string) => void;
-  setMetadata: (metadata: Partial<PageMetadata>) => void;
-  setDraftMode: (draft: boolean) => void;
-  publishPage: () => void;
-  unpublishPage: () => void;
-
-  // Section operations
-  /** Add a Project Grid section as a V2 section with a full-width column (Session 164) */
-  addSection: (blockType: "projectGridBlock" | "projectCarouselBlock", afterRowKey?: string | null) => void;
-  reorderRows: (fromIndex: number, toIndex: number) => void;
-  /** Delete a section by key */
-  deleteSection: (sectionKey: string) => void;
-  /** Duplicate a section, inserting copy after the original */
-  duplicateSection: (sectionKey: string) => void;
-
-  // Block operations
-  updateBlock: (blockKey: string, updates: Partial<ContentBlock>) => void;
-  deleteBlock: (blockKey: string) => void;
-  /** Duplicate a content block (inserts copy immediately after the original) */
-  duplicateBlock: (blockKey: string) => void;
-  moveBlock: (blockKey: string, targetSectionKey: string, targetColumnKey: string, toIndex: number) => void;
-  reorderBlocks: (sectionKey: string, columnKey: string, fromIndex: number, toIndex: number) => void;
-
-  // Selection
-  selectRow: (key: string | null) => void;
-  selectColumn: (rowKey: string | null, colKey: string | null) => void;
-  selectBlock: (key: string | null) => void;
-  /** Select a specific project card within a ProjectGrid block */
-  selectProjectCard: (key: string | null) => void;
-  clearSelection: () => void;
-
-  // Persistence
-  loadFromDocument: (doc: Page) => void;
-  save: () => Promise<void>;
-  reset: () => void;
-
-  // Dirty tracking
-  markDirty: () => void;
-  markClean: () => void;
-
-  // History (Undo/Redo)
-  undo: () => void;
-  redo: () => void;
-  canUndo: () => boolean;
-  canRedo: () => boolean;
-  /** Push a snapshot before a mutation (called internally). */
-  _pushSnapshot: () => void;
-
-  // ---- V2 Section operations ----
-  /** Add a new V2 grid section with a preset layout */
-  addSectionV2: (preset: import("../../lib/sanity/types").SectionV2Preset, afterRowKey?: string | null) => void;
-  /** Add a column to a V2 section at a specific position */
-  addColumnV2: (sectionKey: string, gridRow: number, gridColumn: number, span: number) => void;
-  /** Delete a column from a V2 section */
-  deleteColumnV2: (sectionKey: string, columnKey: string) => void;
-  /** Resize a column in a V2 section (right edge) */
-  resizeColumnV2: (sectionKey: string, columnKey: string, newSpan: number) => void;
-  /** Resize a column in a V2 section from the left edge */
-  resizeColumnV2Left: (sectionKey: string, columnKey: string, newGridColumn: number) => void;
-  /** Move a column in a V2 section (drag & drop) */
-  moveColumnV2: (sectionKey: string, columnKey: string, targetRow: number, targetColumn: number) => void;
-  /** Swap two columns in a V2 section (exchange positions, blocks stay) */
-  swapColumnV2: (sectionKey: string, draggedKey: string, targetKey: string) => void;
-  /** Move a column to an empty gap, adopting the gap's span */
-  moveColumnToGapV2: (sectionKey: string, columnKey: string, targetRow: number, targetColumn: number, targetSpan: number) => void;
-  /** Apply a layout preset to a V2 section (replaces columns + updates preset atomically) */
-  applyPresetV2: (sectionKey: string, preset: SectionV2Preset) => void;
-  /** Update settings for a V2 section */
-  updateSectionV2Settings: (sectionKey: string, settings: Partial<SectionV2Settings>) => void;
-  /** Update responsive overrides for a V2 section */
-  updateSectionV2Responsive: (sectionKey: string, responsive: PageSectionV2["responsive"]) => void;
-  /** Add a block to a V2 section column, optionally at a specific index */
-  addBlockV2: (sectionKey: string, columnKey: string, blockType: BlockType, insertIndex?: number) => void;
-  /** Select a V2 column */
-  selectColumnV2: (sectionKey: string | null, columnKey: string | null) => void;
-  /** Update enter animation for a V2 column (Session 117) */
-  updateColumnEnterAnimation: (sectionKey: string, colKey: string, config: import("../../lib/animation/enter-types").EnterAnimationConfig | undefined) => void;
-
-  // Debounced update (no snapshot per keystroke)
-  updateBlockDebounced: (blockKey: string, updates: Partial<ContentBlock>) => void;
-
-  // Editor mode
-  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>;
-  /** Insert a custom section instance reference into the page rows */
-  addCustomSectionInstance: (id: string, slug: string, title: string, afterRowKey?: string | null) => void;
-  /** Detach a custom section instance — replaces it with a copy of the section data (inline V2 section) */
-  detachCustomSectionInstance: (instanceKey: string, sectionData: PageSectionV2) => void;
-  /** Update the cached title on a custom section instance (cosmetic sync, Session 110) */
-  updateCustomSectionInstanceTitle: (instanceKey: string, newTitle: string) => void;
-  /** Update per-instance section settings overrides (Session 130) */
-  updateCustomSectionInstanceSettings: (instanceKey: string, updates: Partial<SectionV2Settings>) => void;
-  /** Cache base settings from a fetched custom section (for SortableRow merge) */
-  cacheCustomSectionSettings: (sectionId: string, settings: SectionV2Settings) => void;
-
-  // ---- Parallax Group operations (Session 123) ----
-  /** Add a new ParallaxGroup with 1 empty slide */
-  addParallaxGroup: (afterRowKey?: string | null) => void;
-  /** Add a new empty slide to a parallax group */
-  addParallaxSlide: (groupKey: string) => void;
-  /** Remove a slide from a parallax group (minimum 1 enforced) */
-  removeParallaxSlide: (groupKey: string, slideKey: string) => void;
-  /** Reorder a slide up or down within its group */
-  moveParallaxSlide: (groupKey: string, slideKey: string, direction: "up" | "down") => void;
-  /** Update background fields on a parallax slide */
-  updateParallaxSlideBackground: (groupKey: string, slideKey: string, fields: Partial<import("../../lib/sanity/types").ParallaxSlideV2>) => void;
-  /** Update group-level settings (transition effect, snap, etc.) */
-  updateParallaxGroupSettings: (groupKey: string, fields: Partial<Pick<import("../../lib/sanity/types").ParallaxGroup, "transition_effect" | "snap_enabled" | "parallax_intensity">>) => void;
-
-  // ---- Cover Section operations (Session 176) ----
-  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;
-
-  // Page-level settings
-  updatePageSettings: (settings: Partial<PageSettings>) => void;
-  applyGlobalStyles: () => Promise<void>;
-
-  // Canvas
-  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;
-
-  // Color picker live preview (Phase 4)
-  setColorPickerPreview: (preview: BuilderState["colorPickerPreview"]) => void;
-  clearColorPickerPreview: () => void;
-}
+import type {
+  MetaSlice,
+  MetaSliceState,
+  MetaSliceActions,
+  SectionSlice,
+  SectionSliceState,
+  SectionSliceActions,
+  BlockSlice,
+  BlockSliceActions,
+  CanvasSlice,
+  CanvasSliceState,
+  CanvasSliceActions,
+  CoverSlice,
+  CoverSliceActions,
+  SelectionSlice,
+  SelectionSliceState,
+  SelectionSliceActions,
+  HistorySlice,
+  HistorySliceState,
+  HistorySliceActions,
+} from "./types-slices";
+
+export type {
+  MetaSlice,
+  MetaSliceState,
+  MetaSliceActions,
+  SectionSlice,
+  SectionSliceState,
+  SectionSliceActions,
+  BlockSlice,
+  BlockSliceActions,
+  CanvasSlice,
+  CanvasSliceState,
+  CanvasSliceActions,
+  CoverSlice,
+  CoverSliceActions,
+  SelectionSlice,
+  SelectionSliceState,
+  SelectionSliceActions,
+  HistorySlice,
+  HistorySliceState,
+  HistorySliceActions,
+};
+
+/**
+ * Flat state object composed of all slice states.
+ * Runtime shape is unchanged from pre-Session 183 — a single level
+ * of properties. See `./types-slices.ts` for slice boundaries.
+ */
+export type BuilderState = MetaSliceState &
+  SectionSliceState &
+  CanvasSliceState &
+  SelectionSliceState &
+  HistorySliceState;
+
+/**
+ * All store actions, composed from per-slice action types.
+ * Runtime shape is unchanged. See `./types-slices.ts` for slice owners.
+ */
+export type BuilderActions = MetaSliceActions &
+  SectionSliceActions &
+  BlockSliceActions &
+  CanvasSliceActions &
+  CoverSliceActions &
+  SelectionSliceActions &
+  HistorySliceActions;
 
 export type BuilderStore = BuilderState & BuilderActions;

package/lib/version.ts

@@ -6,4 +6,4 @@
  * Exposed as a plain constant so it can be imported without reading
  * package.json at runtime.
  */
-export const ANDAMI_VERSION = "0.4.1";
+export const ANDAMI_VERSION = "0.4.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphika/andami",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Visual Page Builder — core library. A reusable website builder with visual editing, CMS integration, and asset management.",
   "type": "module",
   "license": "MIT",