@morphika/andami 0.1.2 → 0.1.5

package/lib/builder/store-blocks.ts

@@ -10,43 +10,54 @@ type StoreSet = (
 ) => void;
 type StoreGet = () => BuilderStore;
 
+// RC-005 fix: Shared helper for updating a block's fields across all section
+// types (V1, V2, ParallaxGroup). Eliminates duplicated row/column mapping
+// logic between updateBlock and updateBlockDebounced.
+function applyBlockUpdate(
+  rows: ContentItem[],
+  blockKey: string,
+  updates: Partial<ContentBlock>
+): ContentItem[] {
+  const updateColumns = (cols: import("../../lib/sanity/types").SectionColumn[]) =>
+    cols.map((col) => ({
+      ...col,
+      blocks: col.blocks.map((b) =>
+        b._key === blockKey ? ({ ...b, ...updates } as ContentBlock) : b
+      ),
+    }));
+
+  return rows.map((item) => {
+    if (isPageSection(item)) {
+      const block = item.block[0];
+      if (block && block._key === blockKey) {
+        return { ...item, block: [{ ...block, ...updates } as SectionBlock] };
+      }
+      return item;
+    }
+    if (isPageSectionV2(item)) {
+      return { ...item, columns: updateColumns(item.columns) };
+    }
+    if (isParallaxGroup(item)) {
+      return {
+        ...item,
+        slides: (item as ParallaxGroup).slides.map((slide) => ({
+          ...slide,
+          columns: updateColumns(slide.columns),
+        })),
+      } as ContentItem;
+    }
+    return item;
+  });
+}
+
 export function createBlockActions(set: StoreSet, get: StoreGet) {
   return {
     // ---- Block operations ----
 
     updateBlock: (blockKey: string, updates: Partial<ContentBlock>): void => {
       // Snapshot is NOT pushed here to avoid polluting undo history on every keystroke.
-      const updateColumns = (cols: import("../../lib/sanity/types").SectionColumn[]) =>
-        cols.map((col) => ({
-          ...col,
-          blocks: col.blocks.map((b) =>
-            b._key === blockKey ? ({ ...b, ...updates } as ContentBlock) : b
-          ),
-        }));
-
       set((state) => ({
-        rows: state.rows.map((item) => {
-          if (isPageSection(item)) {
-            const block = item.block[0];
-            if (block && block._key === blockKey) {
-              return { ...item, block: [{ ...block, ...updates } as SectionBlock] };
-            }
-            return item;
-          }
-          if (isPageSectionV2(item)) {
-            return { ...item, columns: updateColumns(item.columns) };
-          }
-          if (isParallaxGroup(item)) {
-            return {
-              ...item,
-              slides: (item as ParallaxGroup).slides.map((slide) => ({
-                ...slide,
-                columns: updateColumns(slide.columns),
-              })),
-            } as ContentItem;
-          }
-          return item;
-        }),
+        rows: applyBlockUpdate(state.rows, blockKey, updates),
         isDirty: true,
       }));
     },
@@ -126,7 +137,11 @@ export function createBlockActions(set: StoreSet, get: StoreGet) {
     },
 
     moveBlock: (blockKey: string, targetSectionKey: string, targetColumnKey: string, toIndex: number): void => {
-      const result = moveBlockInState(get().rows, blockKey, targetSectionKey, targetColumnKey, toIndex);
+      // RC-001 fix: Validate first without side effects, then push snapshot
+      // BEFORE applying mutation. This ensures undo state captures the
+      // pre-mutation rows, even if another mutation races in between.
+      const currentRows = get().rows;
+      const result = moveBlockInState(currentRows, blockKey, targetSectionKey, targetColumnKey, toIndex);
       if (!result) return;
 
       get()._pushSnapshot();
@@ -153,39 +168,11 @@ export function createBlockActions(set: StoreSet, get: StoreGet) {
     },
 
     // ---- Debounced block update (no undo snapshot per keystroke) ----
+    // RC-005 fix: Now delegates to shared applyBlockUpdate helper.
 
     updateBlockDebounced: (blockKey: string, updates: Partial<ContentBlock>): void => {
-      const updateColumns = (cols: import("../../lib/sanity/types").SectionColumn[]) =>
-        cols.map((col) => ({
-          ...col,
-          blocks: col.blocks.map((b) =>
-            b._key === blockKey ? ({ ...b, ...updates } as ContentBlock) : b
-          ),
-        }));
-
       set((state) => ({
-        rows: state.rows.map((item) => {
-          if (isPageSection(item)) {
-            const block = item.block[0];
-            if (block && block._key === blockKey) {
-              return { ...item, block: [{ ...block, ...updates } as SectionBlock] };
-            }
-            return item;
-          }
-          if (isPageSectionV2(item)) {
-            return { ...item, columns: updateColumns(item.columns) };
-          }
-          if (isParallaxGroup(item)) {
-            return {
-              ...item,
-              slides: (item as ParallaxGroup).slides.map((slide) => ({
-                ...slide,
-                columns: updateColumns(slide.columns),
-              })),
-            } as ContentItem;
-          }
-          return item;
-        }),
+        rows: applyBlockUpdate(state.rows, blockKey, updates),
         isDirty: true,
       }));
     },

package/lib/builder/store-helpers.ts

@@ -60,23 +60,40 @@ export function moveBlockInState(
       return { ...c, blocks };
     });
 
-  // Pass 1: find and remove block from all sections (V2 + parallax slides)
-  const rowsAfterRemove = rows.map((item) => {
+  // Pass 1: find and remove block from its current section (V2 + parallax slides)
+  // RC-006 fix: Early-exit once block is found, consistent with selectBlock()
+  // search pattern. Also searches PageSection V1 for completeness.
+  let rowsAfterRemove = rows;
+  for (let i = 0; i < rows.length; i++) {
+    const item = rows[i];
     if (isPageSectionV2(item)) {
-      return { ...item, columns: removeFromColumns(item.columns) } as ContentItem;
-    }
-    if (isParallaxGroup(item)) {
+      const updatedCols = removeFromColumns(item.columns);
+      if (movedBlock) {
+        rowsAfterRemove = rows.map((r, idx) =>
+          idx === i ? { ...r, columns: updatedCols } as ContentItem : r
+        );
+        break;
+      }
+    } else if (isParallaxGroup(item)) {
       const group = item as ParallaxGroup;
-      return {
-        ...group,
-        slides: group.slides.map((slide) => ({
-          ...slide,
-          columns: removeFromColumns(slide.columns),
-        })),
-      } as ContentItem;
+      let foundInSlide = false;
+      const updatedSlides = group.slides.map((slide) => {
+        if (foundInSlide) return slide; // skip remaining slides after block found
+        const updatedCols = removeFromColumns(slide.columns);
+        if (movedBlock) {
+          foundInSlide = true;
+          return { ...slide, columns: updatedCols };
+        }
+        return slide;
+      });
+      if (foundInSlide) {
+        rowsAfterRemove = rows.map((r, idx) =>
+          idx === i ? { ...group, slides: updatedSlides } as ContentItem : r
+        );
+        break;
+      }
     }
-    return item;
-  });
+  }
 
   if (!movedBlock) return null;
 

package/lib/builder/store.ts

@@ -34,6 +34,47 @@ import { createSectionActions } from "./store-sections";
 import { createBlockActions } from "./store-blocks";
 import { createCanvasActions } from "./store-canvas";
 
+// ============================================
+// RC-003 fix: Block parent key cache — O(1) lookup in selectBlock().
+// Invalidated when `rows` reference changes (immutable state).
+// ============================================
+
+interface BlockParent { rowKey: string; colKey: string | null }
+let _blockParentCache: Map<string, BlockParent> | null = null;
+let _blockParentCacheRowsRef: ContentItem[] | null = null;
+
+function getBlockParentCache(rows: ContentItem[]): Map<string, BlockParent> {
+  if (_blockParentCache && _blockParentCacheRowsRef === rows) return _blockParentCache;
+
+  const cache = new Map<string, BlockParent>();
+  for (const item of rows) {
+    if (isPageSection(item)) {
+      const sBlock = Array.isArray(item.block) ? item.block[0] : undefined;
+      if (sBlock) cache.set(sBlock._key, { rowKey: item._key, colKey: null });
+    } else if (isPageSectionV2(item)) {
+      const v2 = item as PageSectionV2;
+      for (const col of v2.columns) {
+        for (const b of col.blocks) {
+          cache.set(b._key, { rowKey: item._key, colKey: col._key });
+        }
+      }
+    } else if (isParallaxGroup(item)) {
+      const group = item as ParallaxGroup;
+      for (const slide of group.slides) {
+        for (const col of slide.columns) {
+          for (const b of col.blocks) {
+            cache.set(b._key, { rowKey: slide._key, colKey: col._key });
+          }
+        }
+      }
+    }
+  }
+
+  _blockParentCache = cache;
+  _blockParentCacheRowsRef = rows;
+  return cache;
+}
+
 // ============================================
 // Initial State
 // ============================================
@@ -90,6 +131,9 @@ const initialState: BuilderState = {
   _history: [],
   _future: [],
   _isTimeTraveling: false,
+
+  // Color picker live preview (Phase 4)
+  colorPickerPreview: null,
 };
 
 // ============================================
@@ -102,12 +146,13 @@ export const useBuilderStore = create<BuilderStore>((set, get) => ({
   // ---- Internal: push snapshot before mutations ----
 
   // BUG-010 fix: Snapshots now include pageSettings alongside rows
+  // RC-004 fix: Use functional set() for atomic read+write — prevents two
+  // rapid mutations from reading the same _history before either writes.
   _pushSnapshot: () => {
-    const state = get();
-    set({
+    set((state) => ({
       _history: pushSnapshot(state._history, { rows: state.rows, pageSettings: state.pageSettings }),
       _future: [], // new mutation clears redo stack
-    });
+    }));
   },
 
   // ---- History (Undo/Redo) ----
@@ -187,47 +232,15 @@ export const useBuilderStore = create<BuilderStore>((set, get) => ({
     }
     // BUG-002 fix: resolve parent row and column keys so SettingsPanel
     // and keyboard shortcuts always have consistent selection state.
+    // RC-003 fix: Use cached parent lookup — O(1) instead of O(n) iteration.
     const state = get();
-    let parentRowKey: string | null = null;
-    let parentColKey: string | null = null;
-
-    const searchColumns = (columns: import("../../lib/sanity/types").SectionColumn[], rowKey: string): boolean => {
-      for (const col of columns) {
-        if (col.blocks.some((b) => b._key === key)) {
-          parentRowKey = rowKey;
-          parentColKey = col._key;
-          return true;
-        }
-      }
-      return false;
-    };
-
-    for (const item of state.rows) {
-      if (isPageSection(item)) {
-        const sBlock = Array.isArray(item.block) ? item.block[0] : undefined;
-        if (sBlock && sBlock._key === key) {
-          parentRowKey = item._key;
-          break;
-        }
-      } else if (isPageSectionV2(item)) {
-        if (searchColumns(item.columns, item._key)) break;
-      } else if (isParallaxGroup(item)) {
-        const group = item as ParallaxGroup;
-        let found = false;
-        for (const slide of group.slides) {
-          // For parallax slides, the "row key" is the slide key (used as sectionKey)
-          if (searchColumns(slide.columns, slide._key)) {
-            found = true;
-            break;
-          }
-        }
-        if (found) break;
-      }
-    }
+    const cache = getBlockParentCache(state.rows);
+    const parent = cache.get(key);
+
     set({
       selectedBlockKey: key,
-      selectedRowKey: parentRowKey,
-      selectedColumnKey: parentColKey,
+      selectedRowKey: parent?.rowKey ?? null,
+      selectedColumnKey: parent?.colKey ?? null,
       selectedProjectCardKey: null,
     });
   },
@@ -325,6 +338,11 @@ export const useBuilderStore = create<BuilderStore>((set, get) => ({
   markDirty: () => set({ isDirty: true }),
   markClean: () => set({ isDirty: false }),
 
+  // ---- Color picker live preview (Phase 4) ----
+
+  setColorPickerPreview: (preview) => set({ colorPickerPreview: preview }),
+  clearColorPickerPreview: () => set({ colorPickerPreview: null }),
+
   // ---- Spread in action groups ----
 
   ...createSectionActions(set, get),

package/lib/builder/types.ts

@@ -16,6 +16,7 @@ import type {
   SectionV2Preset,
   SectionColumn,
   PageMetadata,
+  ColorField,
 } from "../../lib/sanity/types";
 import { DEFAULT_BG_COLOR, DEFAULT_TEXT_COLOR, DEFAULT_GRID_WIDTH } from "./constants";
 
@@ -229,6 +230,15 @@ export interface BuilderState {
    *  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>;
+
+  /** Live preview overlay from color picker — shown on canvas without persisting to Sanity.
+   *  Set while user is dragging in the color picker; cleared on close. */
+  colorPickerPreview: {
+    blockKey?: string;
+    sectionKey?: string;
+    field: string;
+    value: ColorField;
+  } | null;
 }
 
 export interface BuilderActions {
@@ -369,6 +379,10 @@ export interface BuilderActions {
   zoomToFit: (viewportWidth: number, viewportHeight: number) => void;
   zoomToPoint: (newZoom: number, cursorX: number, cursorY: number) => void;
   zoomToFrame: (device: DeviceViewport, viewportWidth: number, viewportHeight: number) => void;
+
+  // Color picker live preview (Phase 4)
+  setColorPickerPreview: (preview: BuilderState["colorPickerPreview"]) => void;
+  clearColorPickerPreview: () => void;
 }
 
 export type BuilderStore = BuilderState & BuilderActions;

package/lib/color-utils.ts

@@ -1,6 +1,9 @@
 /**
  * Centralized color conversion utilities.
  *
+ * Phase 2: Includes bridge functions for ColorField (solid + gradient).
+ * Renderers use these bridge functions instead of manipulating ColorField directly.
+ *
  * Previously duplicated across:
  *   - components/builder/ColorPicker.tsx (hexToHSL, hsvToHex, hexToHSV)
  *   - components/blocks/BlockRenderer.tsx (hexToRgba)
@@ -8,6 +11,8 @@
  *   - components/admin/nav-builder/nav-builder-utils.ts (hexToRgba)
  */
 
+import type { ColorField, GradientValue } from "./sanity/types";
+
 /** 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;
@@ -114,3 +119,198 @@ export function lerpHex(a: string, b: string, t: number): string {
   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")}`;
 }
+
+// ─── Deprecation warning flag (Phase 4) ───
+let _gradientOpacityWarned = false;
+
+// ─── ColorField Bridge Functions (Phase 2) ───
+
+/**
+ * Determines whether a ColorField value is a gradient (not a solid hex string).
+ */
+export function isGradient(value: ColorField): value is GradientValue {
+  return typeof value !== "string";
+}
+
+/**
+ * Converts a ColorField to a valid CSS string.
+ * This is the single conversion point for renderers.
+ */
+export function colorToCSS(value: ColorField): string {
+  if (typeof value === "string") return value;
+
+  switch (value.type) {
+    case "linear": {
+      const stops = value.stops
+        .map((s) => `${hexToRgba(s.color, s.alpha)} ${s.position}%`)
+        .join(", ");
+      return `linear-gradient(${value.angle}deg, ${stops})`;
+    }
+    case "radial": {
+      const stops = value.stops
+        .map((s) => `${hexToRgba(s.color, s.alpha)} ${s.position}%`)
+        .join(", ");
+      const shape = value.shape === "circle" ? "circle" : "ellipse";
+      return `radial-gradient(${shape} at ${value.position.x}% ${value.position.y}%, ${stops})`;
+    }
+    case "mesh": {
+      const layers = value.points
+        .map(
+          (p) =>
+            `radial-gradient(at ${p.x}% ${p.y}%, ${p.color} 0%, transparent 50%)`
+        )
+        .join(", ");
+      return `${layers}, ${value.background}`;
+    }
+  }
+}
+
+/**
+ * Extracts a representative hex color from a ColorField.
+ * For gradients, returns the first stop's color.
+ * Used for: text contrast checks, swatch preview, simple validations.
+ */
+export function resolveColorHex(value: ColorField): string {
+  if (typeof value === "string") return value;
+  switch (value.type) {
+    case "linear":
+    case "radial":
+      return value.stops[0]?.color ?? "#000000";
+    case "mesh":
+      return value.points[0]?.color ?? value.background;
+  }
+}
+
+/**
+ * Returns the correct CSS property object for a background color.
+ * - Solid: { backgroundColor: "#ff0000" }
+ * - Gradient: { backgroundImage: "linear-gradient(...)" }
+ *
+ * CSS requires `background-image` for gradients, not `background-color`.
+ */
+export function colorToCSSProperty(
+  value: ColorField,
+  opacity?: number // 0-100, only applies to solids
+): Record<string, string> {
+  if (typeof value === "string") {
+    if (opacity !== undefined && opacity < 100) {
+      return { backgroundColor: hexToRgba(value, opacity / 100) };
+    }
+    return { backgroundColor: value };
+  }
+  // Gradients: opacity is ignored (each stop has its own alpha)
+  if (opacity !== undefined && !_gradientOpacityWarned) {
+    _gradientOpacityWarned = true;
+    console.warn(
+      "[@morphika/andami] background_opacity is ignored for gradient colors. " +
+      "Control opacity per stop in the gradient editor."
+    );
+  }
+  // Mesh gradients need separate backgroundImage + backgroundColor
+  // because a plain color (#hex) is not valid inside background-image.
+  if (value.type === "mesh") {
+    const layers = value.points
+      .map(
+        (p) =>
+          `radial-gradient(at ${p.x}% ${p.y}%, ${p.color} 0%, transparent 50%)`
+      )
+      .join(", ");
+    return { backgroundImage: layers, backgroundColor: value.background };
+  }
+  return { backgroundImage: colorToCSS(value) };
+}
+
+/**
+ * Generates a CSS override rule string for responsive overrides.
+ * Returns the correct rule based on color type (with !important).
+ */
+export function colorToOverrideRule(
+  value: ColorField,
+  opacity?: number
+): string {
+  if (typeof value === "string") {
+    if (opacity !== undefined && opacity < 100) {
+      return `background-color:${hexToRgba(value, opacity / 100)}!important`;
+    }
+    return `background-color:${value}!important`;
+  }
+  if (opacity !== undefined && !_gradientOpacityWarned) {
+    _gradientOpacityWarned = true;
+    console.warn(
+      "[@morphika/andami] background_opacity is ignored for gradient colors. " +
+      "Control opacity per stop in the gradient editor."
+    );
+  }
+  // Mesh gradients need two rules: background-image for layers + background-color for base
+  if (value.type === "mesh") {
+    const layers = value.points
+      .map(
+        (p) =>
+          `radial-gradient(at ${p.x}% ${p.y}%, ${p.color} 0%, transparent 50%)`
+      )
+      .join(", ");
+    return `background-image:${layers}!important;background-color:${value.background}!important`;
+  }
+  return `background-image:${colorToCSS(value)}!important`;
+}
+
+/**
+ * Generates CSS for border with color.
+ * - Solid: standard border shorthand.
+ * - Gradient: border-image.
+ */
+export function borderColorToCSS(
+  value: ColorField,
+  width: number,
+  style: string
+): Record<string, string> {
+  if (typeof value === "string") {
+    return { border: `${width}px ${style} ${value}` };
+  }
+  return {
+    border: `${width}px ${style} transparent`,
+    borderImage: `${colorToCSS(value)} 1`,
+  };
+}
+
+/**
+ * Generates a CSS override rule for border-color in responsive overrides.
+ * - Solid: `border-color:X!important`
+ * - Gradient: `border-image:X 1!important;border-color:transparent!important`
+ */
+export function borderColorToOverrideRule(value: ColorField): string {
+  if (typeof value === "string") {
+    return `border-color:${value}!important`;
+  }
+  return `border-color:transparent!important;border-image:${colorToCSS(value)} 1!important`;
+}
+
+/**
+ * Parse a raw Sanity field value into a typed ColorField.
+ * - Hex strings pass through as-is
+ * - JSON strings starting with "{" are parsed as GradientValue
+ * - Anything else falls back to "#000000"
+ */
+export function parseColorField(raw: unknown): ColorField {
+  if (typeof raw === "string") {
+    if (raw.startsWith("{")) {
+      try {
+        return JSON.parse(raw) as GradientValue;
+      } catch {
+        return raw;
+      }
+    }
+    return raw;
+  }
+  return "#000000";
+}
+
+/**
+ * Serialize a ColorField for storage in Sanity.
+ * - Hex strings are stored as-is
+ * - Gradient objects are JSON-stringified
+ */
+export function serializeColorField(value: ColorField): string {
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}

package/lib/config/index.ts

@@ -1,57 +1,28 @@
-/**
+/**
  * 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.
+ * Uses globalThis + Symbol.for to guarantee a true singleton even when
+ * the bundler creates multiple module instances of this file.
  */
 
 import type { SiteConfig } from "./types";
 
-/** Module-level slot for the registered config. */
-let _registeredConfig: SiteConfig | null = null;
+const CONFIG_KEY = Symbol.for("@morphika/andami/siteConfig");
+const g = globalThis as unknown as Record<symbol, SiteConfig | undefined>;
 
-/** 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;
+  g[CONFIG_KEY] = config;
 }
 
-/**
- * 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",
-      );
-    }
+  const cfg = g[CONFIG_KEY];
+  if (!cfg) {
+    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;
+  return cfg;
 }
 
-// Re-export types for convenience
-export type { SiteConfig } from "./types";
+export type { SiteConfig } from "./types";

package/lib/revalidate.ts

@@ -1,5 +1,5 @@
-import { csrfHeaders } from "../lib/csrf-client";
-import { logger } from "../lib/logger";
+import { csrfHeaders } from "./csrf-client";
+import { logger } from "./logger";
 
 /**
  * Trigger on-demand ISR revalidation from the admin UI.