@morphika/webframe 0.1.0

package/components/blocks/CustomSectionInstanceRenderer.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * CustomSectionInstanceRenderer — Renders a custom section instance on the public site.
+ *
+ * Fetches the section data from the cached public API endpoint and renders it
+ * using SectionV2Renderer. The API response is CDN-cached for 1 hour.
+ *
+ * Session 108: Created as part of Custom Sections Phase 2.
+ * Session 110: M2 fix — loading skeleton to prevent CLS.
+ */
+
+import { useEffect, useState } from "react";
+import type { CustomSectionInstance, PageSectionV2 } from "../../lib/sanity/types";
+import SectionV2Renderer from "./SectionV2Renderer";
+
+interface CustomSectionInstanceRendererProps {
+  instance: CustomSectionInstance;
+}
+
+export default function CustomSectionInstanceRenderer({
+  instance,
+}: CustomSectionInstanceRendererProps) {
+  const [section, setSection] = useState<PageSectionV2 | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    fetch(`/api/custom-sections/${instance.custom_section_id}`)
+      .then((res) => {
+        if (!res.ok) throw new Error("Not found");
+        return res.json();
+      })
+      .then((data) => {
+        if (!cancelled && data.section) {
+          setSection(data.section);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setError(true);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [instance.custom_section_id]);
+
+  // Error — render nothing (silent fail, no layout shift)
+  if (error) return null;
+
+  // Loading — minimal skeleton preserving vertical space
+  if (loading || !section) {
+    return (
+      <div
+        className="w-full animate-pulse"
+        style={{ minHeight: 120, background: "transparent" }}
+        aria-hidden="true"
+      />
+    );
+  }
+
+  // Merge per-instance settings overrides on top of the section's base settings
+  let mergedSection: PageSectionV2 = instance.settings_overrides
+    ? { ...section, settings: { ...section.settings, ...instance.settings_overrides } }
+    : section;
+
+  // Merge per-instance responsive overrides (viewport-specific spacing/border/etc.)
+  if (instance.responsive_overrides) {
+    mergedSection = {
+      ...mergedSection,
+      responsive: {
+        ...mergedSection.responsive,
+        ...instance.responsive_overrides,
+      },
+    };
+  }
+
+  return <SectionV2Renderer section={mergedSection} />;
+}

package/components/blocks/EnterAnimationWrapper.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+/**
+ * EnterAnimationWrapper — applies enter (reveal) animations on the public site.
+ *
+ * Replaces ScrollAnimationWrapper (Session 120).
+ *
+ * Single trigger mode: IntersectionObserver (15% threshold).
+ *   - Above-the-fold: if already intersecting on mount, plays immediately.
+ *   - Below-the-fold: waits for scroll to reveal, then plays once.
+ *
+ * Applies inline @keyframes from getEnterKeyframes() — no CSS animation-timeline,
+ * no scroll-linked animation, no Firefox fallback.
+ *
+ * Respects prefers-reduced-motion: skips animation, shows element immediately.
+ * Sets data-entered when complete (for PageExitContext exit animations).
+ */
+
+import { useRef, useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import type { ResolvedEnterAnimationConfig, EnterPreset } from "../../lib/animation/enter-types";
+import { getEnterKeyframes } from "../../lib/animation/enter-presets";
+
+interface EnterAnimationWrapperProps {
+  config: ResolvedEnterAnimationConfig;
+  children: ReactNode;
+  /** HTML tag for the wrapper element */
+  as?: "div" | "section";
+  className?: string;
+  style?: CSSProperties;
+  /** Stagger index within parent — offsets animation delay for sequential reveals */
+  staggerIndex?: number;
+  /** Stagger delay in ms (multiplied by staggerIndex) */
+  staggerDelay?: number;
+}
+
+/**
+ * Map enter preset names to @keyframes names in globals.css.
+ */
+const PRESET_KEYFRAME_MAP: Record<string, string> = {
+  fade:       "enter-fade",
+  "slide-up": "enter-slide-up",
+  "slide-down": "enter-slide-down",
+  scale:      "enter-scale",
+  blur:       "enter-blur",
+  "blur-in":  "enter-blur-in",
+  reveal:     "enter-reveal",
+};
+
+export default function EnterAnimationWrapper({
+  config,
+  children,
+  as: Tag = "div",
+  className,
+  style,
+  staggerIndex,
+  staggerDelay,
+}: EnterAnimationWrapperProps) {
+  const { preset, duration, delay, easing } = config;
+
+  const ref = useRef<HTMLElement>(null);
+  const [hasEntered, setHasEntered] = useState(false);
+
+  // Compute total delay including stagger
+  const totalDelay = delay + (staggerIndex !== undefined && staggerDelay ? staggerIndex * staggerDelay : 0);
+
+  // Get keyframe data for initial hidden state
+  const keyframes = getEnterKeyframes(preset);
+
+  // ── IntersectionObserver: above-the-fold detection + scroll reveal ──
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || hasEntered) return;
+
+    // Respect prefers-reduced-motion
+    if (typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      setHasEntered(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          // Whether above-the-fold (already visible on mount) or below-the-fold
+          // (scrolled into view), behavior is the same: play animation once.
+          setHasEntered(true);
+          observer.disconnect();
+        }
+      },
+      { threshold: 0.15 },
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [hasEntered]);
+
+  // If preset is "none" or has no keyframes (typewriter), just render children
+  if (preset === "none" || !keyframes) {
+    return (
+      <Tag className={className} style={style}>
+        {children}
+      </Tag>
+    );
+  }
+
+  const animName = PRESET_KEYFRAME_MAP[preset];
+
+  // Build styles based on state
+  let animStyle: CSSProperties;
+
+  if (hasEntered) {
+    // Play the animation
+    animStyle = {
+      animationName: animName,
+      animationDuration: `${duration}ms`,
+      animationDelay: `${totalDelay}ms`,
+      animationTimingFunction: easing,
+      animationFillMode: "both",
+    };
+  } else {
+    // Initial hidden state from keyframe "from" values
+    animStyle = keyframes.from as unknown as CSSProperties;
+  }
+
+  const mergedStyle: CSSProperties = {
+    ...style,
+    ...animStyle,
+  };
+
+  return (
+    <Tag
+      ref={ref as React.Ref<HTMLDivElement> & React.Ref<HTMLElement>}
+      data-enter-animation={preset}
+      data-entered={hasEntered ? "" : undefined}
+      className={className}
+      style={mergedStyle}
+    >
+      {children}
+    </Tag>
+  );
+}

package/components/blocks/HoverAnimationWrapper.tsx

@@ -0,0 +1,308 @@
+"use client";
+
+/**
+ * HoverAnimationWrapper — applies hover effects to blocks on the public site.
+ *
+ * Handles both CSS-based hovers (scale-up, lift, tilt-3d, etc.) and
+ * shader-based hovers (ripple, rgb-shift, pixelate) via ShaderCanvas.
+ *
+ * Block-level only — no cascade. Config comes directly from block.hover_effect.
+ *
+ * Respects:
+ * - prefers-reduced-motion: disables all hover effects (returns children unwrapped)
+ * - Touch devices: hover effects are naturally absent on touch
+ *
+ * Session 60, updated Session 64 (throttled tilt-3d, reduced-motion).
+ * Session 120: Updated to accept HoverEffectConfig, merged ShaderEffectWrapper.
+ * Session 128: Fixed hooks ordering — all hooks must be called before any
+ *   conditional return to comply with React's Rules of Hooks. The shader path
+ *   early return was skipping useCallback/useEffect, causing React error #300
+ *   ("Rendered fewer hooks than expected").
+ */
+
+import { useRef, useCallback, useEffect, useState, lazy, Suspense, type CSSProperties, type ReactNode, Component, type ErrorInfo } from "react";
+import type { HoverEffectConfig } from "../../lib/animation/hover-effect-types";
+import { getHoverEffectStyles, isShaderPreset, SMOOTHNESS_VALUES } from "../../lib/animation/hover-effect-presets";
+import type { ResolvedShaderEffectConfig } from "../../lib/animation/hover-effect-types";
+import { getSiteConfig } from "../../lib/config";
+
+// Lazy import — zero bundle impact when shaders aren't used.
+// Uses React.lazy + Suspense instead of next/dynamic to avoid potential
+// SSR hydration issues with { ssr: false } in Next.js App Router.
+const ShaderCanvas = lazy(() => import("./ShaderCanvas"));
+
+// ── Error boundary for shader rendering ──
+// Catches WebGL / shader errors and falls back to a plain image.
+interface ShaderErrorBoundaryProps {
+  fallbackSrc: string;
+  fallbackAlt: string;
+  children: ReactNode;
+}
+interface ShaderErrorBoundaryState { hasError: boolean }
+
+class ShaderErrorBoundary extends Component<ShaderErrorBoundaryProps, ShaderErrorBoundaryState> {
+  state: ShaderErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): ShaderErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    // eslint-disable-next-line no-console
+    console.warn("[ShaderErrorBoundary] Caught error, falling back to plain image:", error, info.componentStack);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+          src={this.props.fallbackSrc}
+          alt={this.props.fallbackAlt}
+          style={{ display: "block", width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+interface HoverAnimationWrapperProps {
+  config: HoverEffectConfig;
+  children: ReactNode;
+  as?: "div" | "section";
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Required for shader presets — the image src to apply the shader to.
+   * If not provided and a shader preset is selected, falls back to CSS-only.
+   */
+  shaderSrc?: string;
+  shaderAlt?: string;
+  /** Style for the shader container */
+  shaderContainerStyle?: CSSProperties;
+  shaderContainerClassName?: string;
+  shaderImgProps?: React.ImgHTMLAttributes<HTMLImageElement>;
+}
+
+// ── Capability checks (memoized) ──
+
+let _webglSupported: boolean | null = null;
+function isWebGLSupported(): boolean {
+  if (_webglSupported !== null) return _webglSupported;
+  try {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
+    _webglSupported = !!ctx;
+  } catch {
+    _webglSupported = false;
+  }
+  return _webglSupported;
+}
+
+function isTouchOnlyDevice(): boolean {
+  const hasFinePointer = window.matchMedia("(pointer: fine)").matches;
+  if (hasFinePointer) return false;
+  const hasCoarsePointer = window.matchMedia("(pointer: coarse)").matches;
+  return hasCoarsePointer || "ontouchstart" in window || navigator.maxTouchPoints > 0;
+}
+
+export default function HoverAnimationWrapper({
+  config,
+  children,
+  as: Tag = "div",
+  className,
+  style,
+  shaderSrc,
+  shaderAlt,
+  shaderContainerStyle,
+  shaderContainerClassName,
+  shaderImgProps,
+}: HoverAnimationWrapperProps) {
+  const {
+    preset = "none",
+    duration = 300,
+    easing = "ease-out",
+    shader_speed = 1.0,
+    shader_smoothness = "normal",
+  } = config;
+
+  const isShader = isShaderPreset(preset);
+
+  // ── ALL hooks must be called unconditionally (Rules of Hooks) ──
+  // These hooks are used by the CSS hover path, but must be called even
+  // on the shader path to maintain consistent hook ordering across renders.
+
+  const ref = useRef<HTMLDivElement>(null);
+  const rafId = useRef<number>(0);
+  const leaveTimerId = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Respect prefers-reduced-motion
+  const [reducedMotion, setReducedMotion] = useState(false);
+  const [canRenderShader, setCanRenderShader] = useState(false);
+
+  useEffect(() => {
+    const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setReducedMotion(mql.matches);
+    const handler = (e: MediaQueryListEvent) => setReducedMotion(e.matches);
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }, []);
+
+  // Check shader capability once
+  useEffect(() => {
+    if (!isShaderPreset(preset)) return;
+    const siteConfig = getSiteConfig();
+    if (!(siteConfig.features as Record<string, boolean>).shaderEffects) {
+      setCanRenderShader(false);
+      return;
+    }
+    const webgl = isWebGLSupported();
+    const touchOnly = isTouchOnlyDevice();
+    const rm = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    setCanRenderShader(webgl && !touchOnly && !rm);
+  }, [preset]);
+
+  // Throttled mouse move handler for tilt-3d preset (rAF-based)
+  // Called unconditionally to maintain hook ordering.
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      if (preset !== "tilt-3d") return;
+      const el = ref.current;
+      if (!el) return;
+
+      if (rafId.current) cancelAnimationFrame(rafId.current);
+
+      const clientX = e.clientX;
+      const clientY = e.clientY;
+
+      rafId.current = requestAnimationFrame(() => {
+        const rect = el.getBoundingClientRect();
+        const x = (clientX - rect.left) / rect.width;
+        const y = (clientY - rect.top) / rect.height;
+
+        const maxTilt = 8;
+        const rotateY = (x - 0.5) * 2 * maxTilt;
+        const rotateX = (0.5 - y) * 2 * maxTilt;
+
+        el.style.transform = `perspective(800px) rotateX(${rotateX.toFixed(1)}deg) rotateY(${rotateY.toFixed(1)}deg)`;
+      });
+    },
+    [preset]
+  );
+
+  const handleMouseLeave = useCallback(() => {
+    if (preset !== "tilt-3d") return;
+    if (rafId.current) {
+      cancelAnimationFrame(rafId.current);
+      rafId.current = 0;
+    }
+    if (leaveTimerId.current) clearTimeout(leaveTimerId.current);
+    leaveTimerId.current = setTimeout(() => {
+      const el = ref.current;
+      if (!el) return;
+      el.style.transform = "perspective(800px) rotateX(0deg) rotateY(0deg)";
+    }, 50);
+  }, [preset]);
+
+  // Cleanup rAF and debounce timer on unmount
+  useEffect(() => {
+    return () => {
+      if (rafId.current) cancelAnimationFrame(rafId.current);
+      if (leaveTimerId.current) clearTimeout(leaveTimerId.current);
+    };
+  }, []);
+
+  // ── All hooks called. Conditional returns are now safe. ──
+
+  // Shader preset without shaderSrc: passthrough (no wrapper div, no CSS hover)
+  if (isShader && !shaderSrc) {
+    return <>{children}</>;
+  }
+
+  // ── Shader preset rendering ──
+  // Renders children normally (for layout/dimensions) and overlays ShaderCanvas on top.
+  // Children provide the natural size; the shader canvas fills the container absolutely.
+  if (isShader && shaderSrc && canRenderShader) {
+    const shaderConfig: ResolvedShaderEffectConfig = {
+      preset: preset,
+      trigger: "hover",
+      intensity: 1.0,
+      speed: shader_speed,
+      smoothing: SMOOTHNESS_VALUES[shader_smoothness] ?? 0.05,
+    };
+
+    // Fallback image shown while ShaderCanvas loads or if it fails
+    const fallbackImg = (
+      // eslint-disable-next-line @next/next/no-img-element
+      <img
+        src={shaderSrc}
+        alt={shaderAlt ?? ""}
+        style={{
+          display: "block",
+          width: "100%",
+          height: "100%",
+          objectFit: "cover",
+        }}
+      />
+    );
+
+    return (
+      <div
+        style={{ position: "relative", overflow: "hidden", ...shaderContainerStyle }}
+        className={shaderContainerClassName || className}
+      >
+        {/* Children provide layout dimensions (padding, border-radius, natural image size) */}
+        <div aria-hidden="true" style={{ visibility: "hidden" }}>
+          {children}
+        </div>
+        {/* Shader canvas fills the container on top of the hidden children */}
+        <ShaderErrorBoundary fallbackSrc={shaderSrc} fallbackAlt={shaderAlt ?? ""}>
+          <Suspense fallback={fallbackImg}>
+            <ShaderCanvas
+              src={shaderSrc}
+              config={shaderConfig}
+              style={{ position: "absolute", inset: 0 }}
+            />
+          </Suspense>
+        </ShaderErrorBoundary>
+      </div>
+    );
+  }
+
+  // ── CSS hover preset rendering ──
+
+  const hoverStyles = getHoverEffectStyles(preset, duration, easing);
+
+  // When reduced motion is preferred or shader preset falls through (canRenderShader=false),
+  // render children without any animation wrapper
+  if (reducedMotion || !hoverStyles) {
+    return (
+      <Tag className={className} style={style}>
+        {children}
+      </Tag>
+    );
+  }
+
+  // Merge base styles with user styles
+  const mergedStyle: CSSProperties = {
+    ...style,
+    ...(hoverStyles.base as unknown as CSSProperties),
+    transition: `all ${duration}ms ${easing}`,
+  } as CSSProperties;
+
+  const isTilt = preset === "tilt-3d";
+
+  return (
+    <Tag
+      ref={ref as React.Ref<HTMLDivElement>}
+      data-hover-effect={preset}
+      className={className}
+      style={mergedStyle}
+      onMouseMove={isTilt ? handleMouseMove : undefined}
+      onMouseLeave={isTilt ? handleMouseLeave : undefined}
+    >
+      {children}
+    </Tag>
+  );
+}

package/components/blocks/ImageBlockRenderer.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import type { ImageBlock } from "../../lib/sanity/types";
+import { useAssetUrl } from "../../lib/contexts/AssetContext";
+import { handleImageRetry } from "../../lib/asset-retry";
+
+/**
+ * Width handling — must match builder LiveImage in BlockLivePreview.tsx.
+ * Builder uses: full=100%, contained=75%, small=50% with margin auto.
+ */
+const widthStyleMap: Record<string, { width: string; margin?: string }> = {
+  full: { width: "100%" },
+  contained: { width: "75%", margin: "0 auto" },
+  small: { width: "50%", margin: "0 auto" },
+};
+
+const aspectMap: Record<string, string | undefined> = {
+  auto: undefined,
+  "16:9": "16/9",
+  "4:3": "4/3",
+  "1:1": "1/1",
+  "21:9": "21/9",
+};
+
+export default function ImageBlockRenderer({ block }: { block: ImageBlock }) {
+  const resolveAsset = useAssetUrl();
+  const src = resolveAsset(block.asset_path);
+  const widthStyle = widthStyleMap[block.width ?? "full"] || widthStyleMap.full;
+  const aspect = aspectMap[block.aspect_ratio ?? "auto"];
+
+  const borderRadius = block.border_radius ? `${String(block.border_radius).replace(/px$/i, "")}px` : undefined;
+
+  const imgStyle: React.CSSProperties = {
+    width: "100%",
+    display: "block",
+    objectFit: aspect ? "cover" : undefined,
+    aspectRatio: aspect,
+  };
+
+  const imgClassName = block.shadow ? "shadow-lg" : "";
+
+  return (
+    <figure style={{ ...widthStyle, borderRadius, overflow: "hidden" }}>
+      {/* eslint-disable-next-line @next/next/no-img-element */}
+      <img
+        src={src}
+        alt={block.alt ?? ""}
+        loading={block.lazy !== false ? "lazy" : "eager"}
+        decoding="async"
+        onError={handleImageRetry}
+        style={imgStyle}
+        className={imgClassName}
+      />
+      {block.caption && (
+        <figcaption className="mt-2 font-mono text-xs uppercase tracking-wider text-brand-muted">
+          {block.caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}