@morphika/webframe 0.1.0

package/lib/config/types.ts

@@ -0,0 +1,122 @@
+/**
+ * SiteConfig — Central configuration interface for the builder product.
+ *
+ * Each deployment has its own `site.config.ts` at the project root.
+ * All branding, defaults, and feature toggles live here instead of
+ * being hardcoded throughout the codebase.
+ */
+
+export interface SiteConfig {
+  // ── Identity ──
+  /** Site name (used in metadata, admin sidebar, fallback heading) */
+  name: string;
+  /** Production domain (used in metadataBase, JSDoc examples) */
+  domain: string;
+  /** Admin panel title shown on the login page */
+  adminTitle: string;
+  /** HTML lang attribute (default: "en") */
+  lang?: string;
+
+  // ── Sanity ──
+  sanity: {
+    /** Sanity Studio project name identifier */
+    projectName: string;
+    /** Sanity Studio title shown in the UI */
+    studioTitle: string;
+    /** Labels for the Sanity Studio sidebar. English defaults used if omitted. */
+    studioLabels?: {
+      /** Root list title (default: "Content") */
+      content?: string;
+      /** Master pages group (default: "Master Pages") */
+      masterPages?: string;
+      /** Projects list (default: "Projects") */
+      projects?: string;
+      /** All pages list (default: "All Pages") */
+      allPages?: string;
+      /** Site settings label (default: "Site Settings") */
+      siteSettings?: string;
+      /** Asset registry label (default: "Asset Registry") */
+      assetRegistry?: string;
+    };
+  };
+
+  // ── Defaults (overrideable in admin) ──
+  defaults: {
+    /** Default logo text for the navbar */
+    logoText: string;
+    /** Default meta title for SEO */
+    metaTitle: string;
+    /** Default meta description for SEO */
+    metaDescription: string;
+  };
+
+  // ── Brand palette (fallback before admin configures styles) ──
+  palette: {
+    /** Page background */
+    background: string;
+    /** Default text color */
+    text: string;
+    /** Primary brand color (cursor border, buttons, links) */
+    primary: string;
+    /** Secondary brand color (cursor fill, accents) */
+    secondary: string;
+    /** Accent color (headings, highlights) */
+    accent: string;
+    /** Muted/gray for captions, subtle text */
+    muted: string;
+    /** Alternative accent (mapped to --color-brand-accent). Falls back to accent if omitted. */
+    accentAlt?: string;
+    /** Second accent color (mapped to --color-brand-accent-2). Optional. */
+    accent2?: string;
+    /** Dark background (mapped to --color-brand-dark). Falls back to background if omitted. */
+    dark?: string;
+  };
+
+  // ── Typography fallback ──
+  typography: {
+    /** Default font family name (loaded via @font-face or admin upload) */
+    defaultFont: string;
+    /** Monospace font stack fallback */
+    monoFallback: string;
+    /** Sans-serif font stack fallback */
+    sansFallback: string;
+    /**
+     * Built-in font files shipped with the instance (in public/fonts/).
+     * These are injected as @font-face rules by StylesProvider before
+     * admin styles load, preventing FOUT on first render.
+     * If omitted, only admin-uploaded fonts are available.
+     */
+    builtinFonts?: Array<{
+      family: string;
+      src: string;
+      weight?: string;
+      style?: string;
+    }>;
+  };
+
+  // ── Feature toggles ──
+  features: {
+    /** Show custom cursor on desktop (public site only) */
+    customCursor: boolean;
+    /** Enable portfolio/campaign visit tracking */
+    portfolioTracking: boolean;
+    /** Enable page exit animations (reverse enter/load animations on navigate) */
+    pageExitAnimations: boolean;
+    /** Disable scroll animations on mobile (< 768px) */
+    mobileAnimationDisable: boolean;
+    /** Enable WebGL shader effects on images (public site only) */
+    shaderEffects: boolean;
+  };
+
+  // ── Tracking (optional) ──
+  tracking: {
+    /** Knock API URL for visit tracking. Empty = tracking disabled. */
+    knockApiUrl: string;
+    /** Prefix for sessionStorage keys used by the tracker */
+    sessionPrefix: string;
+  };
+
+  // ── Storage keys prefix ──
+  /** Prefix for all localStorage/sessionStorage keys (canvas state, preferences, etc.) */
+  storagePrefix: string;
+}

package/lib/contexts/AssetContext.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import {
+  assetUrl as defaultAssetUrl,
+  adminAssetUrl,
+  thumbUrl as defaultThumbUrl,
+  adminThumbUrl,
+} from "../../lib/assets";
+
+/**
+ * AssetContext — allows overriding how asset paths resolve to URLs.
+ *
+ * Three modes:
+ *
+ * - **default:** Uses `assetUrl()` / `thumbUrl()`. Provider-aware:
+ *   - If `NEXT_PUBLIC_R2_BUCKET_URL` is set → direct R2 CDN URLs
+ *   - Otherwise → `/api/assets/...` proxy (resolves provider at runtime)
+ *
+ * - **admin:** Uses `adminAssetUrl()` / `adminThumbUrl()`. Routes through
+ *   `/api/admin/assets/file?path=...` which requires auth and handles
+ *   provider detection internally (redirects to active provider).
+ *
+ * - **r2-direct:** Uses `assetUrl()` (same as default). Useful for admin
+ *   preview when R2 is active and NEXT_PUBLIC_R2_BUCKET_URL is set —
+ *   bypasses the admin proxy for direct CDN URLs. Falls back to proxy
+ *   if the env var isn't set (same as default mode).
+ *
+ * `useThumbUrl()` returns the corresponding thumbnail resolver for each mode.
+ */
+
+type AssetResolver = (path: string | undefined | null) => string;
+
+interface AssetResolvers {
+  resolveAsset: AssetResolver;
+  resolveThumb: AssetResolver;
+}
+
+const AssetContext = createContext<AssetResolvers>({
+  resolveAsset: defaultAssetUrl,
+  resolveThumb: defaultThumbUrl,
+});
+
+/** Returns the full-resolution asset URL resolver */
+export function useAssetUrl(): AssetResolver {
+  return useContext(AssetContext).resolveAsset;
+}
+
+/** Returns the thumbnail URL resolver */
+export function useThumbUrl(): AssetResolver {
+  return useContext(AssetContext).resolveThumb;
+}
+
+export function AssetProvider({
+  mode,
+  children,
+}: {
+  mode: "default" | "admin" | "r2-direct";
+  children: ReactNode;
+}) {
+  const resolvers: AssetResolvers = (() => {
+    switch (mode) {
+      case "admin":
+        return { resolveAsset: adminAssetUrl, resolveThumb: adminThumbUrl };
+      case "r2-direct":
+        // Use default resolvers (which check NEXT_PUBLIC_R2_BUCKET_URL first).
+        // If the env var is set → direct R2 CDN URLs.
+        // If not → falls through to proxy (same as "default").
+        return { resolveAsset: defaultAssetUrl, resolveThumb: defaultThumbUrl };
+      case "default":
+      default:
+        return { resolveAsset: defaultAssetUrl, resolveThumb: defaultThumbUrl };
+    }
+  })();
+
+  return (
+    <AssetContext.Provider value={resolvers}>{children}</AssetContext.Provider>
+  );
+}

package/lib/contexts/NavAnimationContext.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+/**
+ * NavAnimationContext — Per-page nav entrance animation override.
+ *
+ * Same pattern as NavColorContext: the Navbar reads from this context,
+ * and each page can push overrides via the PageNavAnimation component.
+ *
+ * Session 115: Created for per-page nav entrance animation overrides.
+ */
+
+import { createContext, useContext, useState, useCallback, type ReactNode } from "react";
+import type { NavEntrancePreset } from "../../lib/sanity/types";
+
+interface NavAnimationOverride {
+  preset?: NavEntrancePreset;
+  duration?: number;
+  delay?: number;
+  disabled?: boolean;
+}
+
+interface NavAnimationContextValue {
+  override: NavAnimationOverride;
+  setOverride: (o: NavAnimationOverride) => void;
+}
+
+const NavAnimationContext = createContext<NavAnimationContextValue>({
+  override: {},
+  setOverride: () => {},
+});
+
+export function NavAnimationProvider({ children }: { children: ReactNode }) {
+  const [override, setOverrideState] = useState<NavAnimationOverride>({});
+  const setOverride = useCallback((o: NavAnimationOverride) => setOverrideState(o), []);
+  return (
+    <NavAnimationContext.Provider value={{ override, setOverride }}>
+      {children}
+    </NavAnimationContext.Provider>
+  );
+}
+
+export function useNavAnimation() {
+  return useContext(NavAnimationContext);
+}

package/lib/contexts/NavColorContext.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { createContext, useContext, useState, useCallback } from "react";
+
+interface NavColorContextType {
+  /** Hex color string (e.g. "#ffffff") or empty for default */
+  navColor: string;
+  setNavColor: (color: string) => void;
+}
+
+const NavColorContext = createContext<NavColorContextType>({
+  navColor: "",
+  setNavColor: () => {},
+});
+
+export function NavColorProvider({
+  children,
+  initialColor = "",
+}: {
+  children: React.ReactNode;
+  initialColor?: string;
+}) {
+  const [navColor, setNavColorState] = useState<string>(initialColor);
+
+  const setNavColor = useCallback((color: string) => {
+    setNavColorState(color);
+  }, []);
+
+  return (
+    <NavColorContext.Provider value={{ navColor, setNavColor }}>
+      {children}
+    </NavColorContext.Provider>
+  );
+}
+
+export function useNavColor() {
+  return useContext(NavColorContext);
+}

package/lib/contexts/PageExitContext.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+/**
+ * PageExitContext — intercepts internal link clicks, plays reverse exit
+ * animations on enter/load-triggered elements, then navigates.
+ *
+ * How it works:
+ * 1. A capture-phase click handler on the site container intercepts internal <a> clicks
+ *    BEFORE Next.js Link processes them (capture fires before bubble).
+ * 2. For each animated element (enter/load trigger), the current animation is reset
+ *    and replayed in reverse via animation-direction: reverse.
+ * 3. After the exit duration (capped at 600ms), router.push() fires the navigation.
+ *
+ * Skipped when:
+ * - prefers-reduced-motion is set
+ * - No animated elements exist on the page
+ * - Click originated from the mobile menu overlay (instant nav feels better)
+ * - Modifier keys held (Cmd+click → new tab)
+ * - Already exiting
+ */
+
+import {
+  createContext,
+  useContext,
+  useRef,
+  useState,
+  useEffect,
+  useCallback,
+  type ReactNode,
+} from "react";
+import { useRouter, usePathname } from "next/navigation";
+
+interface PageExitContextValue {
+  /** True while exit animations are playing before navigation */
+  isExiting: boolean;
+}
+
+const PageExitContext = createContext<PageExitContextValue>({ isExiting: false });
+
+export function usePageExit() {
+  return useContext(PageExitContext);
+}
+
+// Selector for elements with completed enter animations (new system: data-entered)
+const ANIMATED_SELECTOR = '[data-entered]';
+
+export function PageExitProvider({ children }: { children: ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const [isExiting, setIsExiting] = useState(false);
+  const exitingRef = useRef(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Reset exiting state when pathname changes (navigation completed)
+  useEffect(() => {
+    exitingRef.current = false;
+    setIsExiting(false);
+  }, [pathname]);
+
+  /**
+   * Trigger exit animations on all enter/load elements, then navigate.
+   */
+  const triggerExit = useCallback(
+    (href: string) => {
+      if (exitingRef.current) return;
+
+      // Respect prefers-reduced-motion
+      if (
+        typeof window !== "undefined" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches
+      ) {
+        router.push(href);
+        return;
+      }
+
+      // Find animated elements eligible for exit
+      const elements = document.querySelectorAll<HTMLElement>(ANIMATED_SELECTOR);
+
+      if (elements.length === 0) {
+        router.push(href);
+        return;
+      }
+
+      exitingRef.current = true;
+      setIsExiting(true);
+
+      let maxDuration = 0;
+
+      elements.forEach((el) => {
+        // Card entrance elements get a simple fade-out instead of reverse
+        // (reversing slide-up → slide-down looks wrong for grid cards)
+        const isCardEntrance = el.closest("[data-card-entrance]") !== null;
+
+        // Read current animation values (set as inline styles by React)
+        const name = el.style.animationName;
+        const dur = el.style.animationDuration || "600ms";
+        const timing = el.style.animationTimingFunction || "ease-out";
+
+        if (!name || name === "none") return;
+
+        const ms = parseFloat(dur); // React sets "600ms" format
+        if (ms > maxDuration) maxDuration = ms;
+
+        // Reset animation to force browser to re-trigger
+        el.style.animation = "none";
+        void el.offsetHeight; // force reflow
+
+        if (isCardEntrance) {
+          // Simple fade-out for card entrance elements
+          el.style.animationName = "enter-fade";
+          el.style.animationDuration = "400ms";
+          el.style.animationDirection = "reverse";
+          el.style.animationFillMode = "forwards";
+          el.style.animationTimingFunction = "ease-out";
+          el.style.animationDelay = "0ms";
+        } else {
+          // Standard reverse for all other animated elements
+          el.style.animationName = name;
+          el.style.animationDuration = dur;
+          el.style.animationDirection = "reverse";
+          el.style.animationFillMode = "forwards";
+          el.style.animationTimingFunction = timing;
+          el.style.animationDelay = "0ms";
+        }
+      });
+
+      // Navigate after exit completes — use 70% of duration (exits feel
+      // snappier than entrances), capped at 600ms.
+      const exitTime = Math.min(Math.max(maxDuration * 0.7, 200), 600);
+      setTimeout(() => {
+        router.push(href);
+      }, exitTime);
+    },
+    [router],
+  );
+
+  // ── Global click interceptor (capture phase) ──
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleClick = (e: MouseEvent) => {
+      // Block link clicks while exit is in progress
+      if (exitingRef.current) {
+        const anchor = (e.target as HTMLElement).closest("a[href]");
+        if (anchor) e.preventDefault();
+        return;
+      }
+
+      const anchor = (e.target as HTMLElement).closest("a[href]");
+      if (!anchor) return;
+
+      const href = anchor.getAttribute("href");
+      if (!href) return;
+
+      // ── Skip non-internal links ──
+      if (
+        href.startsWith("http") ||
+        href.startsWith("#") ||
+        href.startsWith("mailto:") ||
+        href.startsWith("tel:")
+      )
+        return;
+      if (anchor.getAttribute("target") === "_blank") return;
+      if (href === pathname) return;
+      if (href.startsWith("/admin") || href.startsWith("/studio")) return;
+
+      // Skip if modifier keys (Cmd+click, Ctrl+click → new tab)
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+
+      // Skip exit animations when clicking from mobile menu overlay —
+      // instant navigation feels better after the menu close transition.
+      if (anchor.closest("#mobile-nav-menu")) return;
+
+      // Only trigger if there are animated elements to exit
+      if (!document.querySelector(ANIMATED_SELECTOR)) return;
+
+      // Intercept: prevent Next.js Link from navigating immediately
+      e.preventDefault();
+      triggerExit(href);
+    };
+
+    // Capture phase ensures we fire BEFORE Next.js Link's bubble handler.
+    // Next.js Link checks event.defaultPrevented and bails if true.
+    container.addEventListener("click", handleClick, true);
+    return () => container.removeEventListener("click", handleClick, true);
+  }, [pathname, triggerExit]);
+
+  return (
+    <PageExitContext.Provider value={{ isExiting }}>
+      <div ref={containerRef}>{children}</div>
+    </PageExitContext.Provider>
+  );
+}

package/lib/contexts/ThumbStatusContext.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * ThumbStatusContext — provides thumbnail availability data to builder components.
+ *
+ * Fetches the asset registry once and exposes a Map<path, boolean> lookup.
+ * Used by BlockLivePreview to show green/amber thumb badges on image blocks.
+ *
+ * Wrap around the builder canvas:
+ *   <ThumbStatusProvider>
+ *     <BuilderCanvas>...</BuilderCanvas>
+ *   </ThumbStatusProvider>
+ */
+
+import { createContext, useContext, useEffect, useState, useMemo, useCallback } from "react";
+import type { ReactNode } from "react";
+import { isRasterImage } from "../../lib/thumbnails/generate";
+
+interface ThumbStatusContextValue {
+  /** Returns true if asset has a thumbnail, false if not, undefined if unknown/not raster */
+  hasThumb: (assetPath: string) => boolean | undefined;
+  /** Refresh registry data (call after uploads) */
+  refresh: () => void;
+}
+
+const ThumbStatusContext = createContext<ThumbStatusContextValue>({
+  hasThumb: () => undefined,
+  refresh: () => {},
+});
+
+export function useThumbStatus() {
+  return useContext(ThumbStatusContext);
+}
+
+interface RegistryEntry {
+  path: string;
+  has_thumbnail?: boolean;
+  status?: string;
+}
+
+export function ThumbStatusProvider({ children }: { children: ReactNode }) {
+  const [thumbMap, setThumbMap] = useState<Map<string, boolean>>(new Map());
+
+  const fetchRegistry = useCallback(async () => {
+    try {
+      const res = await fetch("/api/admin/assets/registry");
+      if (!res.ok) return;
+      const data = await res.json();
+      const assets: RegistryEntry[] = data.registry?.assets || [];
+      const map = new Map<string, boolean>();
+      for (const a of assets) {
+        if (a.status === "missing") continue;
+        map.set(a.path, a.has_thumbnail === true);
+      }
+      setThumbMap(map);
+    } catch {
+      // Silent — badges simply won't show
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchRegistry();
+  }, [fetchRegistry]);
+
+  const hasThumb = useCallback(
+    (assetPath: string): boolean | undefined => {
+      if (!assetPath || !isRasterImage(assetPath)) return undefined;
+      return thumbMap.get(assetPath);
+    },
+    [thumbMap]
+  );
+
+  const value = useMemo(
+    () => ({ hasThumb, refresh: fetchRegistry }),
+    [hasThumb, fetchRegistry]
+  );
+
+  return (
+    <ThumbStatusContext.Provider value={value}>
+      {children}
+    </ThumbStatusContext.Provider>
+  );
+}

package/lib/csrf-client.ts

@@ -0,0 +1,34 @@
+/**
+ * Client-side CSRF helpers.
+ *
+ * Reads the `csrf_token` cookie (set by the server on login and refreshed
+ * by middleware) and returns headers suitable for fetch() calls.
+ */
+
+const CSRF_COOKIE_NAME = "csrf_token";
+const CSRF_HEADER_NAME = "x-csrf-token";
+
+/**
+ * Read the CSRF token from the browser cookie jar.
+ * Returns undefined if not found or running on the server.
+ */
+export function getCsrfToken(): string | undefined {
+  if (typeof window === "undefined") return undefined;
+  // Use regex to safely extract the value, avoiding split pitfalls
+  const match = window.document.cookie.match(
+    new RegExp(`(?:^|;\\s*)${CSRF_COOKIE_NAME}=([^;]*)`)
+  );
+  return match?.[1] || undefined;
+}
+
+/**
+ * Build a headers object with the CSRF token included.
+ * Merge this into your fetch() headers for mutation requests.
+ *
+ * @example
+ *   fetch(url, { method: "POST", headers: { ...csrfHeaders(), "Content-Type": "application/json" } })
+ */
+export function csrfHeaders(): Record<string, string> {
+  const token = getCsrfToken();
+  return token ? { [CSRF_HEADER_NAME]: token } : {};
+}

package/lib/csrf.ts

@@ -0,0 +1,68 @@
+/**
+ * CSRF protection using double-submit cookie pattern.
+ *
+ * How it works:
+ * 1. Server generates a random CSRF token and sets it as a cookie
+ * 2. Client reads the cookie and sends it as a header (X-CSRF-Token)
+ * 3. Server validates that the header matches the cookie
+ *
+ * Why this works: A cross-origin attacker can trigger the browser to send
+ * cookies, but cannot read them (SameSite + HttpOnly). Since the attacker
+ * can't read the cookie, they can't set the matching header.
+ *
+ * The CSRF cookie is NOT HttpOnly so the client can read and echo it.
+ * This is safe — the value is a random token with no sensitive info.
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+
+const CSRF_COOKIE_NAME = "csrf_token";
+const CSRF_HEADER_NAME = "x-csrf-token";
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Generate a new CSRF token.
+ */
+export function generateCsrfToken(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Set the CSRF token cookie on a response.
+ * Called when the admin logs in or when no CSRF cookie exists.
+ */
+export function setCsrfCookie(response: NextResponse, token: string): void {
+  response.cookies.set(CSRF_COOKIE_NAME, token, {
+    httpOnly: false, // Client must be able to read this
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "strict",
+    path: "/",
+    maxAge: 60 * 60 * 24, // 24 hours
+  });
+}
+
+/**
+ * Validate CSRF token on a mutation request.
+ * Compares the cookie value to the X-CSRF-Token header.
+ *
+ * Returns true if valid, false if CSRF check fails.
+ */
+export function validateCsrf(request: NextRequest): boolean {
+  const cookieToken = request.cookies.get(CSRF_COOKIE_NAME)?.value;
+  const headerToken = request.headers.get(CSRF_HEADER_NAME);
+
+  if (!cookieToken || !headerToken) return false;
+  if (!UUID_V4_REGEX.test(cookieToken)) return false; // Must be valid UUID v4
+
+  return cookieToken === headerToken;
+}
+
+/**
+ * Return a 403 response for CSRF validation failure.
+ */
+export function csrfErrorResponse(): NextResponse {
+  return NextResponse.json(
+    { error: "CSRF validation failed" },
+    { status: 403 }
+  );
+}

package/lib/format-utils.ts

@@ -0,0 +1,24 @@
+// ============================================
+// Shared Format Utilities
+// ============================================
+// Extracted from storage/page.tsx and assets/page.tsx (Session 131)
+
+/**
+ * Format a date string to locale string, or "Never" if absent.
+ */
+export function formatDate(date: string | undefined | null): string {
+  if (!date) return "Never";
+  return new Date(date).toLocaleString();
+}
+
+/**
+ * Format byte count to human-readable string (B, KB, MB, GB, TB).
+ * Uses logarithmic approach for precision at all magnitudes.
+ */
+export function formatBytes(bytes: number | undefined): string {
+  if (!bytes || bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const val = bytes / Math.pow(1024, i);
+  return `${val < 10 ? val.toFixed(2) : val < 100 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
+}