@morphika/andami 0.1.2

package/lib/builder/types.ts

@@ -0,0 +1,374 @@
+// ============================================
+// Builder State Types
+// ============================================
+// These types define the in-memory state for the Visual Page Builder.
+// They mirror the Sanity schema types but are optimized for the builder UI.
+
+import type {
+  Page,
+  PageType,
+  ContentBlock,
+  ContentItem,
+  PageSection,
+  PageSectionV2,
+  SectionSettings,
+  SectionV2Settings,
+  SectionV2Preset,
+  SectionColumn,
+  PageMetadata,
+} from "../../lib/sanity/types";
+import { DEFAULT_BG_COLOR, DEFAULT_TEXT_COLOR, DEFAULT_GRID_WIDTH } from "./constants";
+
+// ============================================
+// Block Type Registry
+// ============================================
+
+export type BlockType = ContentBlock["_type"];
+
+export type BlockCategory = "content" | "section";
+
+export interface BlockTypeInfo {
+  type: BlockType;
+  label: string;
+  description: string;
+  group: "generic";
+  icon: string; // SVG path or emoji for now
+  /** Block category for grouping in the picker */
+  category: BlockCategory;
+}
+
+/**
+ * Content blocks — available in the "+ Add Block" picker inside columns.
+ * Section-level blocks (projectGrid) are NOT here —
+ * they live in the SectionTypePicker as Page Sections.
+ */
+export const BLOCK_TYPE_REGISTRY: BlockTypeInfo[] = [
+  { type: "textBlock", label: "Text", description: "Rich text content", group: "generic", icon: "T", category: "content" },
+  { type: "imageBlock", label: "Image", description: "Single image with caption", group: "generic", icon: "🖼", category: "content" },
+  { type: "imageGridBlock", label: "Image Grid", description: "Multiple images in grid", group: "generic", icon: "⊞", category: "content" },
+  { type: "videoBlock", label: "Video", description: "Vimeo, YouTube, or MP4", group: "generic", icon: "▶", category: "content" },
+  { type: "spacerBlock", label: "Spacer", description: "Vertical spacing", group: "generic", icon: "↕", category: "content" },
+  { type: "buttonBlock", label: "Button", description: "Call-to-action button", group: "generic", icon: "▣", category: "content" },
+  { type: "coverBlock", label: "Cover", description: "Full-screen hero section", group: "generic", icon: "◈", category: "content" },
+];
+
+/**
+ * Complete block info lookup — includes BOTH content blocks and section blocks.
+ * Used by SettingsPanel, SortableBlock, DndWrapper, etc. for labels/icons.
+ * The BLOCK_TYPE_REGISTRY above only contains content blocks (for the picker).
+ */
+export const ALL_BLOCK_INFO: BlockTypeInfo[] = [
+  ...BLOCK_TYPE_REGISTRY,
+  // Section blocks — not in the content picker but still need label/icon lookup
+  { type: "projectGridBlock", label: "Project Grid", description: "Staggered project showcase grid", group: "generic", icon: "⬡", category: "section" },
+];
+
+// Parallax group info — used by BuilderCanvas/SortableRow for label/icon lookup (not a block)
+export const PARALLAX_GROUP_INFO = { label: "Parallax Showcase", icon: "▽" };
+
+// ============================================
+// Section Types — for the "+ Add Section" picker
+// ============================================
+
+/** Section block types that create a full-width row with a pre-populated block */
+export type SectionBlockType = "projectGridBlock";
+
+/** Set for fast lookup — used by SortableBlock, ColumnDropZone, SortableRow to suppress inner chrome */
+const SECTION_BLOCK_TYPES: ReadonlySet<string> = new Set<string>(["projectGridBlock"]);
+
+/** Check if a block type is a section-level block (should render without block/column chrome) */
+export function isSectionBlockType(type: string): boolean {
+  return SECTION_BLOCK_TYPES.has(type);
+}
+
+export type SectionType = "empty-v2" | "parallaxGroup" | SectionBlockType;
+
+export interface SectionTypeInfo {
+  type: SectionType;
+  label: string;
+  description: string;
+  icon: string;
+  /** If set, this section auto-creates a row with this block type pre-populated */
+  blockType?: SectionBlockType;
+}
+
+export const SECTION_TYPE_REGISTRY: SectionTypeInfo[] = [
+  { type: "empty-v2", label: "Empty Section", description: "Grid section with flexible columns", icon: "⊞" },
+  { type: "projectGridBlock", label: "Project Grid", description: "Staggered project showcase grid", icon: "⬡", blockType: "projectGridBlock" },
+  { type: "parallaxGroup", label: "Parallax Section", description: "Full-screen parallax showcase with V2 slides", icon: "▽" },
+];
+
+// ============================================
+// Builder Store State
+// ============================================
+
+// ============================================
+// Page-level Settings (global per page)
+// ============================================
+
+export interface PageSettings {
+  background_color: string;
+  nav_color: string;
+  text_color: string;
+  /** Page-level default enter animation (cascade: page → section → column → block) */
+  enter_animation?: import("../../lib/animation/enter-types").EnterAnimationConfig;
+  /** Per-page nav entrance animation override */
+  nav_entrance_animation?: import("../../lib/sanity/types").NavEntrancePreset;
+  nav_entrance_duration?: number;
+  nav_entrance_delay?: number;
+  nav_entrance_disabled?: boolean;
+}
+
+export const DEFAULT_PAGE_SETTINGS: PageSettings = {
+  background_color: DEFAULT_BG_COLOR,
+  nav_color: "",
+  text_color: DEFAULT_TEXT_COLOR,
+};
+
+// ============================================
+// Canvas Types
+// ============================================
+
+export type CanvasTool = 'select' | 'hand';
+export type DeviceViewport = 'desktop' | 'tablet' | 'phone';
+
+export const DEVICE_WIDTHS: Record<DeviceViewport, number> = {
+  desktop: 1920,
+  tablet: 810,
+  phone: 390,
+} as const;
+
+/** Simulated viewport heights for converting vh units in the builder canvas */
+export const DEVICE_HEIGHTS: Record<DeviceViewport, number> = {
+  desktop: 800,
+  tablet: 1080,
+  phone: 844,
+} as const;
+
+// ============================================
+// Grid Settings (from Customize → Grid)
+// ============================================
+
+export interface GridSettings {
+  width: string;         // e.g. "1445"
+  outer_padding: string; // e.g. "30"
+  gutter_desktop: string;
+  gutter_responsive: string;
+  gutter_phone: string;
+}
+
+export const DEFAULT_GRID_SETTINGS: GridSettings = {
+  width: DEFAULT_GRID_WIDTH,
+  outer_padding: "30",
+  gutter_desktop: "30",
+  gutter_responsive: "30",
+  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 — page sections (V1 + V2)
+  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[];
+  _isTimeTraveling: boolean;
+
+  /** 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>;
+}
+
+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
+  addSection: (blockType: "projectGridBlock", afterRowKey?: string | null) => void;
+  reorderRows: (fromIndex: number, toIndex: number) => void;
+  /** Update settings for a PageSection (background, spacing, animation, etc.) */
+  updateSectionSettings: (sectionKey: string, settings: Partial<SectionSettings>) => void;
+  /** BUG-013 fix: Update responsive overrides for a PageSection */
+  updateSectionResponsive: (sectionKey: string, responsive: PageSection["responsive"]) => void;
+  /** Update the block content inside a PageSection */
+  updateSectionBlock: (sectionKey: string, updates: Partial<import("../../lib/sanity/types").ContentBlock>) => void;
+  /** Delete a section (PageSection or PageSectionV2) by key */
+  deleteSection: (sectionKey: string) => void;
+  /** Duplicate a section (PageSection or PageSectionV2), 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;
+
+  // 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;
+}
+
+export type BuilderStore = BuilderState & BuilderActions;

package/lib/builder/utils.ts

@@ -0,0 +1,37 @@
+/**
+ * Generate a unique key for Sanity objects (rows, columns, blocks).
+ * Uses crypto.randomUUID() for reliable collision resistance.
+ * Falls back to Math.random() in environments without crypto support.
+ */
+export function generateKey(): string {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID().replace(/-/g, "").substring(0, 12);
+  }
+  // Fallback: 12-character base-36 string
+  return (
+    Math.random().toString(36).substring(2, 8) +
+    Math.random().toString(36).substring(2, 8)
+  );
+}
+
+/**
+ * Normalize a min-height CSS value.
+ *
+ * BUG-015 fix: Prevents invalid CSS like '500pxpx' or bare numbers.
+ * - Preset values like '100vh', '80vh' etc. → use as-is
+ * - Values already containing a unit (px, vh, %, em, rem) → use as-is
+ * - Bare numbers like '500' → append 'px'
+ * - Empty/falsy → undefined
+ */
+export function normalizeMinHeight(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  // Already has a CSS unit — use as-is
+  if (/[a-z%]$/i.test(trimmed)) return trimmed;
+  // Bare number — append px
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return `${trimmed}px`;
+  // Unrecognized — return as-is and let CSS handle it
+  return trimmed;
+}
+

package/lib/color-utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Centralized color conversion utilities.
+ *
+ * Previously duplicated across:
+ *   - components/builder/ColorPicker.tsx (hexToHSL, hsvToHex, hexToHSV)
+ *   - components/blocks/BlockRenderer.tsx (hexToRgba)
+ *   - lib/builder/layout-styles.ts (hexToRgba)
+ *   - components/admin/nav-builder/nav-builder-utils.ts (hexToRgba)
+ */
+
+/** Convert hex (#RRGGBB) to HSL values. */
+export function hexToHSL(hex: string): { h: number; s: number; l: number } {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h = 0;
+  let s = 0;
+  const l = (max + min) / 2;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+      case g: h = ((b - r) / d + 2) / 6; break;
+      case b: h = ((r - g) / d + 4) / 6; break;
+    }
+  }
+  return { h: Math.round(h * 360), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+/** Convert HSV (hue 0–360, saturation 0–100, value 0–100) to hex (#RRGGBB). */
+export function hsvToHex(h: number, s: number, v: number): string {
+  s /= 100; v /= 100;
+  const c = v * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = v - c;
+  let r = 0, g = 0, b = 0;
+  if (h < 60) { r = c; g = x; }
+  else if (h < 120) { r = x; g = c; }
+  else if (h < 180) { g = c; b = x; }
+  else if (h < 240) { g = x; b = c; }
+  else if (h < 300) { r = x; b = c; }
+  else { r = c; b = x; }
+  const toHex = (n: number) => Math.round((n + m) * 255).toString(16).padStart(2, "0");
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/** Convert hex (#RRGGBB) to HSV values. */
+export function hexToHSV(hex: string): { h: number; s: number; v: number } {
+  const r = parseInt(hex.slice(1, 3), 16) / 255;
+  const g = parseInt(hex.slice(3, 5), 16) / 255;
+  const b = parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const d = max - min;
+  let h = 0;
+  const s = max === 0 ? 0 : d / max;
+  const v = max;
+  if (max !== min) {
+    switch (max) {
+      case r: h = ((g - b) / d + (g < b ? 6 : 0)) * 60; break;
+      case g: h = ((b - r) / d + 2) * 60; break;
+      case b: h = ((r - g) / d + 4) * 60; break;
+    }
+  }
+  return { h: Math.round(h), s: Math.round(s * 100), v: Math.round(v * 100) };
+}
+
+/**
+ * Convert hex color to rgba string.
+ * Supports #RGB, #RRGGBB, and #RRGGBBAA formats.
+ */
+export function hexToRgba(hex: string, alpha: number): string {
+  let r = 0, g = 0, b = 0;
+  const clean = hex.replace("#", "");
+  if (clean.length === 3) {
+    r = parseInt(clean[0] + clean[0], 16);
+    g = parseInt(clean[1] + clean[1], 16);
+    b = parseInt(clean[2] + clean[2], 16);
+  } else if (clean.length >= 6) {
+    r = parseInt(clean.slice(0, 2), 16);
+    g = parseInt(clean.slice(2, 4), 16);
+    b = parseInt(clean.slice(4, 6), 16);
+  }
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
+/** Validate a hex color string (#RRGGBB format). */
+export function isValidHex(hex: string): boolean {
+  return /^#[0-9a-fA-F]{6}$/.test(hex);
+}
+
+/**
+ * Linearly interpolate between two hex colors.
+ * @param a - Start hex color (#RRGGBB)
+ * @param b - End hex color (#RRGGBB)
+ * @param t - Interpolation factor 0..1 (0 = a, 1 = b)
+ * @returns Interpolated hex color (#RRGGBB)
+ */
+export function lerpHex(a: string, b: string, t: number): string {
+  const cleanA = a.replace("#", "");
+  const cleanB = b.replace("#", "");
+  const rA = parseInt(cleanA.slice(0, 2), 16);
+  const gA = parseInt(cleanA.slice(2, 4), 16);
+  const bA = parseInt(cleanA.slice(4, 6), 16);
+  const rB = parseInt(cleanB.slice(0, 2), 16);
+  const gB = parseInt(cleanB.slice(2, 4), 16);
+  const bB = parseInt(cleanB.slice(4, 6), 16);
+  const clamp = (n: number) => Math.max(0, Math.min(255, Math.round(n)));
+  const r = clamp(rA + (rB - rA) * t);
+  const g = clamp(gA + (gB - gA) * t);
+  const bl = clamp(bA + (bB - bA) * t);
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${bl.toString(16).padStart(2, "0")}`;
+}

package/lib/config/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Site configuration accessor.
+ *
+ * Call `registerConfig(config)` at app startup (e.g. in your root layout)
+ * before any component calls `getSiteConfig()`. The instance's
+ * `app/layout.tsx` imports its own `site.config.ts` and passes it here.
+ */
+
+import type { SiteConfig } from "./types";
+
+/** Module-level slot for the registered config. */
+let _registeredConfig: SiteConfig | null = null;
+
+/** Cached reference. */
+let _resolved: SiteConfig | null = null;
+
+/**
+ * Register the site configuration.
+ *
+ * Call this once at app startup (root layout module scope) before any
+ * component or API route calls `getSiteConfig()`. The instance's
+ * `app/layout.tsx` imports its own `site.config.ts` and passes it here.
+ *
+ * Calling this more than once replaces the previous config (useful for
+ * testing, but not expected in production).
+ */
+export function registerConfig(config: SiteConfig): void {
+  _registeredConfig = config;
+  // Invalidate resolved cache so next getSiteConfig() picks up the new value.
+  _resolved = null;
+}
+
+/**
+ * Get the site configuration.
+ *
+ * Returns the config registered via `registerConfig()`.
+ * Throws if no config has been registered yet.
+ *
+ * Returns the same object reference on every call (singleton).
+ * Safe to call from both server and client components.
+ */
+export function getSiteConfig(): SiteConfig {
+  if (!_resolved) {
+    if (_registeredConfig) {
+      _resolved = _registeredConfig;
+    } else {
+      throw new Error(
+        "SiteConfig not registered. Call registerConfig(config) in your root layout before using getSiteConfig().\n" +
+        "See: https://github.com/MorphikaStudio/Morphika_Andami#quick-start",
+      );
+    }
+  }
+  return _resolved;
+}
+
+// Re-export types for convenience
+export type { SiteConfig } from "./types";