@morphika/webframe 0.1.0

package/lib/builder/serializer.ts

@@ -0,0 +1,845 @@
+/**
+ * Bidirectional serializer: Builder state ↔ Sanity document.
+ *
+ * - `documentToState(doc)` — Sanity document → Zustand state shape
+ * - `stateToDocument(state)` — Zustand state → Sanity-compatible document
+ *
+ * Handles _key generation for objects that lack keys,
+ * normalizes missing fields, and strips undefined values.
+ *
+ * Session 76: Added PageSection support + auto-migration from old matryoshka format.
+ */
+
+import type { Page, ContentBlock, ContentItem, PageSection, PageSectionV2, SectionBlock, SectionColumn, SectionV2Settings, CustomSectionInstance, ParallaxGroup } from "../../lib/sanity/types";
+import { isPageSection, isPageSectionV2, isCustomSectionInstance, isParallaxGroup } from "../../lib/sanity/types";
+import type { BuilderState, PageSettings } from "./types";
+import { isSectionBlockType } from "./types";
+import { generateKey } from "./utils";
+import { DEFAULT_BG_COLOR, DEFAULT_TEXT_COLOR, DEFAULT_GRID_WIDTH } from "./constants";
+import type { EnterAnimationConfig } from "../../lib/animation/enter-types";
+
+// ============================================
+// Project Grid v1 → v2 Migration (Session 105)
+// ============================================
+
+/** Map v1 string gap values to pixel numbers */
+const GAP_V1_MAP: Record<string, number> = {
+  small: 8,
+  medium: 16,
+  large: 32,
+  xlarge: 48,
+};
+
+/**
+ * Detect and migrate a v1 projectGridBlock to v2 format.
+ * v1 is identified by the presence of `grid_layout` (string field).
+ * v2 is identified by the presence of `columns` (number field).
+ * If already v2 or not a projectGridBlock, returns as-is.
+ */
+function migrateProjectGridV1ToV2(block: Record<string, unknown>): void {
+  if (block._type !== "projectGridBlock") return;
+
+  // Already v2: has `columns` as a number
+  if (typeof block.columns === "number") return;
+
+  // Not v1 either (fresh block without grid_layout) — apply defaults
+  if (!block.grid_layout && typeof block.columns !== "number") {
+    block.columns = 3;
+    block.aspect_ratios = ["16/9"];
+    block.gap_v = 16;
+    block.gap_h = 16;
+    block.hover_effect = block.hover_effect || "scale";
+    block.show_subtitle = block.show_subtitle ?? true;
+    block.border_radius = 0;
+    block.video_mode = "off";
+    return;
+  }
+
+  // ─── v1 → v2 migration ───
+
+  // columns: columns_desktop → columns (clamp 1–6)
+  const colDesktop = typeof block.columns_desktop === "number" ? block.columns_desktop : 2;
+  block.columns = Math.max(1, Math.min(6, colDesktop));
+
+  // gap: string → gap_v + gap_h (both same value)
+  const gapStr = typeof block.gap === "string" ? block.gap : "large";
+  const gapPx = GAP_V1_MAP[gapStr] ?? 32;
+  block.gap_v = gapPx;
+  block.gap_h = gapPx;
+
+  // card_aspect_ratio → aspect_ratios
+  const oldRatio = typeof block.card_aspect_ratio === "string" ? block.card_aspect_ratio : "16/9";
+  if (oldRatio === "random") {
+    block.aspect_ratios = ["16/9", "1/1", "9/16"];
+  } else {
+    block.aspect_ratios = [oldRatio];
+  }
+
+  // hover_effect: "overlay" → "scale", rest 1:1
+  const oldHover = typeof block.hover_effect === "string" ? block.hover_effect : "overlay";
+  if (oldHover === "overlay") {
+    block.hover_effect = "scale";
+  }
+  // "scale" and "none" pass through
+
+  // border_radius: string → number
+  const oldRadius = block.card_border_radius;
+  block.border_radius = typeof oldRadius === "string" ? (parseInt(oldRadius, 10) || 0) : 0;
+
+  // video: video_autoloop + video_hover → video_mode
+  if (block.video_autoloop === true) {
+    block.video_mode = "autoloop";
+  } else if (block.video_hover === true) {
+    block.video_mode = "hover";
+  } else {
+    block.video_mode = "off";
+  }
+
+  // show_subtitle: direct copy (default true)
+  block.show_subtitle = block.show_subtitle ?? true;
+
+  // ─── Clean up v1 fields (not needed in builder state) ───
+  delete block.grid_layout;
+  delete block.gap;
+  delete block.auto_columns;
+  delete block.card_size;
+  delete block.columns_desktop;
+  delete block.card_aspect_ratio;
+  delete block.card_border_radius;
+  delete block.video_hover;
+  delete block.video_autoloop;
+}
+
+/**
+ * Normalize animation fields on a block during read.
+ * Post-migration (Session 122): only new fields exist in Sanity.
+ * This is a no-op now but kept as a hook point for future needs.
+ */
+function normalizeBlockAnimationFields(_block: Record<string, unknown>): void {
+  // No-op: migration completed in Session 122.
+  // All documents now use enter_animation / hover_effect directly.
+}
+
+// ============================================
+// Constants
+// ============================================
+
+/**
+ * Map block types to section_type values.
+ * Used during migration and validation to ensure consistent section type naming.
+ */
+const SECTION_TYPE_MAP: Record<string, string> = {
+  projectGridBlock: "projectGrid",
+};
+
+// ============================================
+// Sanity Document → Builder State
+// ============================================
+
+/**
+ * Ensure every item has a _key.
+ * Sanity sometimes omits _key on newly created objects.
+ */
+function ensureKeys<T extends { _key?: string }>(items: T[] | undefined): (T & { _key: string })[] {
+  if (!items) return [];
+  return items.map((item) => ({
+    ...item,
+    _key: item._key || generateKey(),
+  }));
+}
+
+
+/**
+ * Normalize block layout responsive overrides.
+ * Cleans up empty/invalid values within responsive.tablet.layout and responsive.phone.layout.
+ * Strips empty viewport objects and empty layout sub-objects.
+ */
+/**
+ * Clean a layout object by removing empty, null, and empty-string values.
+ * Returns undefined if the cleaned object has no keys.
+ */
+function cleanLayoutObject(obj: Record<string, unknown>): Record<string, unknown> | undefined {
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    if (val !== undefined && val !== null && val !== "") {
+      cleaned[key] = val;
+    }
+  }
+  return Object.keys(cleaned).length > 0 ? cleaned : undefined;
+}
+
+/**
+ * Normalize block layout responsive overrides.
+ * Cleans up empty/invalid values within responsive.tablet.layout and responsive.phone.layout.
+ * Strips empty viewport objects and empty layout sub-objects.
+ */
+function normalizeBlockResponsive(
+  responsive: Record<string, Record<string, unknown>> | undefined
+): Record<string, Record<string, unknown>> | undefined {
+  if (!responsive) return undefined;
+
+  const result: Record<string, Record<string, unknown>> = {};
+
+  for (const vp of ["tablet", "phone"] as const) {
+    const vpOverrides = responsive[vp];
+    if (!vpOverrides || typeof vpOverrides !== "object") continue;
+
+    const cleaned: Record<string, unknown> = {};
+
+    for (const [key, val] of Object.entries(vpOverrides)) {
+      if (val === undefined || val === null) continue;
+
+      if (key === "layout" && typeof val === "object" && val !== null) {
+        const layoutCleaned = cleanLayoutObject(val as Record<string, unknown>);
+        if (layoutCleaned) cleaned.layout = layoutCleaned;
+        continue;
+      }
+
+      // Other block properties (non-layout)
+      if (typeof val === "string" && val.trim() === "") continue;
+      cleaned[key] = val;
+    }
+
+    if (Object.keys(cleaned).length > 0) {
+      result[vp] = cleaned;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+
+function normalizePageSection(section: Partial<PageSection> & { _key: string }): PageSection {
+  const ensuredBlock = ensureKeys((section.block || []) as SectionBlock[]) as (SectionBlock & { _key: string })[];
+  const ensuredBlockType = ensuredBlock[0]?._type || "projectGridBlock";
+  // BUG-022 fix: Preserve the original section_type even if unknown.
+  // Only default when the field is missing entirely (new sections).
+  const sectionType = section.section_type || (SECTION_TYPE_MAP[ensuredBlockType] || "projectGrid");
+
+  // Warn on unknown types but don't override — future types should survive round-trips
+  if (!Object.values(SECTION_TYPE_MAP).includes(sectionType)) {
+    console.warn(`[Serializer] Unknown section_type: ${sectionType} — preserving as-is`);
+  }
+
+  // Auto-migrate projectGridBlock v1 → v2
+  if (ensuredBlock[0]) {
+    migrateProjectGridV1ToV2(ensuredBlock[0] as unknown as Record<string, unknown>);
+  }
+
+  // Session 117: Migrate animation fields on section blocks
+  if (ensuredBlock[0]) {
+    normalizeBlockAnimationFields(ensuredBlock[0] as unknown as Record<string, unknown>);
+  }
+
+  return {
+    _type: "pageSection",
+    _key: section._key,
+    section_type: sectionType as import("@/lib/sanity/types").PageSectionType,
+    block: [ensuredBlock[0] || { _type: ensuredBlockType, _key: generateKey() }] as [SectionBlock],
+    settings: section.settings || {},
+    // BUG-013 fix: preserve responsive overrides for sections
+    ...(section.responsive ? { responsive: section.responsive } : {}),
+  };
+}
+
+/**
+ * Normalize a PageSectionV2 from Sanity data into the builder's shape.
+ * Ensures all columns have _keys, validates grid positions, and fills defaults.
+ */
+function normalizePageSectionV2(section: Partial<PageSectionV2> & { _key: string }): PageSectionV2 {
+  const rawColumns = ensureKeys((section.columns || []) as Array<Partial<SectionColumn> & { _key?: string }>);
+
+  const columns: SectionColumn[] = rawColumns.map((col) => {
+    const colRecord = col as unknown as Record<string, unknown>;
+    // Migrate column-level enter_animation (new field, no old equivalent for columns)
+    const colEnterAnimation = colRecord.enter_animation as EnterAnimationConfig | undefined;
+
+    return {
+      _key: col._key || generateKey(),
+      grid_column: col.grid_column || 1,
+      grid_row: col.grid_row || 1,
+      span: col.span || 12,
+      blocks: ensureKeys(col.blocks || []).map((b) => {
+        const blockRecord = b as unknown as Record<string, unknown>;
+
+        // Migrate animation fields on blocks (Session 117)
+        normalizeBlockAnimationFields(blockRecord);
+
+        const blockResponsive = normalizeBlockResponsive(
+          blockRecord.responsive as Record<string, Record<string, unknown>> | undefined
+        );
+        if (blockResponsive) {
+          return { ...b, responsive: blockResponsive } as ContentBlock;
+        }
+        if (blockRecord.responsive && !blockResponsive) {
+          const { responsive: _, ...rest } = blockRecord;
+          return rest as unknown as ContentBlock;
+        }
+        return b as ContentBlock;
+      }),
+      ...(colEnterAnimation ? { enter_animation: colEnterAnimation } : {}),
+    };
+  });
+
+  const rawSettings = section.settings || {} as Partial<SectionV2Settings>;
+
+  return {
+    _type: "pageSectionV2",
+    _key: section._key,
+    section_type: "empty-v2",
+    columns,
+    settings: {
+      preset: rawSettings.preset || "full",
+      grid_columns: rawSettings.grid_columns || 12,
+      col_gap: rawSettings.col_gap ?? 20,
+      row_gap: rawSettings.row_gap ?? 20,
+      spacing_top: rawSettings.spacing_top,
+      spacing_right: rawSettings.spacing_right,
+      spacing_bottom: rawSettings.spacing_bottom,
+      spacing_left: rawSettings.spacing_left,
+      offset_top: rawSettings.offset_top,
+      offset_right: rawSettings.offset_right,
+      offset_bottom: rawSettings.offset_bottom,
+      offset_left: rawSettings.offset_left,
+      background_color: rawSettings.background_color,
+      background_opacity: rawSettings.background_opacity,
+      background_image: rawSettings.background_image,
+      background_size: rawSettings.background_size,
+      background_position: rawSettings.background_position,
+      background_repeat: rawSettings.background_repeat,
+      border_color: rawSettings.border_color,
+      border_width: rawSettings.border_width,
+      border_style: rawSettings.border_style,
+      border_sides: rawSettings.border_sides,
+      border_radius: rawSettings.border_radius,
+      enter_animation: rawSettings.enter_animation,
+      stagger: rawSettings.stagger,
+    },
+    ...(section.responsive ? { responsive: section.responsive } : {}),
+  };
+}
+
+// ============================================
+// ParallaxGroup normalization (Session 123)
+// ============================================
+
+/**
+ * Normalize a ParallaxGroup from Sanity data into the builder's shape.
+ * Each slide contains V2 section data (columns + settings).
+ */
+function normalizeParallaxGroup(group: Partial<ParallaxGroup> & { _key: string }): ParallaxGroup {
+  const rawSlides = ensureKeys(
+    (group.slides || []) as Array<Partial<import("@/lib/sanity/types").ParallaxSlideV2> & { _key?: string }>
+  );
+
+  const slides: import("@/lib/sanity/types").ParallaxSlideV2[] = rawSlides.map((slide) => {
+    // Normalize the V2 columns within each slide (reuse existing logic)
+    const slideKey = slide._key || generateKey();
+    const tempV2: Partial<PageSectionV2> & { _key: string } = {
+      _key: slideKey,
+      columns: slide.columns as SectionColumn[] | undefined,
+      settings: slide.section_settings as SectionV2Settings | undefined,
+    };
+    const normalizedV2 = normalizePageSectionV2(tempV2);
+
+    return {
+      _key: slideKey,
+      _type: "parallaxSlide" as const,
+      background_type: slide.background_type || "image",
+      background_image: slide.background_image,
+      background_video: slide.background_video,
+      background_position: slide.background_position || "center center",
+      background_overlay_color: slide.background_overlay_color || "#000000",
+      background_overlay_opacity: slide.background_overlay_opacity ?? 0,
+      nav_color: slide.nav_color,
+      columns: normalizedV2.columns,
+      section_settings: normalizedV2.settings,
+    };
+  });
+
+  return {
+    _type: "parallaxGroup",
+    _key: group._key,
+    slides,
+    transition_effect: group.transition_effect || "parallax",
+    snap_enabled: group.snap_enabled ?? true,
+    parallax_intensity: group.parallax_intensity ?? 0.4,
+  };
+}
+
+/**
+ * Serialize a ParallaxGroup for Sanity.
+ */
+function serializeParallaxGroup(group: ParallaxGroup): Record<string, unknown> {
+  return {
+    _key: group._key,
+    _type: "parallaxGroup",
+    transition_effect: group.transition_effect,
+    snap_enabled: group.snap_enabled,
+    parallax_intensity: group.parallax_intensity,
+    slides: group.slides.map((slide) => {
+      // Serialize the V2 section data within each slide
+      const tempV2: PageSectionV2 = {
+        _type: "pageSectionV2",
+        _key: slide._key,
+        section_type: "empty-v2",
+        columns: slide.columns,
+        settings: slide.section_settings,
+      };
+      const serializedV2 = serializePageSectionV2(tempV2);
+
+      return stripUndefined({
+        _key: slide._key,
+        _type: "parallaxSlide",
+        background_type: slide.background_type,
+        background_image: slide.background_image,
+        background_video: slide.background_video,
+        background_position: slide.background_position,
+        background_overlay_color: slide.background_overlay_color,
+        background_overlay_opacity: slide.background_overlay_opacity,
+        nav_color: slide.nav_color,
+        columns: serializedV2.columns,
+        section_settings: serializedV2.settings,
+      });
+    }),
+  };
+}
+
+/**
+ * Normalize a content item (PageSection, PageSectionV2, ParallaxGroup, etc.).
+ */
+function migrateContentItem(item: Record<string, unknown>): ContentItem {
+  // PageSection — normalize and return
+  if (item._type === "pageSection") {
+    return normalizePageSection(item as unknown as Partial<PageSection> & { _key: string });
+  }
+
+  // PageSectionV2 — normalize and return
+  if (item._type === "pageSectionV2") {
+    return normalizePageSectionV2(item as unknown as Partial<PageSectionV2> & { _key: string });
+  }
+
+  // CustomSectionInstance — pass through reference + per-instance overrides (Session 107, 130)
+  if (item._type === "customSectionInstance") {
+    const raw = item as unknown as Record<string, unknown>;
+    return {
+      _type: "customSectionInstance",
+      _key: (item._key as string) || generateKey(),
+      custom_section_id: (item.custom_section_id as string) || "",
+      custom_section_slug: (item.custom_section_slug as string) || "",
+      custom_section_title: (item.custom_section_title as string) || "Untitled",
+      ...(raw.settings_overrides && typeof raw.settings_overrides === "object"
+        ? { settings_overrides: raw.settings_overrides as Partial<SectionV2Settings> }
+        : {}),
+      ...(raw.responsive_overrides && typeof raw.responsive_overrides === "object"
+        ? { responsive_overrides: raw.responsive_overrides as PageSectionV2["responsive"] }
+        : {}),
+    } as CustomSectionInstance;
+  }
+
+  // ParallaxGroup — normalize slides (Session 123)
+  if (item._type === "parallaxGroup") {
+    return normalizeParallaxGroup(item as unknown as Partial<ParallaxGroup> & { _key: string });
+  }
+
+  // Unknown type — warn and skip
+  console.warn(`[Serializer] Unknown content item type: ${item._type}, skipping`);
+  // Return a dummy PageSectionV2 as fallback
+  return normalizePageSectionV2({ _key: generateKey() } as unknown as Partial<PageSectionV2> & { _key: string });
+}
+
+/**
+ * Convert a Sanity `page` document into the builder's state shape.
+ */
+export function documentToState(doc: Page): Omit<BuilderState, "isDirty" | "isSaving" | "saveError" | "lastSavedAt" | "selectedRowKey" | "selectedColumnKey" | "selectedBlockKey" | "_history" | "_future" | "_isTimeTraveling" | "_originalSlug" | "previewMode" | "canvasZoom" | "canvasPanX" | "canvasPanY" | "canvasTool" | "activeViewport" | "editorMode" | "customSectionSlug" | "customSectionTitle" | "savedPageState"> {
+  const docRecord = doc as unknown as Record<string, unknown>;
+  const pageSettings = docRecord.page_settings as Record<string, unknown> | undefined;
+
+  // BUG-014 fix: Track whether the Sanity document actually had page_settings saved.
+  // This lets applyGlobalStyles() know not to overwrite user-chosen colors.
+  const hasDocumentPageSettings = !!pageSettings;
+
+  // nav_color: free hex string (or legacy NavColorVariant — both accepted)
+  const nav_color = (typeof pageSettings?.nav_color === "string")
+    ? (pageSettings.nav_color as string)
+    : "";
+
+  // Process content_rows with auto-migration
+  const rawRows = ensureKeys((doc.content_rows || []) as Array<{ _key?: string }>);
+  const rows: ContentItem[] = rawRows.map((item) =>
+    migrateContentItem(item as unknown as Record<string, unknown>)
+  );
+
+  return {
+    pageId: doc._id,
+    pageTitle: doc.title || "",
+    pageSlug: doc.slug?.current || "",
+    pageType: doc.page_type || "page",
+    metadata: doc.metadata || {},
+    publishedAt: doc.published_at || null,
+    draftMode: doc.draft_mode ?? true,
+    rows,
+    _customSectionCache: {},
+    // BUG-014 fix: flag whether colors came from the document
+    _hasDocumentPageSettings: hasDocumentPageSettings,
+    pageSettings: {
+      background_color: (pageSettings?.background_color as string) || DEFAULT_BG_COLOR,
+      text_color: (pageSettings?.text_color as string) || DEFAULT_TEXT_COLOR,
+      nav_color,
+      enter_animation: pageSettings?.enter_animation as PageSettings["enter_animation"],
+      nav_entrance_animation: (pageSettings?.nav_entrance_animation as PageSettings["nav_entrance_animation"]) || undefined,
+      nav_entrance_duration: (pageSettings?.nav_entrance_duration as number) || undefined,
+      nav_entrance_delay: (pageSettings?.nav_entrance_delay as number) || undefined,
+      nav_entrance_disabled: (pageSettings?.nav_entrance_disabled as boolean) || undefined,
+    },
+    // Grid settings are loaded separately via applyGlobalStyles(), not from the page document.
+    // Provide defaults here to satisfy the type; they'll be overwritten on init.
+    gridSettings: {
+      width: DEFAULT_GRID_WIDTH,
+      outer_padding: "30",
+      gutter_desktop: "30",
+      gutter_responsive: "30",
+      gutter_phone: "16",
+    },
+    selectedProjectCardKey: null,
+  };
+}
+
+// ============================================
+// Builder State → Sanity Document
+// ============================================
+
+/**
+ * Strip undefined values from an object (Sanity rejects undefined).
+ */
+function stripUndefined<T extends Record<string, unknown>>(obj: T): T {
+  const result = {} as T;
+  for (const key of Object.keys(obj) as (keyof T)[]) {
+    if (obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+function serializeBlock(block: ContentBlock): ContentBlock {
+  const serialized = stripUndefined({ ...block }) as ContentBlock;
+
+  // Normalize block responsive data (clean up empty layout overrides)
+  const blockRecord = serialized as unknown as Record<string, unknown>;
+  if (blockRecord.responsive) {
+    const normalized = normalizeBlockResponsive(
+      blockRecord.responsive as Record<string, Record<string, unknown>>
+    );
+    if (normalized) {
+      blockRecord.responsive = normalized;
+    } else {
+      delete blockRecord.responsive;
+    }
+  }
+
+  // Normalize block layout responsive if present (layout.responsive sub-object)
+  if (blockRecord.layout && typeof blockRecord.layout === "object") {
+    const layout = blockRecord.layout as Record<string, unknown>;
+    // Strip undefined/null/empty string values from layout
+    const cleanLayout: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(layout)) {
+      if (v !== undefined && v !== null && v !== "") {
+        cleanLayout[k] = v;
+      }
+    }
+    if (Object.keys(cleanLayout).length > 0) {
+      blockRecord.layout = cleanLayout;
+    } else {
+      delete blockRecord.layout;
+    }
+  }
+
+  // Session 117: Ensure new animation fields are written
+  // enter_animation / hover_effect are already on the block from the store.
+  // Clean empty animation configs (preset=none or no preset → remove to keep Sanity clean)
+  const enterAnim = blockRecord.enter_animation as Record<string, unknown> | undefined;
+  if (enterAnim && (!enterAnim.preset || enterAnim.preset === "none")) {
+    delete blockRecord.enter_animation;
+  }
+  const hoverEff = blockRecord.hover_effect;
+  if (hoverEff && typeof hoverEff === "object") {
+    const he = hoverEff as Record<string, unknown>;
+    if (!he.preset || he.preset === "none") {
+      delete blockRecord.hover_effect;
+    }
+  }
+
+  return serialized;
+}
+
+/**
+ * Normalize section responsive overrides for serialization (save path).
+ * Strips undefined/null/empty string values and removes empty viewport objects.
+ */
+function normalizeSectionResponsiveForSerialize(
+  responsive: PageSection["responsive"] | undefined
+): PageSection["responsive"] | undefined {
+  if (!responsive) return undefined;
+
+  const result: NonNullable<PageSection["responsive"]> = {};
+
+  for (const vp of ["tablet", "phone"] as const) {
+    const overrides = responsive[vp];
+    if (!overrides || typeof overrides !== "object") continue;
+
+    const cleaned: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(overrides)) {
+      if (val === undefined || val === null) continue;
+      if (typeof val === "string" && val.trim() === "") continue;
+      cleaned[key] = val;
+    }
+
+    if (Object.keys(cleaned).length > 0) {
+      result[vp] = cleaned as typeof result[typeof vp];
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function serializePageSection(section: PageSection): Record<string, unknown> {
+  const s = section.settings;
+  return {
+    _key: section._key,
+    _type: "pageSection",
+    section_type: section.section_type,
+    block: (section.block || []).map((b) => serializeBlock(b as ContentBlock)),
+    // BUG-013 fix: persist responsive overrides for sections (normalized: strips empty values)
+    responsive: normalizeSectionResponsiveForSerialize(section.responsive),
+    settings: s ? stripUndefined({
+      background_color: s.background_color,
+      background_opacity: s.background_opacity,
+      background_image: s.background_image,
+      background_size: s.background_size,
+      background_position: s.background_position,
+      background_repeat: s.background_repeat,
+      spacing_top: s.spacing_top,
+      spacing_right: s.spacing_right,
+      spacing_bottom: s.spacing_bottom,
+      spacing_left: s.spacing_left,
+      offset_top: s.offset_top,
+      offset_right: s.offset_right,
+      offset_bottom: s.offset_bottom,
+      offset_left: s.offset_left,
+      border_color: s.border_color,
+      border_width: s.border_width,
+      border_style: s.border_style,
+      border_sides: s.border_sides,
+      border_radius: s.border_radius,
+      enter_animation: s.enter_animation,
+    }) : undefined,
+  };
+}
+
+/**
+ * Normalize V2 section responsive overrides for serialization.
+ */
+function normalizeSectionV2ResponsiveForSerialize(
+  responsive: PageSectionV2["responsive"] | undefined
+): PageSectionV2["responsive"] | undefined {
+  if (!responsive) return undefined;
+
+  const result: NonNullable<PageSectionV2["responsive"]> = {};
+
+  for (const vp of ["tablet", "phone"] as const) {
+    const overrides = responsive[vp];
+    if (!overrides || typeof overrides !== "object") continue;
+
+    const cleaned: Record<string, unknown> = {};
+
+    // Column overrides
+    if (overrides.columns && Array.isArray(overrides.columns) && overrides.columns.length > 0) {
+      const cleanedCols = overrides.columns.filter((co) => {
+        // Only keep overrides that have at least one meaningful value
+        return co.grid_column != null || co.grid_row != null || co.span != null;
+      });
+      if (cleanedCols.length > 0) {
+        cleaned.columns = cleanedCols;
+      }
+    }
+
+    // Settings overrides
+    if (overrides.settings) {
+      const settingsCleaned: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(overrides.settings)) {
+        if (val === undefined || val === null) continue;
+        if (typeof val === "string" && val.trim() === "") continue;
+        settingsCleaned[key] = val;
+      }
+      if (Object.keys(settingsCleaned).length > 0) {
+        cleaned.settings = settingsCleaned;
+      }
+    }
+
+    if (Object.keys(cleaned).length > 0) {
+      result[vp] = cleaned as typeof result[typeof vp];
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function serializePageSectionV2(section: PageSectionV2): Record<string, unknown> {
+  const s = section.settings;
+  return {
+    _key: section._key,
+    _type: "pageSectionV2",
+    section_type: section.section_type,
+    columns: section.columns.map((col) => {
+      const colData: Record<string, unknown> = {
+        _key: col._key,
+        _type: "sectionColumn",
+        grid_column: col.grid_column,
+        grid_row: col.grid_row,
+        span: col.span,
+        blocks: col.blocks.map(serializeBlock),
+      };
+      // Session 117: Column-level enter animation
+      if (col.enter_animation && col.enter_animation.preset && col.enter_animation.preset !== "none") {
+        colData.enter_animation = col.enter_animation;
+      }
+      return colData;
+    }),
+    settings: s ? stripUndefined({
+      preset: s.preset,
+      grid_columns: s.grid_columns,
+      col_gap: s.col_gap,
+      row_gap: s.row_gap,
+      spacing_top: s.spacing_top,
+      spacing_right: s.spacing_right,
+      spacing_bottom: s.spacing_bottom,
+      spacing_left: s.spacing_left,
+      offset_top: s.offset_top,
+      offset_right: s.offset_right,
+      offset_bottom: s.offset_bottom,
+      offset_left: s.offset_left,
+      background_color: s.background_color,
+      background_opacity: s.background_opacity,
+      background_image: s.background_image,
+      background_size: s.background_size,
+      background_position: s.background_position,
+      background_repeat: s.background_repeat,
+      border_color: s.border_color,
+      border_width: s.border_width,
+      border_style: s.border_style,
+      border_sides: s.border_sides,
+      border_radius: s.border_radius,
+      enter_animation: (s.enter_animation?.preset && s.enter_animation.preset !== "none")
+        ? s.enter_animation : undefined,
+      stagger: s.stagger,
+    }) : undefined,
+    responsive: normalizeSectionV2ResponsiveForSerialize(section.responsive),
+  };
+}
+
+/**
+ * Serialize a content item (PageSection or PageSectionV2) for Sanity.
+ */
+function serializeContentItem(item: ContentItem): Record<string, unknown> {
+  if (isPageSection(item)) {
+    return serializePageSection(item);
+  }
+  if (isPageSectionV2(item)) {
+    return serializePageSectionV2(item);
+  }
+  // CustomSectionInstance — serialize reference + per-instance overrides (Session 107, 130)
+  if (isCustomSectionInstance(item)) {
+    const out: Record<string, unknown> = {
+      _type: "customSectionInstance",
+      _key: item._key,
+      custom_section_id: item.custom_section_id,
+      custom_section_slug: item.custom_section_slug,
+      custom_section_title: item.custom_section_title,
+    };
+    if (item.settings_overrides && Object.keys(item.settings_overrides).length > 0) {
+      out.settings_overrides = item.settings_overrides;
+    }
+    if (item.responsive_overrides) {
+      // Only write if there's actual data (at least one viewport with content)
+      const r = item.responsive_overrides;
+      const hasTablet = r.tablet && (r.tablet.settings && Object.keys(r.tablet.settings).length > 0 || r.tablet.columns && r.tablet.columns.length > 0);
+      const hasPhone = r.phone && (r.phone.settings && Object.keys(r.phone.settings).length > 0 || r.phone.columns && r.phone.columns.length > 0);
+      if (hasTablet || hasPhone) {
+        out.responsive_overrides = item.responsive_overrides;
+      }
+    }
+    return out;
+  }
+  // ParallaxGroup — serialize slides with their V2 section data (Session 123)
+  if (isParallaxGroup(item)) {
+    return serializeParallaxGroup(item);
+  }
+  // Should never reach here
+  throw new Error(`[Serializer] Unknown content item type during serialization`);
+}
+
+/**
+ * Convert the builder's state into a Sanity-compatible document payload.
+ * Used by the save API route.
+ */
+export function stateToDocument(
+  state: Pick<BuilderState, "pageId" | "pageTitle" | "pageSlug" | "pageType" | "metadata" | "draftMode" | "publishedAt" | "rows" | "pageSettings">
+): Record<string, unknown> {
+  // BUG-008 fix: Always persist page_settings when ANY field has a non-default value.
+  // Previously, animation configs with preset='none' but other fields set (intensity, easing)
+  // would be stripped. Now we check for the presence of any animation config object,
+  // not just whether its preset is 'none'.
+  const ps = state.pageSettings;
+  const bgColor = ps?.background_color || DEFAULT_BG_COLOR;
+  const txtColor = ps?.text_color || DEFAULT_TEXT_COLOR;
+  const navColor = ps?.nav_color || "";
+
+  const enterAnim = ps?.enter_animation;
+  const hasEnterAnimation = enterAnim && enterAnim.preset && enterAnim.preset !== 'none';
+
+  const navEntranceAnimation = ps?.nav_entrance_animation || "";
+  const navEntranceDuration = ps?.nav_entrance_duration;
+  const navEntranceDelay = ps?.nav_entrance_delay;
+  const navEntranceDisabled = ps?.nav_entrance_disabled;
+
+  // Persist whenever any value differs from deserialisation defaults
+  const hasPageSettings =
+    bgColor !== DEFAULT_BG_COLOR ||
+    txtColor !== DEFAULT_TEXT_COLOR ||
+    !!navColor ||
+    !!hasEnterAnimation ||
+    !!enterAnim ||
+    !!navEntranceAnimation ||
+    !!navEntranceDuration ||
+    !!navEntranceDelay ||
+    !!navEntranceDisabled;
+
+  return stripUndefined({
+    _id: state.pageId,
+    _type: "page",
+    title: state.pageTitle,
+    slug: { _type: "slug", current: state.pageSlug },
+    page_type: state.pageType,
+    content_rows: state.rows.map(serializeContentItem),
+    metadata: stripUndefined({
+      seo_title: state.metadata.seo_title,
+      seo_description: state.metadata.seo_description,
+      og_image_path: state.metadata.og_image_path,
+    }),
+    page_settings: hasPageSettings
+      ? {
+          background_color: bgColor,
+          text_color: txtColor,
+          nav_color: navColor || undefined,
+          enter_animation: hasEnterAnimation ? enterAnim : undefined,
+          nav_entrance_animation: navEntranceAnimation || undefined,
+          nav_entrance_duration: navEntranceDuration || undefined,
+          nav_entrance_delay: navEntranceDelay || undefined,
+          nav_entrance_disabled: navEntranceDisabled || undefined,
+        }
+      : undefined,
+    draft_mode: state.draftMode,
+    published_at: state.publishedAt,
+  });
+}