@morphika/andami 0.1.8 → 0.1.9

package/lib/builder/serializer/normalizers.ts

@@ -0,0 +1,278 @@
+/**
+ * Document → State normalization functions.
+ * Converts Sanity page documents into the builder's Zustand state shape.
+ *
+ * Extracted from serializer.ts in Session 162.
+ */
+
+import type { Page, ContentBlock, ContentItem, PageSection, PageSectionV2, SectionBlock, SectionColumn, SectionV2Settings, CustomSectionInstance, ParallaxGroup } from "../../../lib/sanity/types";
+import type { BuilderState, PageSettings } 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";
+
+import { ensureKeys, normalizeBlockResponsive, SECTION_TYPE_MAP } from "./shared";
+import { migrateProjectGridV1ToV2, normalizeBlockAnimationFields } from "./migrations";
+
+// ============================================
+// Section Normalizers
+// ============================================
+
+export 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.
+ */
+export 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).
+ */
+export 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,
+  };
+}
+
+/**
+ * Normalize a content item (PageSection, PageSectionV2, ParallaxGroup, etc.).
+ */
+export 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,
+    colorPickerPreview: null,
+  };
+}

package/lib/builder/serializer/serializers.ts

@@ -0,0 +1,393 @@
+/**
+ * State → Document serialization functions.
+ * Converts the builder's Zustand state into Sanity-compatible document payloads.
+ *
+ * Extracted from serializer.ts in Session 162.
+ */
+
+import type { ContentBlock, ContentItem, PageSection, PageSectionV2, ParallaxGroup } from "../../../lib/sanity/types";
+import { isPageSection, isPageSectionV2, isCustomSectionInstance, isParallaxGroup } from "../../../lib/sanity/types";
+import type { BuilderState } from "../types";
+import { DEFAULT_BG_COLOR, DEFAULT_TEXT_COLOR } from "../constants";
+
+import { stripUndefined, normalizeBlockResponsive } from "./shared";
+
+// ============================================
+// Block Serialization
+// ============================================
+
+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;
+}
+
+// ============================================
+// Section Serialization
+// ============================================
+
+/**
+ * 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),
+  };
+}
+
+// ============================================
+// ParallaxGroup Serialization (Session 123)
+// ============================================
+
+/**
+ * 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,
+      });
+    }),
+  };
+}
+
+// ============================================
+// Content Item Dispatcher
+// ============================================
+
+/**
+ * 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`);
+}
+
+// ============================================
+// Main Export
+// ============================================
+
+/**
+ * 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,
+  });
+}