@morphika/andami 0.1.2

package/lib/animation/hover-effect-types.ts

@@ -0,0 +1,126 @@
+/**
+ * Hover Effect System — Type definitions
+ *
+ * Unified hover effects that combine CSS-based hovers (scale-up, lift, etc.)
+ * and shader-based hovers (ripple, rgb-shift, pixelate) into one type system.
+ *
+ * Block-level only — no cascade. Each block type has a curated set of
+ * available hover presets.
+ *
+ * Session 116 — Animation UX Refactor.
+ */
+
+import type { ContentBlock } from "../../lib/sanity/types";
+
+type BlockType = ContentBlock["_type"];
+
+// ── Easing ─────────────────────────────────────────────────────────
+
+export type HoverEasing =
+  | "ease"
+  | "ease-in"
+  | "ease-out"
+  | "ease-in-out"
+  | "linear";
+
+// ── Shader smoothness ──────────────────────────────────────────────
+
+export type ShaderSmoothness = "snappy" | "normal" | "smooth";
+
+// ── CSS-based hover presets ────────────────────────────────────────
+
+export type CSSHoverPreset =
+  | "none"
+  | "scale-up"
+  | "scale-down"
+  | "lift"
+  | "tilt-3d"
+  | "color-shift"
+  | "blur-reveal"
+  | "border-glow";
+
+// ── Shader-based hover presets ─────────────────────────────────────
+
+export type ShaderHoverPreset =
+  | "ripple"
+  | "rgb-shift"
+  | "pixelate";
+
+/**
+ * Union of ALL hover presets — CSS-based + shader-based.
+ * Used as the field type in HoverEffectConfig.
+ */
+export type HoverPreset = CSSHoverPreset | ShaderHoverPreset;
+
+// ── Per-block-type preset registry ─────────────────────────────────
+
+/**
+ * Which hover presets are available for each block type.
+ * Empty array = no hover effects available for that block type.
+ *
+ * Based on the registry table in ANIMATION-UX-ROADMAP.md.
+ */
+export const BLOCK_HOVER_PRESETS: Record<BlockType, readonly HoverPreset[]> = {
+  textBlock:              [],   // text hovers feel wrong
+  imageBlock:             ["scale-up", "lift", "tilt-3d", "ripple", "rgb-shift", "pixelate"],
+  imageGridBlock:         ["tilt-3d"],
+  videoBlock:             [],   // video has play/pause interaction
+  buttonBlock:            ["scale-up", "lift", "border-glow"],
+  coverBlock:             ["scale-up", "lift", "ripple", "rgb-shift", "pixelate"],
+  spacerBlock:            [],   // invisible
+  projectGridBlock:       ["scale-up", "lift"],  // per-card effect
+};
+
+// ── Hover effect config ────────────────────────────────────────────
+
+/**
+ * Unified hover effect config. Replaces both HoverAnimationConfig
+ * and ShaderEffectConfig.
+ *
+ * Stored on blocks only (no cascade — hover is block-level).
+ * Shader-specific fields are only relevant when preset is a ShaderHoverPreset.
+ */
+export interface HoverEffectConfig {
+  preset?: HoverPreset;
+  duration?: number;                  // ms, default 300 (CSS transitions)
+  easing?: HoverEasing;              // default "ease-out"
+  // Shader-specific (only when preset is ripple/rgb-shift/pixelate):
+  shader_speed?: number;             // 0.5–3.0, default 1.0
+  shader_smoothness?: ShaderSmoothness; // default "normal"
+}
+
+/**
+ * Fully resolved config — all fields present.
+ */
+export interface ResolvedHoverEffectConfig {
+  preset: HoverPreset;
+  duration: number;
+  easing: HoverEasing;
+  shader_speed: number;
+  shader_smoothness: ShaderSmoothness;
+}
+
+// ── Defaults ───────────────────────────────────────────────────────
+
+export const HOVER_EFFECT_DEFAULTS: ResolvedHoverEffectConfig = {
+  preset: "none",
+  duration: 300,
+  easing: "ease-out",
+  shader_speed: 1.0,
+  shader_smoothness: "normal",
+};
+
+// ── Resolved shader config (used by ShaderCanvas / HoverAnimationWrapper) ──
+// Moved here from lib/shader/types.ts in Session 122.
+
+/**
+ * Fully resolved shader effect config — all fields guaranteed.
+ * Used internally by ShaderCanvas and HoverAnimationWrapper.
+ */
+export interface ResolvedShaderEffectConfig {
+  preset: ShaderHoverPreset | "none";
+  trigger: "hover" | "scroll";
+  intensity: number;
+  speed: number;
+  smoothing: number;  // Resolved from ShaderSmoothness → lerp factor
+}

package/lib/asset-retry.ts

@@ -0,0 +1,111 @@
+/**
+ * Client-side asset retry utilities with cache busting and visual feedback.
+ *
+ * When an image/video fails to load, the browser may have cached the
+ * 302 redirect from /api/assets/... pointing to a stale link.
+ * Simply re-setting `img.src = img.src` would reuse that cached redirect.
+ *
+ * Cache busting appends `?_r=N&t=<timestamp>` to force the browser to
+ * make a fresh request to the API route, which generates a new link.
+ *
+ * Visual feedback: after exhausting retries, elements get a `data-asset-failed`
+ * attribute that CSS uses to show a subtle placeholder instead of the browser's
+ * broken image icon. A manual retry is available via click/tap.
+ */
+
+/** Max retry attempts for media that fails to load */
+export const MAX_RETRIES = 3;
+
+/** Data attribute to track retry count */
+export const RETRY_ATTR = "data-retries";
+
+/** Data attribute set when all retries are exhausted */
+export const FAILED_ATTR = "data-asset-failed";
+
+/** Backoff delays in ms for each retry (exponential: 1s, 2s, 4s) */
+const RETRY_DELAYS = [1000, 2000, 4000];
+
+/**
+ * Strip any existing retry query params from a URL, then append fresh ones.
+ * This ensures each retry gets a unique URL that bypasses the browser cache.
+ */
+export function cacheBustUrl(url: string, retryCount: number): string {
+  // Remove existing retry params
+  const base = url.replace(/[?&](_r|t)=[^&]*/g, "").replace(/\?$/, "");
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}_r=${retryCount}&t=${Date.now()}`;
+}
+
+/**
+ * Mark an element as failed and show visual placeholder.
+ * The element becomes clickable to trigger a manual retry.
+ */
+function markAsFailed(el: HTMLImageElement | HTMLVideoElement) {
+  el.setAttribute(FAILED_ATTR, "1");
+
+  // For images: make the broken icon invisible and show a CSS placeholder via parent
+  if (el instanceof HTMLImageElement) {
+    // Store original src for manual retry
+    if (!el.dataset.originalSrc) {
+      el.dataset.originalSrc = el.src.replace(/[?&](_r|t)=[^&]*/g, "").replace(/\?$/, "");
+    }
+    // Set up manual retry on click
+    el.style.cursor = "pointer";
+    el.title = "Tap to retry loading";
+    el.removeEventListener("click", manualRetryHandler);
+    el.addEventListener("click", manualRetryHandler);
+  }
+}
+
+/**
+ * Manual retry handler — resets retry counter and tries again with fresh cache bust.
+ */
+function manualRetryHandler(e: Event) {
+  const img = e.currentTarget as HTMLImageElement;
+  img.removeAttribute(FAILED_ATTR);
+  img.removeAttribute(RETRY_ATTR);
+  img.style.cursor = "";
+  img.title = "";
+  img.src = cacheBustUrl(img.dataset.originalSrc || img.src, 0);
+}
+
+/**
+ * Generic onError handler for <img> elements with cache-busting retry.
+ * Use directly as `onError={handleImageRetry}` or wrap in useCallback.
+ *
+ * After MAX_RETRIES, sets `data-asset-failed` attribute for CSS-based
+ * visual feedback and enables click-to-retry.
+ */
+export function handleImageRetry(e: React.SyntheticEvent<HTMLImageElement>) {
+  const img = e.currentTarget;
+  const retries = parseInt(img.getAttribute(RETRY_ATTR) || "0", 10);
+  if (retries < MAX_RETRIES) {
+    const next = retries + 1;
+    img.setAttribute(RETRY_ATTR, String(next));
+    const delay = RETRY_DELAYS[retries] ?? RETRY_DELAYS[RETRY_DELAYS.length - 1];
+    setTimeout(() => {
+      img.src = cacheBustUrl(img.src, next);
+    }, delay);
+  } else {
+    markAsFailed(img);
+  }
+}
+
+/**
+ * Generic onError handler for <video> elements with cache-busting retry.
+ */
+export function handleVideoRetry(e: React.SyntheticEvent<HTMLVideoElement>) {
+  const video = e.currentTarget;
+  const retries = parseInt(video.getAttribute(RETRY_ATTR) || "0", 10);
+  if (retries < MAX_RETRIES) {
+    const next = retries + 1;
+    video.setAttribute(RETRY_ATTR, String(next));
+    const delay = RETRY_DELAYS[retries] ?? RETRY_DELAYS[RETRY_DELAYS.length - 1];
+    setTimeout(() => {
+      video.src = cacheBustUrl(video.src, next);
+      video.load();
+    }, delay);
+  } else {
+    markAsFailed(video);
+  }
+}

package/lib/assets.ts

@@ -0,0 +1,92 @@
+/**
+ * Asset URL resolution — provider-aware.
+ *
+ * Assets are stored as relative paths in Sanity (e.g. "projects/hero.jpg").
+ * This module resolves them to full URLs based on the active storage provider.
+ *
+ * Resolution strategies:
+ *
+ * 1. **R2 direct URL (fastest):** If `NEXT_PUBLIC_R2_BUCKET_URL` is set,
+ *    assets resolve directly to the R2 CDN URL. No proxy, no API call.
+ *    This is baked into the client bundle at build time.
+ *
+ * 2. **Proxy fallback (runtime switching):** If no R2 env var, assets go
+ *    through `/api/assets/[...path]` which checks the active provider at
+ *    runtime and redirects accordingly. This supports provider switching
+ *    without redeploying.
+ *
+ * @example
+ * assetUrl("projects/house-of-delights/cover.jpg")
+ * // R2 direct:  "https://assets.example.com/projects/house-of-delights/cover.jpg"
+ * // Or proxy:   "/api/assets/projects/house-of-delights/cover.jpg"
+ */
+
+import { logger } from "../lib/logger";
+
+/**
+ * Resolve a relative asset path to a full URL (public site).
+ *
+ * Priority:
+ * 1. NEXT_PUBLIC_R2_BUCKET_URL → direct R2 CDN URL (zero latency)
+ * 2. NEXT_PUBLIC_ASSET_BASE_URL → custom base (e.g. "/api/assets")
+ * 3. "/api/assets" → default proxy route
+ */
+export function assetUrl(path: string | undefined | null): string {
+  if (!path) {
+    if (process.env.NODE_ENV === "development") {
+      logger.warn("[Assets]", "assetUrl() called with empty path");
+    }
+    return "/placeholder-asset.svg";
+  }
+
+  // #7: Normalize path — strip all leading slashes to prevent double-slash URLs
+  const cleanPath = path.replace(/^\/+/, "");
+
+  // R2 direct mode: when env var is set, skip proxy entirely.
+  // This is the zero-latency path — URL resolves to R2 CDN directly.
+  const r2Base = process.env.NEXT_PUBLIC_R2_BUCKET_URL;
+  if (r2Base) {
+    return `${r2Base.replace(/\/+$/, "")}/${cleanPath}`;
+  }
+
+  // Proxy mode: route through /api/assets which handles provider detection
+  // at runtime (supports provider switching without env var changes).
+  const base = process.env.NEXT_PUBLIC_ASSET_BASE_URL;
+  const resolvedBase = base || "/api/assets";
+  return `${resolvedBase.replace(/\/+$/, "")}/${cleanPath}`;
+}
+
+/**
+ * Resolve a relative asset path via the admin proxy.
+ *
+ * In the editor (/admin), images load through `/api/admin/assets/file?path=...`
+ * which handles auth + provider detection internally (R2 direct URL redirect).
+ */
+export function adminAssetUrl(path: string | undefined | null): string {
+  if (!path) return "/placeholder-asset.svg";
+  return `/api/admin/assets/file?path=${encodeURIComponent(path)}`;
+}
+
+/**
+ * Resolve a relative asset path to its thumbnail URL (public).
+ *
+ * Thumbnails live in `_thumbs/{original_path}` with .jpg extension.
+ * The base URL resolution is provider-aware (same as assetUrl).
+ */
+export function thumbUrl(path: string | undefined | null): string {
+  if (!path) return assetUrl(path);
+  // #40: Case-insensitive extension replacement for thumbnails (.JPG, .PNG, etc.)
+  const thumbPath = `_thumbs/${path.replace(/\.[^.]+$/i, ".jpg")}`;
+  return assetUrl(thumbPath);
+}
+
+/**
+ * Resolve a relative asset path to its thumbnail URL (admin proxy).
+ *
+ * Same as thumbUrl but routes through the admin proxy for builder use.
+ */
+export function adminThumbUrl(path: string | undefined | null): string {
+  if (!path) return adminAssetUrl(path);
+  const thumbPath = `_thumbs/${path.replace(/\.[^.]+$/, ".jpg")}`;
+  return adminAssetUrl(thumbPath);
+}

package/lib/audit.ts

@@ -0,0 +1,35 @@
+/**
+ * Structured audit logging for admin operations.
+ *
+ * Logs admin actions with consistent format to server console.
+ * Future: can be extended to write to a persistent store
+ * (e.g., Sanity document, external logging service).
+ */
+
+export interface AuditLogEntry {
+  /** Action performed: 'page.create', 'settings.update', 'r2.connect', etc. */
+  action: string;
+  /** Timestamp of the action */
+  timestamp: string;
+  /** Additional context about the action */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Log an admin action to the server console with structured format.
+ *
+ * Usage:
+ *   auditLog("page.create", { slug: "about", page_type: "about" });
+ *   auditLog("settings.update", { section: "navigation" });
+ *   auditLog("r2.connect", { bucket: "my-assets" });
+ */
+export function auditLog(action: string, details?: Record<string, unknown>): void {
+  const entry: AuditLogEntry = {
+    action,
+    timestamp: new Date().toISOString(),
+    ...(details ? { details } : {}),
+  };
+
+  // Structured JSON log — easily parseable by log aggregation tools
+  console.log(`[AUDIT] ${JSON.stringify(entry)}`);
+}

package/lib/auth-token.ts

@@ -0,0 +1,94 @@
+/**
+ * Admin token generation & validation using HMAC-SHA256.
+ * Uses Web Crypto API (works in Edge Runtime, Node.js, and browsers).
+ *
+ * Security: Tokens include a timestamp nonce and use a dedicated server-side
+ * secret (ADMIN_TOKEN_SECRET). Tokens expire after 24 hours.
+ *
+ * Used by: middleware.ts, lib/auth.ts, app/api/admin/auth/route.ts
+ */
+
+const encoder = new TextEncoder();
+
+/** Token validity period: 24 hours */
+const TOKEN_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Derive the HMAC signing key from server-side secrets.
+ * Uses ADMIN_TOKEN_SECRET (preferred) with password as fallback component.
+ */
+async function getSigningKey(password: string): Promise<CryptoKey> {
+  const tokenSecret = process.env.ADMIN_TOKEN_SECRET || "";
+  if (!tokenSecret) {
+    console.warn(
+      "[Security] ADMIN_TOKEN_SECRET is not set. Token security is degraded. " +
+      "Set this env var for production. Generate one with: openssl rand -base64 32"
+    );
+  }
+  // Combine dedicated secret + password for key material
+  const keyMaterial = `${tokenSecret}:${password}`;
+  return crypto.subtle.importKey(
+    "raw",
+    encoder.encode(keyMaterial),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+
+/**
+ * Sign a payload string with HMAC-SHA256 and return hex.
+ */
+async function hmacSign(key: CryptoKey, payload: string): Promise<string> {
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return Array.from(new Uint8Array(signature))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Generate a new admin token with embedded timestamp nonce.
+ * Format: `{timestamp}.{hmac_hex}`
+ */
+export async function generateAdminToken(password: string): Promise<string> {
+  const timestamp = Date.now().toString();
+  const key = await getSigningKey(password);
+  const signature = await hmacSign(key, `admin_session:${timestamp}`);
+  return `${timestamp}.${signature}`;
+}
+
+/**
+ * Validate an admin token: check format, expiration, and HMAC signature.
+ * Returns true if the token is valid and not expired.
+ */
+export async function validateAdminToken(token: string): Promise<boolean> {
+  const pw = process.env.ADMIN_PASSWORD;
+  if (!pw) return false;
+
+  // Parse token format: timestamp.signature
+  const dotIndex = token.indexOf(".");
+  if (dotIndex === -1) return false;
+
+  const timestamp = token.substring(0, dotIndex);
+  const providedSignature = token.substring(dotIndex + 1);
+
+  // Validate timestamp is a number
+  const tokenTime = parseInt(timestamp, 10);
+  if (isNaN(tokenTime)) return false;
+
+  // Check token expiration (24h)
+  const age = Date.now() - tokenTime;
+  if (age < 0 || age > TOKEN_MAX_AGE_MS) return false;
+
+  // Recompute expected signature and compare
+  const key = await getSigningKey(pw);
+  const expectedSignature = await hmacSign(key, `admin_session:${timestamp}`);
+
+  // Constant-time comparison to prevent timing attacks
+  if (providedSignature.length !== expectedSignature.length) return false;
+  let mismatch = 0;
+  for (let i = 0; i < expectedSignature.length; i++) {
+    mismatch |= providedSignature.charCodeAt(i) ^ expectedSignature.charCodeAt(i);
+  }
+  return mismatch === 0;
+}

package/lib/auth.ts

@@ -0,0 +1,13 @@
+import { cookies } from "next/headers";
+import { validateAdminToken } from "../lib/auth-token";
+
+/**
+ * Verify that the current request is authenticated as admin.
+ * For use in server-side API routes and Server Components.
+ */
+export async function isAdminAuthenticated(): Promise<boolean> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get("admin_token")?.value;
+  if (!token) return false;
+  return validateAdminToken(token);
+}

package/lib/builder/cascade-helpers.ts

@@ -0,0 +1,51 @@
+/**
+ * Helper utilities for the cascade engine.
+ *
+ * Extracted from store.ts to reduce duplication and enable unit testing.
+ * The main pattern here is mapping cascade engine output (lightweight position objects)
+ * back to full SectionColumn objects (preserving blocks).
+ */
+
+import type { SectionColumn, ContentBlock } from "../../lib/sanity/types";
+import type { CascadeColumn } from "./cascade";
+
+// Re-export so existing consumers that import from cascade-helpers still work
+export type { CascadeColumn } from "./cascade";
+
+/**
+ * Map cascade engine output back to full SectionColumn objects,
+ * preserving blocks from the original columns.
+ *
+ * The cascade engine only deals with positions (_key, grid_column, grid_row, span).
+ * This function re-attaches the blocks from the original columns by key lookup.
+ * New columns (not in the block map) get empty block arrays.
+ */
+export function applyBlocksToColumns(
+  cascadeResult: CascadeColumn[],
+  originalColumns: SectionColumn[]
+): SectionColumn[] {
+  const blockMap = new Map<string, ContentBlock[]>(
+    originalColumns.map((c) => [c._key, c.blocks])
+  );
+
+  return cascadeResult.map((cc) => ({
+    _key: cc._key,
+    grid_column: cc.grid_column,
+    grid_row: cc.grid_row,
+    span: cc.span,
+    blocks: blockMap.get(cc._key) || [],
+  }));
+}
+
+/**
+ * Extract lightweight cascade columns from full SectionColumns.
+ * Used as input to cascade engine functions.
+ */
+export function toCascadeColumns(columns: SectionColumn[]): CascadeColumn[] {
+  return columns.map((c) => ({
+    _key: c._key,
+    grid_column: c.grid_column,
+    grid_row: c.grid_row,
+    span: c.span,
+  }));
+}