@morphika/webframe 0.1.0

package/lib/sanity/types.ts

@@ -0,0 +1,869 @@
+// ============================================
+// Primitives / shared
+// ============================================
+
+export type NavColorVariant =
+  | "yellow-lime"
+  | "yellow"
+  | "red-coral"
+  | "blue"
+  | "green"
+  | "white";
+
+/** Minimal Portable Text block shape (Sanity block content). */
+export interface PortableTextBlock {
+  _type: string;
+  _key: string;
+  children?: Array<{ _type: string; _key: string; text?: string; marks?: string[] }>;
+  markDefs?: Array<{ _type: string; _key: string; [key: string]: unknown }>;
+  style?: string;
+  level?: number;
+  listItem?: string;
+  [key: string]: unknown;
+}
+
+export type PortableTextContent = PortableTextBlock[];
+
+export interface SanitySlug {
+  current: string;
+}
+
+// ============================================
+// Responsive Overrides
+// ============================================
+// Blocks store their base properties (= desktop).
+// Tablet and phone can override any visual/layout property.
+// At render time we merge: { ...base, ...overrides[viewport] }.
+// This keeps desktop as source of truth; smaller viewports only
+// store what differs.
+
+/**
+ * Per-viewport overrides for a block.
+ * Each key holds a partial set of the block's own properties.
+ * `_type` and `_key` are never overridden.
+ */
+export interface ResponsiveOverrides<T> {
+  tablet?: Partial<Omit<T, "_type" | "_key" | "responsive">>;
+  phone?: Partial<Omit<T, "_type" | "_key" | "responsive">>;
+}
+
+// ============================================
+// Enter Animation Config (Session 116)
+// ============================================
+// Unified "enter" trigger with above-the-fold detection.
+// No intensity/range/trigger fields.
+
+export { type EnterAnimationConfig, type TypewriterConfig } from "../../lib/animation/enter-types";
+
+// ============================================
+// Hover Effect Config — NEW (Session 116)
+// ============================================
+// Replaces both HoverAnimationConfig and ShaderEffectConfig.
+// Block-level only (no cascade).
+
+export { type HoverEffectConfig } from "../../lib/animation/hover-effect-types";
+
+// ============================================
+// Block Layout — shared styling for all blocks
+// ============================================
+// Same properties as Row layout (Semplice Module styling):
+// Spacing (padding TRBL), Background, Offset (margin TRBL), Border.
+
+export interface BlockLayout {
+  // Alignment
+  align_h?: "left" | "center" | "right";
+  align_v?: "top" | "center" | "bottom";
+  // Spacing (padding TRBL, px)
+  spacing_top?: string;
+  spacing_right?: string;
+  spacing_bottom?: string;
+  spacing_left?: string;
+  // Background
+  background_color?: string;
+  background_opacity?: number;       // 0–100
+  background_image?: string;         // asset path
+  background_size?: "cover" | "contain" | "auto";
+  background_position?: string;
+  background_repeat?: "no-repeat" | "repeat" | "repeat-x" | "repeat-y";
+  // Offset (margin TRBL, px)
+  offset_top?: string;
+  offset_right?: string;
+  offset_bottom?: string;
+  offset_left?: string;
+  // Border
+  border_color?: string;
+  border_width?: string;
+  border_style?: "none" | "solid" | "dashed" | "dotted";
+  border_sides?: "all" | "top" | "right" | "bottom" | "left" | "top-bottom" | "left-right";
+  border_radius?: string;
+}
+
+// ============================================
+// Block Types (7)
+// ============================================
+
+export interface TextBlock {
+  _type: "textBlock";
+  _key: string;
+  text?: PortableTextContent;
+  /** Optional reference to a global typography level (h1, h2, body, etc.) */
+  textStyle?: string;
+  /** Number of CSS columns (1 = default, 2–4 = multi-column).
+   *  Column gap inherits the global grid gutter via var(--grid-gutter). */
+  columns?: number;
+  style?: {
+    fontSize?: number | string;  // px value (number) or legacy string enum
+    color?: string;
+    alignment?: "left" | "center" | "right" | "justify";
+    fontWeight?: string;  // "300" | "400" | "500" | "700" etc.
+    lineHeight?: string;
+    letterSpacing?: string;
+    maxWidth?: string;
+    opacity?: number;
+    textTransform?: "none" | "uppercase" | "lowercase" | "capitalize";
+  };
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  typewriter_config?: import("@/lib/animation/enter-types").TypewriterConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<TextBlock>;
+}
+
+export interface ImageBlock {
+  _type: "imageBlock";
+  _key: string;
+  asset_path: string;
+  alt?: string;
+  caption?: string;
+  width?: "full" | "contained" | "small";
+  aspect_ratio?: "auto" | "16:9" | "4:3" | "1:1" | "21:9";
+  lazy?: boolean;
+  border_radius?: string;
+  shadow?: boolean;
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<ImageBlock>;
+}
+
+export interface ImageGridBlock {
+  _type: "imageGridBlock";
+  _key: string;
+  images?: Array<{ asset_path: string; alt?: string }>;
+  h_gutter?: number;
+  v_gutter?: number;
+  images_per_row?: 1 | 2 | 4 | 6 | 12;
+  random_grid?: "disabled" | "small2-big4" | "small3-big6" | "small4-big8";
+  random_seed?: number;
+  lightbox?: boolean;
+  object_fit?: "cover" | "contain";
+  border_radius?: string;
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<ImageGridBlock>;
+}
+
+export interface VideoBlock {
+  _type: "videoBlock";
+  _key: string;
+  video_type: "vimeo" | "youtube" | "mp4" | "url";
+  url_or_path: string;
+  poster?: string;
+  autoplay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  width?: "full" | "contained";
+  aspect_ratio?: "16:9" | "21:9" | "4:3" | "auto";
+  border_radius?: string;
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<VideoBlock>;
+}
+
+export interface SpacerBlock {
+  _type: "spacerBlock";
+  _key: string;
+  height?: "small" | "medium" | "large" | "xlarge" | "custom";
+  custom_height?: number;
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<SpacerBlock>;
+}
+
+export interface ButtonBlock {
+  _type: "buttonBlock";
+  _key: string;
+  text: string;
+  url: string;
+  style?: "primary" | "secondary" | "outline" | "text";
+  size?: "small" | "medium" | "large";
+  target?: boolean;
+  full_width?: boolean;
+  alignment?: "left" | "center" | "right";
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<ButtonBlock>;
+}
+
+export interface CoverBlock {
+  _type: "coverBlock";
+  _key: string;
+  // Content
+  headline?: string;
+  subheadline?: string;
+  cta_button?: {
+    text?: string;
+    url?: string;
+    target_blank?: boolean;
+    style?: "primary" | "secondary" | "outline" | "text";
+  };
+  // Media
+  media_type?: "image" | "video";
+  media_path?: string;
+  video_poster?: string;
+  background_size?: "cover" | "contain" | "none";
+  background_position?: string;
+  background_repeat?: "no-repeat" | "repeat" | "repeat-x" | "repeat-y";
+  // Overlay
+  overlay?: "none" | "dark" | "light" | "gradient-bottom" | "gradient-top";
+  overlay_opacity?: number;
+  // Layout
+  content_align_h?: "left" | "center" | "right";
+  content_align_v?: "top" | "center" | "bottom";
+  content_max_width?: string;
+  height?: "100vh" | "80vh" | "60vh" | "40vh" | "custom";
+  custom_height?: string;
+  mobile_height?: "same" | "100vh" | "80vh" | "60vh" | "500px" | "400px";
+  // Appearance
+  text_color?: string;
+  show_scroll_indicator?: boolean;
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  hover_effect?: import("@/lib/animation/hover-effect-types").HoverEffectConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<CoverBlock>;
+}
+
+// ============================================
+// Project Grid Block v2 (template-only, Session 105)
+// ============================================
+
+export interface ProjectGridItemOverrides {
+  aspect_ratio_override?: "16/9" | "1/1" | "9/16" | null;
+}
+
+export interface ProjectGridItem {
+  _key: string;
+  project_slug: string;
+  custom_thumbnail?: string;
+  custom_subtitle?: string;
+  /** Per-card aspect ratio override — null/undefined = inherit grid-level ratios */
+  aspect_ratio_override?: "16/9" | "1/1" | "9/16" | null;
+  /** Viewport-specific per-card overrides (tablet/phone) */
+  responsive?: {
+    tablet?: ProjectGridItemOverrides;
+    phone?: ProjectGridItemOverrides;
+  };
+}
+
+/** Card entrance animation config for Project Grid */
+export interface CardEntranceConfig {
+  enabled?: boolean;                              // default false
+  preset?: "fade" | "slide-up" | "scale";         // default "slide-up"
+  stagger_delay?: number;                         // ms between cards, default 80
+  duration?: number;                              // ms, default 500
+}
+
+export interface ProjectGridBlock {
+  _type: "projectGridBlock";
+  _key: string;
+  // ─── Grid Settings ───
+  columns: number;                          // 1–6, default 3
+  aspect_ratios: string[];                  // ["16/9", "1/1", "9/16"] multi-select, min 1
+  gap_v: number;                            // Vertical gap in px, default 16
+  gap_h: number;                            // Horizontal gap in px, default 16
+  // ─── Appearance ───
+  hover_effect: "3d" | "scale" | "none";    // default "scale"
+  show_subtitle: boolean;                   // default true
+  border_radius: number;                    // px, default 0
+  // ─── Video ───
+  video_mode: "off" | "hover" | "autoloop"; // default "off"
+  // ─── Card Entrance Animation ───
+  card_entrance?: CardEntranceConfig;
+  // ─── Projects ───
+  projects: ProjectGridItem[];
+  // ─── Standard block fields ───
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<ProjectGridBlock>;
+}
+
+// ============================================
+// Parallax V2 — Group + Slide types (Session 123)
+// ============================================
+
+export type NavEntrancePreset = "" | "fade-in" | "slide-down" | "blur-in";
+
+/** A single parallax slide — contains a full V2 section (columns + blocks) with background media */
+export interface ParallaxSlideV2 {
+  _key: string;
+  _type: "parallaxSlide";
+
+  // Background
+  background_type: "image" | "video";   // default "image"
+  background_image?: string;            // asset path
+  background_video?: string;            // asset path
+  background_position?: string;         // CSS background-position, default "center center"
+  background_overlay_color?: string;    // hex, default "#000000"
+  background_overlay_opacity?: number;  // 0–100, default 0
+
+  // Nav color override — hex color applied to navbar while this slide is active
+  nav_color?: string;                   // hex, e.g. "#ffffff"
+
+  // V2 section data (same structure as PageSectionV2 internals)
+  columns: SectionColumn[];
+  section_settings: SectionV2Settings;
+}
+
+/** A group of parallax slides — lives inline in a page's content_rows */
+export interface ParallaxGroup {
+  _type: "parallaxGroup";
+  _key: string;
+
+  // Slides
+  slides: ParallaxSlideV2[];
+
+  // Group-level settings
+  transition_effect: "parallax" | "crossfade" | "reveal";  // default "parallax"
+  snap_enabled: boolean;               // default true
+  parallax_intensity: number;           // 0.2–0.6, default 0.4 (hidden from UI, hardcoded)
+}
+
+// ============================================
+// Page Section — first-class section type (Session 76)
+// ============================================
+// Replaces the old "matryoshka" approach where section blocks were
+// wrapped in row → column → block. Sections are direct entries in
+// content_rows alongside regular rows.
+
+export type PageSectionType = "projectGrid";
+
+export interface SectionSettings {
+  // Background
+  background_color?: string;
+  background_opacity?: number;
+  background_image?: string;
+  background_size?: "cover" | "contain" | "auto";
+  background_position?: string;
+  background_repeat?: "no-repeat" | "repeat" | "repeat-x" | "repeat-y";
+  // Spacing (padding TRBL)
+  spacing_top?: string;
+  spacing_right?: string;
+  spacing_bottom?: string;
+  spacing_left?: string;
+  // Offset (margin TRBL)
+  offset_top?: string;
+  offset_right?: string;
+  offset_bottom?: string;
+  offset_left?: string;
+  // Border
+  border_color?: string;
+  border_width?: string;
+  border_style?: "none" | "solid" | "dashed" | "dotted";
+  border_sides?: "all" | "top" | "right" | "bottom" | "left" | "top-bottom" | "left-right";
+  border_radius?: string;
+  // Animation
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+}
+
+/** Section block types that can appear inside a PageSection */
+export type SectionBlock = ProjectGridBlock;
+
+/** Section settings that can be overridden per-viewport */
+export type SectionSettingsOverridable = Pick<SectionSettings,
+  "background_color" | "background_opacity" | "background_image" | "background_size" | "background_position" | "background_repeat" |
+  "spacing_top" | "spacing_right" | "spacing_bottom" | "spacing_left" |
+  "offset_top" | "offset_right" | "offset_bottom" | "offset_left" |
+  "border_color" | "border_width" | "border_style" | "border_sides" | "border_radius"
+>;
+
+export interface PageSection {
+  _type: "pageSection";
+  _key: string;
+  section_type: PageSectionType;
+  /** The actual section content — single block */
+  block: [SectionBlock];
+  settings?: SectionSettings;
+  /** BUG-013 fix: Per-viewport responsive overrides for section settings */
+  responsive?: {
+    tablet?: Partial<SectionSettingsOverridable>;
+    phone?: Partial<SectionSettingsOverridable>;
+  };
+}
+
+// ============================================
+// Page Section V2 — V2 Grid System (Session 83)
+// ============================================
+// Flat list of columns with explicit grid positions.
+// No "row" objects — rows are a visual artifact derived from grid_row values.
+
+export type SectionV2Preset = "full" | "halves" | "thirds" | "quarters" | "1/3+2/3" | "2/3+1/3" | "custom";
+
+export interface SectionV2Settings {
+  // Grid
+  preset: SectionV2Preset;
+  grid_columns: number;        // default 12
+  col_gap: number;             // px, horizontal
+  row_gap: number;             // px, vertical
+  // Spacing (padding TRBL, px)
+  spacing_top?: string;
+  spacing_right?: string;
+  spacing_bottom?: string;
+  spacing_left?: string;
+  // Offset (margin TRBL, px)
+  offset_top?: string;
+  offset_right?: string;
+  offset_bottom?: string;
+  offset_left?: string;
+  // Background
+  background_color?: string;
+  background_opacity?: number;
+  background_image?: string;
+  background_size?: "cover" | "contain" | "auto";
+  background_position?: string;
+  background_repeat?: "no-repeat" | "repeat" | "repeat-x" | "repeat-y";
+  // Border
+  border_color?: string;
+  border_width?: string;
+  border_style?: "none" | "solid" | "dashed" | "dotted";
+  border_sides?: "all" | "top" | "right" | "bottom" | "left" | "top-bottom" | "left-right";
+  border_radius?: string;
+  // Animation (cascade: page → section → column → block)
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+  stagger?: {
+    enabled?: boolean;
+    delayPerChild?: number;     // 50–300ms
+    direction?: "left-to-right" | "right-to-left";
+  };
+}
+
+export interface SectionColumn {
+  _key: string;
+  grid_column: number;      // 1-based start position (1–12)
+  grid_row: number;         // 1-based, computed by builder
+  span: number;             // how many grid columns (1–grid_columns)
+  blocks: ContentBlock[];   // same block types as today
+  // NEW (Session 116) — column-level enter animation for 4-level cascade
+  enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+}
+
+export interface ColumnOverride {
+  _key: string;             // matches SectionColumn._key
+  grid_column?: number;
+  grid_row?: number;
+  span?: number;
+}
+
+/** V2 section settings that can be overridden per-viewport */
+export type SectionV2SettingsOverridable = Pick<SectionV2Settings,
+  "col_gap" | "row_gap" |
+  "spacing_top" | "spacing_right" | "spacing_bottom" | "spacing_left" |
+  "offset_top" | "offset_right" | "offset_bottom" | "offset_left" |
+  "background_color" | "background_opacity" |
+  "border_color" | "border_width" | "border_style" | "border_sides" | "border_radius" |
+  "enter_animation" | "stagger"
+>;
+
+export interface SectionV2ResponsiveOverride {
+  columns?: ColumnOverride[];                         // per-column layout overrides
+  settings?: Partial<SectionV2SettingsOverridable>;    // section-level overrides
+}
+
+export interface PageSectionV2 {
+  _type: "pageSectionV2";
+  _key: string;
+  section_type: "empty-v2";
+  columns: SectionColumn[];
+  settings: SectionV2Settings;
+  responsive?: {
+    tablet?: SectionV2ResponsiveOverride;
+    phone?: SectionV2ResponsiveOverride;
+  };
+}
+
+// ============================================
+// Custom Section — reusable V2 section (Session 107)
+// ============================================
+
+/** Full custom section document (for editing) */
+export interface CustomSection {
+  _id: string;
+  title: string;
+  slug: SanitySlug;
+  description?: string;
+  section: PageSectionV2;
+  thumbnail_path?: string;
+  updated_at?: string;
+}
+
+/** Lightweight list item (for picker) */
+export interface CustomSectionListItem {
+  _id: string;
+  title: string;
+  slug: SanitySlug;
+  description?: string;
+  thumbnail_path?: string;
+  updated_at?: string;
+}
+
+/** Instance reference stored inside a page's content_rows */
+export interface CustomSectionInstance {
+  _type: "customSectionInstance";
+  _key: string;
+  custom_section_id: string;      // Sanity _id of the customSection document
+  custom_section_slug: string;
+  custom_section_title: string;   // cached for display
+  /** Per-instance section settings overrides (spacing, background, border, animation).
+   *  Merged on top of the custom section's base settings at render time.
+   *  Content (columns/blocks) remains shared; only the "embedding" settings vary per-instance. */
+  settings_overrides?: Partial<SectionV2Settings>;
+  /** Per-instance responsive overrides (tablet/phone viewport-specific settings).
+   *  Same structure as PageSectionV2.responsive but only affects this instance. */
+  responsive_overrides?: PageSectionV2["responsive"];
+}
+
+// ============================================
+// Content Item — union of PageSection, PageSectionV2, and CustomSectionInstance
+// ============================================
+// Used in content_rows and the builder store.
+
+export type ContentItem = PageSection | PageSectionV2 | CustomSectionInstance | ParallaxGroup;
+
+/** Type guard: check if a content item is a PageSection (V1) */
+export function isPageSection(item: ContentItem): item is PageSection {
+  return (item as PageSection)._type === "pageSection";
+}
+
+/** Type guard: check if a content item is a PageSectionV2 */
+export function isPageSectionV2(item: ContentItem): item is PageSectionV2 {
+  return (item as PageSectionV2)._type === "pageSectionV2";
+}
+
+/** Type guard: check if a content item is a CustomSectionInstance */
+export function isCustomSectionInstance(item: ContentItem): item is CustomSectionInstance {
+  return (item as CustomSectionInstance)._type === "customSectionInstance";
+}
+
+/** Type guard: check if a content item is a ParallaxGroup (Session 123) */
+export function isParallaxGroup(item: ContentItem): item is ParallaxGroup {
+  return (item as ParallaxGroup)._type === "parallaxGroup";
+}
+
+// ============================================
+// Shared references
+// ============================================
+
+export interface PageRef {
+  _id: string;
+  title: string;
+  slug: SanitySlug;
+  page_type: PageType;
+}
+
+// ============================================
+// Union type for all blocks
+// ============================================
+
+export type ContentBlock =
+  | TextBlock
+  | ImageBlock
+  | ImageGridBlock
+  | VideoBlock
+  | SpacerBlock
+  | ButtonBlock
+  | CoverBlock
+  | ProjectGridBlock;
+
+// ============================================
+// Structural types
+// ============================================
+
+// ============================================
+// Page types
+// ============================================
+
+export type PageType = "page" | "project";
+
+export interface PageMetadata {
+  seo_title?: string;
+  seo_description?: string;
+  og_image_path?: string;
+}
+
+export interface Page {
+  _id: string;
+  title: string;
+  slug: SanitySlug;
+  page_type: PageType;
+  is_home?: boolean;
+  content_rows?: ContentItem[];
+  metadata?: PageMetadata;
+  published_at?: string;
+  draft_mode?: boolean;
+  thumbnail_path?: string;
+  cover_video?: string;
+  page_settings?: {
+    background_color?: string;
+    text_color?: string;
+    nav_color?: string;
+    enter_animation?: import("@/lib/animation/enter-types").EnterAnimationConfig;
+    // ── Per-page nav entrance override ──
+    nav_entrance_animation?: NavEntrancePreset;
+    nav_entrance_duration?: number;
+    nav_entrance_delay?: number;
+    nav_entrance_disabled?: boolean;
+  };
+}
+
+export interface PageListItem {
+  _id: string;
+  title: string;
+  slug: SanitySlug;
+  page_type: PageType;
+  is_home?: boolean;
+  draft_mode?: boolean;
+  published_at?: string;
+  thumbnail_path?: string;
+  cover_video?: string;
+}
+
+// ============================================
+// Site Settings
+// ============================================
+
+export interface NavItemStyleOverrides {
+  font_size?: number;
+  font_weight?: string;
+  font_family?: string;
+  color?: string; // hex
+  text_transform?: "none" | "uppercase" | "lowercase" | "capitalize";
+  vertical_align?: "top" | "middle" | "bottom";
+}
+
+export interface NavItem {
+  _key: string;
+  type: "logo" | "menu-item"; // NEW — item type
+  label: string;
+  logo_image?: string; // NEW — asset path for logo (optional)
+  link_type: "internal" | "external" | "content";
+  internal_page?: PageRef;
+  external_url?: string;
+  /** Content link: type of media shown in lightbox */
+  content_type?: "image" | "video-file" | "video-embed";
+  /** Content link: asset path for image or video file */
+  content_asset?: string;
+  /** Content link: embed URL for YouTube/Vimeo */
+  content_url?: string;
+  visible: boolean;
+  grid_column: number; // 1–12, required
+  column_span: number; // NEW — how many columns this item occupies (1–12)
+  style_overrides?: NavItemStyleOverrides; // NEW — per-item style overrides
+}
+
+export interface NavDesign {
+  logo_text?: string;
+  color?: NavColorVariant;
+  position?: "fixed" | "sticky" | "static";
+  hide_on_scroll?: boolean;
+  font_size?: number;
+  font_weight?: string;
+  font_family?: string;
+  text_align?: "left" | "center" | "right";
+  text_transform?: "none" | "uppercase" | "lowercase" | "capitalize";
+  vertical_align?: "top" | "middle" | "bottom";
+  padding_h?: number;
+  padding_v?: number;
+  margin_h?: number;
+  margin_v?: number;
+  background_color?: string;
+  background_opacity?: number;
+  backdrop_blur?: boolean;
+  items_gap?: number;
+  logo_columns?: number; // 1–6, how many grid columns the logo spans
+  // ── Entrance animation ──
+  entrance_animation?: NavEntrancePreset;
+  entrance_duration?: number;   // ms, default 600
+  entrance_delay?: number;      // ms, default 0
+  entrance_stagger?: boolean;   // stagger items, default false
+  entrance_stagger_delay?: number; // ms between items, default 80
+}
+
+// ============================================
+// Storage Provider
+// ============================================
+
+export type StorageProviderType = "r2";
+
+// ============================================
+// Asset Registry
+// ============================================
+
+export interface RegisteredAsset {
+  _key: string;
+  path: string;
+  filename: string;
+  extension: string;
+  file_size?: number;
+  mime_type?: string;
+  width?: number;
+  height?: number;
+  file_hash?: string;
+  has_thumbnail?: boolean;
+  status: "active" | "missing" | "moved" | "new";
+  last_checked_at?: string;
+  used_in?: string[];
+  previous_paths?: string[];
+}
+
+export interface RelinkLogEntry {
+  _key: string;
+  date: string;
+  old_seed: string;
+  new_seed: string;
+  assets_relinked: number;
+  assets_missing: number;
+  details?: string;
+}
+
+export interface AssetRegistry {
+  _id: string;
+  /** Active storage provider. Defaults to "r2". */
+  storage_provider?: StorageProviderType;
+  seed_url?: string;
+  scan_status?: "ready" | "scanning" | "error";
+  last_scanned_at?: string;
+  scan_error?: string;
+  assets?: RegisteredAsset[];
+  relink_log?: RelinkLogEntry[];
+  // R2 configuration
+  r2_bucket_url?: string;
+  r2_access_key_id?: string;
+  r2_secret_access_key?: string;
+  r2_endpoint?: string;
+  r2_bucket_name?: string;
+  r2_connected_at?: string;
+}
+
+// ============================================
+// Site Settings
+// ============================================
+
+export interface SiteSettings {
+  nav_items?: NavItem[];
+  nav_design?: NavDesign;
+  default_title?: string;
+  default_description?: string;
+  default_og_image?: string;
+  favicon_path?: string;
+  analytics_id?: string;
+  seed_url?: string;
+  last_scanned_at?: string;
+  asset_status?: "ok" | "scanning" | "error";
+}
+
+// ============================================
+// Site Styles — Global design system
+// ============================================
+
+export interface FontVariant {
+  _key: string;
+  weight: string; // "300", "400", "500", "700", etc.
+  style: "normal" | "italic";
+  file_url: string; // Sanity CDN URL
+  file_id?: string; // Sanity asset ID (for deletion)
+  original_filename: string;
+}
+
+export interface FontFamily {
+  _key: string;
+  family: string; // e.g. "Inter", "Space Grotesk"
+  is_builtin?: boolean; // true for fonts already in /public/fonts/
+  variants: FontVariant[];
+}
+
+export interface TypographyLevel {
+  font_family?: string; // References FontFamily.family
+  font_size: string; // e.g. "3rem", "48px"
+  font_weight: string; // e.g. "700"
+  line_height: string; // e.g. "1.1"
+  letter_spacing: string; // e.g. "-0.02em"
+  text_transform?: "none" | "uppercase" | "lowercase" | "capitalize";
+  color?: string; // Override page text color
+}
+
+export interface ColorSwatch {
+  _key?: string;
+  name: string;
+  hex: string;
+}
+
+export interface ColorPalette {
+  swatches: ColorSwatch[];
+  // Legacy fields (backward compat, may be empty)
+  background?: string;
+  text?: string;
+  primary?: string;
+  secondary?: string;
+  accent?: string;
+  muted?: string;
+}
+
+export interface SpacingScale {
+  section_padding: string; // e.g. "80px"
+  content_gap: string; // e.g. "24px"
+  border_radius: string; // e.g. "8px"
+}
+
+export interface LinkStyle {
+  color: string;
+  hover_color: string;
+  underline: boolean;
+}
+
+export interface ButtonStyle {
+  primary_bg: string;
+  primary_text: string;
+  secondary_bg: string;
+  secondary_text: string;
+  border_radius: string;
+}
+
+export interface GridSettings {
+  width: string;           // e.g. "1445"
+  outer_padding: string;   // e.g. "30"
+  gutter_desktop: string;  // e.g. "30"
+  gutter_responsive: string; // e.g. "30" (tablet)
+  gutter_phone?: string;   // e.g. "16" (phone, ≤640px)
+}
+
+export interface SiteStyles {
+  grid?: GridSettings;
+  fonts?: FontFamily[];
+  typography?: {
+    h1?: TypographyLevel;
+    h2?: TypographyLevel;
+    h3?: TypographyLevel;
+    h4?: TypographyLevel;
+    body?: TypographyLevel;
+    small?: TypographyLevel;
+  };
+  colors?: ColorPalette;
+  link_style?: LinkStyle;
+  button_style?: ButtonStyle;
+  /** When true, disables all scroll animations on viewports ≤768px */
+  disable_scroll_animations_mobile?: boolean;
+}