@morphika/webframe 0.1.0

package/components/ui/Navbar.tsx

@@ -0,0 +1,582 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { usePathname } from "next/navigation";
+import Link from "next/link";
+import type { NavItem, NavDesign, NavEntrancePreset } from "../../lib/sanity/types";
+import { useNavColor } from "../../lib/contexts/NavColorContext";
+import { useNavAnimation } from "../../lib/contexts/NavAnimationContext";
+import { usePageExit } from "../../lib/contexts/PageExitContext";
+import { getSiteConfig } from "../../lib/config";
+import NavContentLightbox from "./NavContentLightbox";
+
+// ============================================
+// Color variant mapping
+// ============================================
+
+const colorMap: Record<string, string> = {
+  "yellow-lime": "text-brand-accent",
+  yellow: "text-brand-accent-alt",
+  "red-coral": "text-brand-secondary",
+  blue: "text-brand-primary",
+  green: "text-brand-accent-2",
+  white: "text-brand-text",
+};
+
+// ============================================
+// NavLink — shared link component (eliminates duplication)
+// ============================================
+
+interface NavLinkProps {
+  item: NavItem;
+  className: string;
+  style?: React.CSSProperties;
+  onClick?: () => void;
+  currentPath: string;
+  activeClassName?: string;
+  /** Called when a content link is clicked — opens lightbox */
+  onContentClick?: (item: NavItem) => void;
+}
+
+function NavLink({
+  item,
+  className,
+  style,
+  onClick,
+  currentPath,
+  activeClassName = "opacity-60",
+  onContentClick,
+}: NavLinkProps) {
+  // Content links render as buttons that open a lightbox
+  if (item.link_type === "content") {
+    const hasContent = item.content_asset || item.content_url;
+    return (
+      <button
+        className={className}
+        style={{ ...style, cursor: hasContent ? "pointer" : "default", opacity: hasContent ? 1 : 0.4, background: "none", border: "none", padding: 0 }}
+        onClick={() => {
+          if (hasContent && onContentClick) onContentClick(item);
+          if (onClick) onClick();
+        }}
+      >
+        {item.label}
+      </button>
+    );
+  }
+
+  const isExternal = item.link_type === "external";
+  const href = isExternal
+    ? item.external_url || undefined
+    : item.internal_page?.slug?.current
+      ? `/${item.internal_page.slug.current}`
+      : undefined;
+
+  // Check if this link is the active page
+  const isActive =
+    !isExternal && href && (currentPath === href || currentPath.startsWith(`${href}/`));
+
+  const resolvedClassName = `${className}${isActive ? ` ${activeClassName}` : ""}`;
+
+  // No valid href — render as inert text
+  if (!href) {
+    return (
+      <span className={className} style={{ ...style, cursor: "default", opacity: 0.4 }}>
+        {item.label}
+      </span>
+    );
+  }
+
+  if (isExternal) {
+    return (
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        className={resolvedClassName}
+        style={style}
+        onClick={onClick}
+      >
+        {item.label}
+      </a>
+    );
+  }
+
+  return (
+    <Link href={href} className={resolvedClassName} style={style} onClick={onClick} aria-current={isActive ? "page" : undefined}>
+      {item.label}
+    </Link>
+  );
+}
+
+// ============================================
+// Props
+// ============================================
+
+interface NavbarProps {
+  navItems?: NavItem[];
+  design?: NavDesign;
+  /** @deprecated Use design.color instead */
+  colorVariant?: string;
+}
+
+// ============================================
+// Component
+// ============================================
+
+export default function Navbar({
+  navItems = [],
+  design,
+  colorVariant = "yellow-lime",
+}: NavbarProps) {
+  // Resolve color: context > design > prop
+  const { navColor: contextColor } = useNavColor();
+  const activeColor = contextColor || design?.color || colorVariant;
+  const pathname = usePathname();
+  const { isExiting } = usePageExit();
+  const { override: navAnimOverride } = useNavAnimation();
+
+  // ── Entrance animation resolution (page override > global) ──
+  const entranceDisabled = navAnimOverride.disabled === true;
+  const entrancePreset: NavEntrancePreset | "" = entranceDisabled
+    ? ""
+    : (navAnimOverride.preset || design?.entrance_animation || "");
+  const entranceDuration = navAnimOverride.duration || design?.entrance_duration || 600;
+  const entranceDelay = navAnimOverride.delay ?? design?.entrance_delay ?? 0;
+  const entranceStagger = !entranceDisabled && (design?.entrance_stagger ?? false);
+  const entranceStaggerDelay = design?.entrance_stagger_delay ?? 80;
+
+  // Trigger entrance animation shortly after mount
+  const [navEntered, setNavEntered] = useState(!entrancePreset);
+  useEffect(() => {
+    if (!entrancePreset) {
+      setNavEntered(true);
+      return;
+    }
+    // Small delay to ensure the CSS initial hidden state paints first
+    const timer = requestAnimationFrame(() => setNavEntered(true));
+    return () => cancelAnimationFrame(timer);
+  }, [entrancePreset]);
+
+  // Resolve design values with defaults
+  const position = design?.position || "fixed";
+  const hideOnScroll = design?.hide_on_scroll !== false;
+  const fontSize = design?.font_size ?? 14;
+  const fontWeight = design?.font_weight || "400";
+  const fontFamily = design?.font_family || undefined;
+  const textTransformVal = design?.text_transform || "uppercase";
+  const textAlignVal = design?.text_align || "left";
+  const itemsJustify = textAlignVal === "center" ? "center" : textAlignVal === "right" ? "flex-end" : "flex-start";
+  const paddingH = design?.padding_h ?? 24;
+  const paddingV = design?.padding_v ?? 27;
+  const marginH = design?.margin_h ?? 0;
+  const marginV = design?.margin_v ?? 0;
+  const itemsGap = design?.items_gap ?? 32;
+  const bgColor = design?.background_color || "";
+  const bgOpacity = design?.background_opacity ?? 0;
+  const backdropBlur = !!design?.backdrop_blur;
+  const verticalAlign = design?.vertical_align || "top";
+  // Map vertical_align to CSS align-items value for the grid container
+  const gridAlignItems = verticalAlign === "bottom" ? "end" : verticalAlign === "middle" ? "center" : "start";
+
+  const [isVisible, setIsVisible] = useState(true);
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const [lightboxItem, setLightboxItem] = useState<NavItem | null>(null);
+  const lastScrollY = useRef(0);
+  const ticking = useRef(false);
+  const hamburgerButtonRef = useRef<HTMLButtonElement>(null);
+  const mobileMenuRef = useRef<HTMLDivElement>(null);
+
+  // Close mobile menu on route change (back/forward navigation)
+  useEffect(() => {
+    setIsMenuOpen(false);
+  }, [pathname]);
+
+  // Close mobile menu immediately when page exit animations start
+  useEffect(() => {
+    if (isExiting) setIsMenuOpen(false);
+  }, [isExiting]);
+
+  // Focus management: return focus to hamburger when menu closes
+  const prevMenuOpen = useRef(false);
+  useEffect(() => {
+    if (!isMenuOpen && prevMenuOpen.current) {
+      hamburgerButtonRef.current?.focus();
+    }
+    prevMenuOpen.current = isMenuOpen;
+  }, [isMenuOpen]);
+
+  // Focus trap: handle Tab/Shift+Tab/Escape within mobile menu
+  useEffect(() => {
+    if (!isMenuOpen || !mobileMenuRef.current) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        setIsMenuOpen(false);
+        return;
+      }
+
+      if (e.key !== "Tab") return;
+
+      const focusable = mobileMenuRef.current?.querySelectorAll<HTMLElement>(
+        'a, button, [tabindex]:not([tabindex="-1"])'
+      );
+      if (!focusable || focusable.length === 0) return;
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [isMenuOpen]);
+
+  // Hide on scroll down, show on scroll up
+  const handleScroll = useCallback(() => {
+    if (!hideOnScroll) return;
+    if (ticking.current) return;
+
+    ticking.current = true;
+    requestAnimationFrame(() => {
+      const currentScrollY = window.scrollY;
+
+      if (currentScrollY < 10) {
+        setIsVisible(true);
+      } else if (currentScrollY > lastScrollY.current && currentScrollY > 80) {
+        setIsVisible(false);
+      } else if (currentScrollY < lastScrollY.current) {
+        setIsVisible(true);
+      }
+
+      lastScrollY.current = currentScrollY;
+      ticking.current = false;
+    });
+  }, [hideOnScroll]);
+
+  useEffect(() => {
+    if (position === "static") return;
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    return () => window.removeEventListener("scroll", handleScroll);
+  }, [handleScroll, position]);
+
+  // Lock body scroll when mobile menu is open
+  useEffect(() => {
+    if (isMenuOpen) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "";
+    }
+    return () => {
+      document.body.style.overflow = "";
+    };
+  }, [isMenuOpen]);
+
+  // If activeColor is a hex string, use inline style; otherwise use Tailwind class
+  const isHexColor = activeColor.startsWith("#");
+  const textColorClass = isHexColor ? "" : (colorMap[activeColor] || colorMap["yellow-lime"]);
+  const textColorStyle: React.CSSProperties | undefined = isHexColor ? { color: activeColor } : undefined;
+
+  // Build background style
+  const navBgStyle: React.CSSProperties = {};
+  if (bgColor && bgOpacity > 0) {
+    const hex = bgColor.replace("#", "");
+    if (hex.length >= 6) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      navBgStyle.backgroundColor = `rgba(${r}, ${g}, ${b}, ${bgOpacity / 100})`;
+    }
+  }
+  if (backdropBlur) {
+    navBgStyle.backdropFilter = "blur(12px)";
+    navBgStyle.WebkitBackdropFilter = "blur(12px)";
+  }
+
+  // Position class
+  const positionClass =
+    position === "fixed"
+      ? "fixed"
+      : position === "sticky"
+        ? "sticky"
+        : "relative";
+
+  // Visibility: only applies to fixed/sticky when hideOnScroll
+  const shouldHide = position !== "static" && hideOnScroll && !isVisible;
+
+  // Grid layout: detect new format (items with type field) vs legacy (logo in design)
+  const visibleItems = navItems.filter((item) => item.visible !== false);
+  const hasNewFormat = visibleItems.some((i) => i.type === "logo" || i.type === "menu-item");
+
+  // New format: logo is a nav item; legacy: logo from design
+  const logoItem = hasNewFormat ? visibleItems.find((i) => i.type === "logo") : null;
+  // Filter out ALL logo-type items from menu items (prevents duplicate rendering)
+  const menuItems = hasNewFormat
+    ? visibleItems.filter((i) => i.type !== "logo")
+    : visibleItems;
+  const logoCols = logoItem ? logoItem.column_span : (design?.logo_columns ?? 3);
+  const logoLabel = logoItem?.label || design?.logo_text || getSiteConfig().defaults.logoText;
+
+  const placedItems = menuItems.filter((i) => typeof i.grid_column === "number" && i.grid_column > 0);
+  const unplacedItems = menuItems.filter((i) => typeof i.grid_column !== "number" || i.grid_column <= 0);
+
+  // Shared link styling (textTransform + fontFamily applied via inline style)
+  // When using hex color, we must set `color: inherit` on links because browser
+  // user-agent stylesheet sets `a { color: ... }` which overrides CSS inheritance.
+  const linkClassName = `tracking-normal ${textColorClass} transition-colors duration-200 hover:opacity-80 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current`;
+  const linkStyle: React.CSSProperties = {
+    fontSize: `${fontSize}px`,
+    fontWeight: fontWeight as React.CSSProperties["fontWeight"],
+    textTransform: textTransformVal as React.CSSProperties["textTransform"],
+    fontFamily: fontFamily || "var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace)",
+    ...(isHexColor ? { color: "inherit" } : {}),
+  };
+
+  return (
+    <>
+      {/* Navbar */}
+      <nav
+        role="navigation"
+        aria-label="Main navigation"
+        className={`${positionClass} top-0 left-0 right-0 z-50 transition-transform duration-300 ease-in-out ${
+          shouldHide ? "-translate-y-full" : "translate-y-0"
+        }`}
+        // Nav entrance animation (whole nav when no stagger)
+        {...(entrancePreset && !entranceStagger ? { "data-nav-entrance": entrancePreset } : {})}
+        {...(navEntered && entrancePreset && !entranceStagger ? { "data-nav-entered": "" } : {})}
+        style={{
+          ...navBgStyle,
+          ...textColorStyle,
+          ...(marginH > 0 || marginV > 0
+            ? {
+                left: `${marginH}px`,
+                right: `${marginH}px`,
+                top: `${marginV}px`,
+                borderRadius: "8px",
+              }
+            : {}),
+          // CSS custom properties for animation duration
+          ...(entrancePreset && !entranceStagger ? {
+            "--nav-entrance-duration": `${entranceDuration}ms`,
+            "--nav-entrance-delay": `${entranceDelay}ms`,
+          } as React.CSSProperties : {}),
+        }}
+      >
+        {/* Desktop: 12-column grid constrained to --grid-width */}
+        <div
+          className="hidden lg:grid"
+          style={{
+            gridTemplateColumns: "repeat(12, 1fr)",
+            maxWidth: "var(--grid-width, 1445px)",
+            marginLeft: "auto",
+            marginRight: "auto",
+            paddingLeft: `${paddingH}px`,
+            paddingRight: `${paddingH}px`,
+            paddingTop: `${paddingV}px`,
+            paddingBottom: `${paddingV}px`,
+            alignItems: gridAlignItems,
+            columnGap: `${itemsGap}px`,
+          }}
+        >
+          {/* Logo */}
+          <div
+            {...(entrancePreset && entranceStagger ? { "data-nav-item-entrance": entrancePreset } : {})}
+            {...(navEntered && entrancePreset && entranceStagger ? { "data-nav-entered": "" } : {})}
+            style={{
+              gridColumn: logoItem ? `${logoItem.grid_column} / span ${logoItem.column_span}` : `1 / span ${logoCols}`,
+              gridRow: 1,
+              display: "flex",
+              justifyContent: "flex-start",
+              alignItems: "center",
+              minWidth: 0,
+              overflow: "hidden",
+              whiteSpace: "nowrap",
+              ...(logoItem?.style_overrides?.vertical_align ? {
+                alignSelf: logoItem.style_overrides.vertical_align === "bottom" ? "end" : logoItem.style_overrides.vertical_align === "middle" ? "center" : "start",
+              } : {}),
+              ...(entrancePreset && entranceStagger ? {
+                "--nav-item-duration": `${Math.round(entranceDuration * 0.7)}ms`,
+                "--nav-item-delay": `${entranceDelay}ms`,
+              } as React.CSSProperties : {}),
+            }}
+          >
+            <Link
+              href="/"
+              className={linkClassName}
+              style={{
+                ...linkStyle,
+                ...(logoItem?.style_overrides?.font_size ? { fontSize: `${logoItem.style_overrides.font_size}px` } : {}),
+                ...(logoItem?.style_overrides?.font_weight ? { fontWeight: logoItem.style_overrides.font_weight } : {}),
+                ...(logoItem?.style_overrides?.font_family ? { fontFamily: logoItem.style_overrides.font_family } : {}),
+                ...(logoItem?.style_overrides?.color ? { color: logoItem.style_overrides.color } : {}),
+                ...(logoItem?.style_overrides?.text_transform ? { textTransform: logoItem.style_overrides.text_transform as React.CSSProperties["textTransform"] } : {}),
+              }}
+            >
+              {logoLabel}
+            </Link>
+          </div>
+
+          {/* Items with grid_column — each in its own column(s) */}
+          {placedItems.map((item, idx) => {
+            const itemVAlign = item.style_overrides?.vertical_align;
+            // Stagger: logo is index 0, first menu item is index 1, etc.
+            const staggerIdx = idx + 1;
+            return (
+            <div
+              key={item._key}
+              {...(entrancePreset && entranceStagger ? { "data-nav-item-entrance": entrancePreset } : {})}
+              {...(navEntered && entrancePreset && entranceStagger ? { "data-nav-entered": "" } : {})}
+              style={{
+                gridColumn: `${item.grid_column} / span ${item.column_span || 1}`,
+                gridRow: 1,
+                display: "flex",
+                justifyContent: itemsJustify,
+                alignItems: "center",
+                minWidth: 0,
+                overflow: "hidden",
+                whiteSpace: "nowrap",
+                ...(itemVAlign ? {
+                  alignSelf: itemVAlign === "bottom" ? "end" : itemVAlign === "middle" ? "center" : "start",
+                } : {}),
+                ...(entrancePreset && entranceStagger ? {
+                  "--nav-item-duration": `${Math.round(entranceDuration * 0.7)}ms`,
+                  "--nav-item-delay": `${entranceDelay + staggerIdx * entranceStaggerDelay}ms`,
+                } as React.CSSProperties : {}),
+              }}
+            >
+              <NavLink
+                item={item}
+                className={linkClassName}
+                style={{
+                  ...linkStyle,
+                  ...(item.style_overrides?.font_size ? { fontSize: `${item.style_overrides.font_size}px` } : {}),
+                  ...(item.style_overrides?.font_weight ? { fontWeight: item.style_overrides.font_weight } : {}),
+                  ...(item.style_overrides?.font_family ? { fontFamily: item.style_overrides.font_family } : {}),
+                  ...(item.style_overrides?.color ? { color: item.style_overrides.color } : {}),
+                  ...(item.style_overrides?.text_transform ? { textTransform: item.style_overrides.text_transform as React.CSSProperties["textTransform"] } : {}),
+                }}
+                currentPath={pathname}
+                onContentClick={setLightboxItem}
+              />
+            </div>
+          );
+          })}
+
+          {/* Fallback: unplaced items in remaining columns */}
+          {unplacedItems.length > 0 && (
+            <div
+              style={{
+                gridColumn: `${logoCols + 1} / -1`,
+                display: "flex",
+                justifyContent: itemsJustify,
+                alignItems: "center",
+                gap: `${design?.items_gap ?? 32}px`,
+              }}
+            >
+              {unplacedItems.map((item) => (
+                <NavLink
+                  key={item._key}
+                  item={item}
+                  className={linkClassName}
+                  style={linkStyle}
+                  currentPath={pathname}
+                />
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Mobile: simple flex layout with hamburger */}
+        <div
+          className="flex lg:hidden items-center justify-between"
+          style={{
+            maxWidth: "var(--grid-width, 1445px)",
+            marginLeft: "auto",
+            marginRight: "auto",
+            paddingLeft: `${paddingH}px`,
+            paddingRight: `${paddingH}px`,
+            paddingTop: `${paddingV}px`,
+            paddingBottom: `${paddingV}px`,
+          }}
+        >
+          <Link
+            href="/"
+            className={linkClassName}
+            style={linkStyle}
+          >
+            {logoLabel}
+          </Link>
+
+          <button
+            ref={hamburgerButtonRef}
+            onClick={() => setIsMenuOpen(!isMenuOpen)}
+            className={`flex flex-col justify-center items-center gap-[5px] w-8 h-8 ${textColorClass} focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current`}
+            aria-label={isMenuOpen ? "Close menu" : "Open menu"}
+            aria-expanded={isMenuOpen}
+            aria-controls="mobile-nav-menu"
+          >
+            <span
+              className={`block w-5 h-[1.5px] bg-current transition-all duration-300 ${
+                isMenuOpen ? "rotate-45 translate-y-[6.5px]" : ""
+              }`}
+            />
+            <span
+              className={`block w-5 h-[1.5px] bg-current transition-all duration-300 ${
+                isMenuOpen ? "opacity-0" : ""
+              }`}
+            />
+            <span
+              className={`block w-5 h-[1.5px] bg-current transition-all duration-300 ${
+                isMenuOpen ? "-rotate-45 -translate-y-[6.5px]" : ""
+              }`}
+            />
+          </button>
+        </div>
+      </nav>
+
+      {/* Mobile overlay menu */}
+      <div
+        ref={mobileMenuRef}
+        id="mobile-nav-menu"
+        role="dialog"
+        aria-modal={isMenuOpen}
+        aria-label="Mobile navigation menu"
+        className={`fixed inset-0 z-40 bg-brand-dark transition-opacity duration-300 lg:hidden ${
+          isMenuOpen
+            ? "opacity-100 pointer-events-auto"
+            : "opacity-0 pointer-events-none"
+        }`}
+      >
+        <div className="flex flex-col items-center justify-center h-full gap-8">
+          {[...menuItems].sort((a, b) => (a.grid_column || 0) - (b.grid_column || 0)).map((item) => (
+            <NavLink
+              key={item._key}
+              item={item}
+              className={`font-mono text-2xl tracking-wide ${textColorClass} transition-colors duration-200 hover:opacity-80 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current`}
+              style={{ textTransform: textTransformVal as React.CSSProperties["textTransform"], ...(fontFamily ? { fontFamily } : {}), ...(isHexColor ? { color: "inherit" } : {}) }}
+              currentPath={pathname}
+              onContentClick={(clickedItem) => { setLightboxItem(clickedItem); setIsMenuOpen(false); }}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Content lightbox */}
+      {lightboxItem && lightboxItem.link_type === "content" && (
+        <NavContentLightbox
+          contentType={lightboxItem.content_type || "image"}
+          contentAsset={lightboxItem.content_asset}
+          contentUrl={lightboxItem.content_url}
+          onClose={() => setLightboxItem(null)}
+        />
+      )}
+    </>
+  );
+}

package/components/ui/PortfolioTracker.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * PortfolioTracker — Outreach & campaign visit tracking.
+ *
+ * Tracks two types of visits:
+ * 1. Lead referrals:  example.com/portfolio?r=AM92
+ * 2. Custom channels: example.com/portfolio?c=discord
+ *
+ * Sends a POST to the Knock API on first load and on SPA route changes.
+ * Uses sessionStorage to persist ref/channel across internal navigation.
+ *
+ * Configured via site.config.ts: tracking.knockApiUrl + tracking.sessionPrefix.
+ * If knockApiUrl is empty, the component renders nothing.
+ */
+
+import { useEffect, useRef } from "react";
+import { usePathname } from "next/navigation";
+import { getSiteConfig } from "../../lib/config";
+
+const cfg = getSiteConfig();
+const KNOCK_API_URL = cfg.tracking.knockApiUrl;
+const REF_KEY = `${cfg.tracking.sessionPrefix}_ref`;
+const CHANNEL_KEY = `${cfg.tracking.sessionPrefix}_channel`;
+
+function sendVisit(
+  page: string,
+  ref: string | null,
+  channel: string | null,
+): void {
+  if (!ref && !channel) return;
+
+  const body: Record<string, string> = {
+    page,
+    timestamp: new Date().toISOString(),
+  };
+  if (ref) body.ref = ref;
+  if (channel) body.channel = channel;
+
+  fetch(KNOCK_API_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).catch(() => {
+    /* silent — tracking should never break the site */
+  });
+}
+
+export default function PortfolioTracker() {
+  const pathname = usePathname();
+  const prevPathRef = useRef<string | null>(null);
+  const enabled = !!KNOCK_API_URL;
+
+  // Initial visit + capture URL params into sessionStorage
+  useEffect(() => {
+    if (!enabled) return;
+
+    const params = new URLSearchParams(window.location.search);
+    const ref = params.get("r") || params.get("ref");
+    const channel = params.get("c");
+
+    if (ref) sessionStorage.setItem(REF_KEY, ref);
+    if (channel) sessionStorage.setItem(CHANNEL_KEY, channel);
+
+    const storedRef = ref || sessionStorage.getItem(REF_KEY);
+    const storedChannel = channel || sessionStorage.getItem(CHANNEL_KEY);
+
+    if (storedRef || storedChannel) {
+      sendVisit(window.location.pathname, storedRef, storedChannel);
+    }
+
+    prevPathRef.current = window.location.pathname;
+  }, [enabled]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // SPA route change tracking (Next.js App Router)
+  useEffect(() => {
+    if (!enabled) return;
+    if (prevPathRef.current === null || pathname === prevPathRef.current) return;
+    prevPathRef.current = pathname;
+
+    const ref = sessionStorage.getItem(REF_KEY);
+    const channel = sessionStorage.getItem(CHANNEL_KEY);
+    sendVisit(pathname, ref, channel);
+  }, [pathname, enabled]);
+
+  return null;
+}