@windrun-huaiin/third-ui 14.0.1 → 14.0.2

package/dist/clerk/fingerprint/index.js

@@ -10,6 +10,9 @@ var fingerprintProvider = require('./fingerprint-provider.js');
 
 exports.FINGERPRINT_CONSTANTS = fingerprintShared.FINGERPRINT_CONSTANTS;
 exports.FINGERPRINT_COOKIE_NAME = fingerprintShared.FINGERPRINT_COOKIE_NAME;
+exports.FINGERPRINT_FIRST_TOUCH_COOKIE_NAME = fingerprintShared.FINGERPRINT_FIRST_TOUCH_COOKIE_NAME;
+exports.FINGERPRINT_FIRST_TOUCH_HEADER = fingerprintShared.FINGERPRINT_FIRST_TOUCH_HEADER;
+exports.FINGERPRINT_FIRST_TOUCH_STORAGE_KEY = fingerprintShared.FINGERPRINT_FIRST_TOUCH_STORAGE_KEY;
 exports.FINGERPRINT_HEADER_NAME = fingerprintShared.FINGERPRINT_HEADER_NAME;
 exports.FINGERPRINT_SOURCE_REFER = fingerprintShared.FINGERPRINT_SOURCE_REFER;
 exports.FINGERPRINT_STORAGE_KEY = fingerprintShared.FINGERPRINT_STORAGE_KEY;
@@ -19,6 +22,7 @@ exports.createFingerprintFetch = fingerprintClient.createFingerprintFetch;
 exports.createFingerprintHeaders = fingerprintClient.createFingerprintHeaders;
 exports.generateFingerprintId = fingerprintClient.generateFingerprintId;
 exports.getFingerprintId = fingerprintClient.getFingerprintId;
+exports.getOrCreateFirstTouchData = fingerprintClient.getOrCreateFirstTouchData;
 exports.getOrGenerateFingerprintId = fingerprintClient.getOrGenerateFingerprintId;
 exports.setFingerprintId = fingerprintClient.setFingerprintId;
 exports.useFingerprintHeaders = fingerprintClient.useFingerprintHeaders;

package/dist/clerk/fingerprint/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-export { FINGERPRINT_CONSTANTS, FINGERPRINT_COOKIE_NAME, FINGERPRINT_HEADER_NAME, FINGERPRINT_SOURCE_REFER, FINGERPRINT_STORAGE_KEY, isValidFingerprintId } from './fingerprint-shared.mjs';
-export { clearFingerprintId, createFingerprintFetch, createFingerprintHeaders, generateFingerprintId, getFingerprintId, getOrGenerateFingerprintId, setFingerprintId, useFingerprintHeaders } from './fingerprint-client.mjs';
+export { FINGERPRINT_CONSTANTS, FINGERPRINT_COOKIE_NAME, FINGERPRINT_FIRST_TOUCH_COOKIE_NAME, FINGERPRINT_FIRST_TOUCH_HEADER, FINGERPRINT_FIRST_TOUCH_STORAGE_KEY, FINGERPRINT_HEADER_NAME, FINGERPRINT_SOURCE_REFER, FINGERPRINT_STORAGE_KEY, isValidFingerprintId } from './fingerprint-shared.mjs';
+export { clearFingerprintId, createFingerprintFetch, createFingerprintHeaders, generateFingerprintId, getFingerprintId, getOrCreateFirstTouchData, getOrGenerateFingerprintId, setFingerprintId, useFingerprintHeaders } from './fingerprint-client.mjs';
 export { useFingerprint } from './use-fingerprint.mjs';
 export { FingerprintProvider, FingerprintStatus, useFingerprintContext, useFingerprintContextSafe, withFingerprint } from './fingerprint-provider.mjs';

package/dist/clerk/fingerprint/server.js

@@ -7,6 +7,9 @@ var fingerprintServer = require('./fingerprint-server.js');
 
 exports.FINGERPRINT_CONSTANTS = fingerprintShared.FINGERPRINT_CONSTANTS;
 exports.FINGERPRINT_COOKIE_NAME = fingerprintShared.FINGERPRINT_COOKIE_NAME;
+exports.FINGERPRINT_FIRST_TOUCH_COOKIE_NAME = fingerprintShared.FINGERPRINT_FIRST_TOUCH_COOKIE_NAME;
+exports.FINGERPRINT_FIRST_TOUCH_HEADER = fingerprintShared.FINGERPRINT_FIRST_TOUCH_HEADER;
+exports.FINGERPRINT_FIRST_TOUCH_STORAGE_KEY = fingerprintShared.FINGERPRINT_FIRST_TOUCH_STORAGE_KEY;
 exports.FINGERPRINT_HEADER_NAME = fingerprintShared.FINGERPRINT_HEADER_NAME;
 exports.FINGERPRINT_SOURCE_REFER = fingerprintShared.FINGERPRINT_SOURCE_REFER;
 exports.FINGERPRINT_STORAGE_KEY = fingerprintShared.FINGERPRINT_STORAGE_KEY;

package/dist/clerk/fingerprint/server.mjs

@@ -1,2 +1,2 @@
-export { FINGERPRINT_CONSTANTS, FINGERPRINT_COOKIE_NAME, FINGERPRINT_HEADER_NAME, FINGERPRINT_SOURCE_REFER, FINGERPRINT_STORAGE_KEY, isValidFingerprintId } from './fingerprint-shared.mjs';
+export { FINGERPRINT_CONSTANTS, FINGERPRINT_COOKIE_NAME, FINGERPRINT_FIRST_TOUCH_COOKIE_NAME, FINGERPRINT_FIRST_TOUCH_HEADER, FINGERPRINT_FIRST_TOUCH_STORAGE_KEY, FINGERPRINT_HEADER_NAME, FINGERPRINT_SOURCE_REFER, FINGERPRINT_STORAGE_KEY, isValidFingerprintId } from './fingerprint-shared.mjs';
 export { extractFingerprintFromNextRequest, extractFingerprintFromNextStores, extractFingerprintId, generateServerFingerprintId } from './fingerprint-server.mjs';

package/dist/clerk/fingerprint/use-fingerprint.js

@@ -37,6 +37,8 @@ function useFingerprint(config) {
      */
     const initializeFingerprintId = React.useCallback(() => tslib_es6.__awaiter(this, void 0, void 0, function* () {
         try {
+            // Capture first-touch as early as possible before any in-site navigation can overwrite context.
+            fingerprintClient.getOrCreateFirstTouchData();
             const currentFingerprintId = yield fingerprintClient.getOrGenerateFingerprintId();
             console.log('Initialized fingerprintId:', currentFingerprintId);
             setFingerprintIdState(currentFingerprintId);

package/dist/clerk/fingerprint/use-fingerprint.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { __awaiter } from '../../node_modules/.pnpm/@rollup_plugin-typescript@12.1.4_rollup@4.46.2_tslib@2.8.1_typescript@5.9.3/node_modules/tslib/tslib.es6.mjs';
 import { useState, useCallback, useEffect } from 'react';
-import { getOrGenerateFingerprintId, createFingerprintHeaders } from './fingerprint-client.mjs';
+import { getOrCreateFirstTouchData, getOrGenerateFingerprintId, createFingerprintHeaders } from './fingerprint-client.mjs';
 import { FINGERPRINT_SOURCE_REFER } from './fingerprint-shared.mjs';
 
 /**
@@ -35,6 +35,8 @@ function useFingerprint(config) {
      */
     const initializeFingerprintId = useCallback(() => __awaiter(this, void 0, void 0, function* () {
         try {
+            // Capture first-touch as early as possible before any in-site navigation can overwrite context.
+            getOrCreateFirstTouchData();
             const currentFingerprintId = yield getOrGenerateFingerprintId();
             console.log('Initialized fingerprintId:', currentFingerprintId);
             setFingerprintIdState(currentFingerprintId);

package/dist/main/delayed-img.d.ts

@@ -0,0 +1,7 @@
+import { type ImageProps } from "next/image";
+interface DelayedImgProps extends ImageProps {
+    wrapperClassName?: string;
+    placeholderClassName?: string;
+}
+export declare function DelayedImg({ alt, wrapperClassName, placeholderClassName, className, onLoad, ...imageProps }: DelayedImgProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/main/delayed-img.js

@@ -0,0 +1,39 @@
+"use client";
+'use strict';
+
+var tslib_es6 = require('../node_modules/.pnpm/@rollup_plugin-typescript@12.1.4_rollup@4.46.2_tslib@2.8.1_typescript@5.9.3/node_modules/tslib/tslib.es6.js');
+var jsxRuntime = require('react/jsx-runtime');
+var Image = require('next/image');
+var React = require('react');
+var lib = require('@windrun-huaiin/base-ui/lib');
+var utils = require('@windrun-huaiin/lib/utils');
+
+var _a, _b;
+const ENV_DELAY_ENABLED = process.env.NEXT_PUBLIC_DELAYED_IMG_ENABLED === "true" ||
+    process.env.NEXT_PUBLIC_DELAY_REVEAL_ENABLED === "true";
+const rawDelaySeconds = (_b = (_a = process.env.NEXT_PUBLIC_DELAYED_IMG_SECONDS) !== null && _a !== void 0 ? _a : process.env.NEXT_PUBLIC_DELAY_REVEAL_SECONDS) !== null && _b !== void 0 ? _b : "0";
+const parsedDelaySeconds = Number(rawDelaySeconds);
+const ENV_DELAY_MS = Number.isFinite(parsedDelaySeconds) && parsedDelaySeconds > 0
+    ? parsedDelaySeconds * 1000
+    : 0;
+function DelayedImg(_a) {
+    var { alt, wrapperClassName, placeholderClassName, className, onLoad } = _a, imageProps = tslib_es6.__rest(_a, ["alt", "wrapperClassName", "placeholderClassName", "className", "onLoad"]);
+    const shouldDelay = ENV_DELAY_ENABLED && ENV_DELAY_MS > 0;
+    const [isMounted, setIsMounted] = React.useState(!shouldDelay);
+    const [isLoaded, setIsLoaded] = React.useState(false);
+    React.useEffect(() => {
+        if (!shouldDelay || isMounted) {
+            return;
+        }
+        const timer = window.setTimeout(() => {
+            setIsMounted(true);
+        }, ENV_DELAY_MS);
+        return () => window.clearTimeout(timer);
+    }, [isMounted, shouldDelay]);
+    return (jsxRuntime.jsxs("div", { className: utils.cn("relative", wrapperClassName), children: [(!isMounted || !isLoaded) && (jsxRuntime.jsxs("div", { "aria-hidden": "true", className: utils.cn("absolute inset-0 rounded-[inherit] border animate-pulse shadow-sm bg-white/70 dark:bg-white/5", lib.themeBgColor, placeholderClassName), children: [jsxRuntime.jsx("div", { className: utils.cn("absolute inset-x-0 top-0 h-28 rounded-[inherit] bg-linear-to-b from-white/80 to-transparent dark:from-white/14 dark:to-transparent", lib.themeViaColor) }), jsxRuntime.jsx("div", { className: "absolute inset-0 rounded-[inherit] bg-white/20 dark:bg-white/0" })] })), isMounted && (jsxRuntime.jsx(Image, Object.assign({}, imageProps, { alt: alt, onLoad: (event) => {
+                    setIsLoaded(true);
+                    onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);
+                }, className: utils.cn("transition duration-300", isLoaded ? "opacity-100" : "opacity-0", className) })))] }));
+}
+
+exports.DelayedImg = DelayedImg;

package/dist/main/delayed-img.mjs

@@ -0,0 +1,37 @@
+"use client";
+import { __rest } from '../node_modules/.pnpm/@rollup_plugin-typescript@12.1.4_rollup@4.46.2_tslib@2.8.1_typescript@5.9.3/node_modules/tslib/tslib.es6.mjs';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import Image from 'next/image';
+import { useState, useEffect } from 'react';
+import { themeViaColor, themeBgColor } from '@windrun-huaiin/base-ui/lib';
+import { cn } from '@windrun-huaiin/lib/utils';
+
+var _a, _b;
+const ENV_DELAY_ENABLED = process.env.NEXT_PUBLIC_DELAYED_IMG_ENABLED === "true" ||
+    process.env.NEXT_PUBLIC_DELAY_REVEAL_ENABLED === "true";
+const rawDelaySeconds = (_b = (_a = process.env.NEXT_PUBLIC_DELAYED_IMG_SECONDS) !== null && _a !== void 0 ? _a : process.env.NEXT_PUBLIC_DELAY_REVEAL_SECONDS) !== null && _b !== void 0 ? _b : "0";
+const parsedDelaySeconds = Number(rawDelaySeconds);
+const ENV_DELAY_MS = Number.isFinite(parsedDelaySeconds) && parsedDelaySeconds > 0
+    ? parsedDelaySeconds * 1000
+    : 0;
+function DelayedImg(_a) {
+    var { alt, wrapperClassName, placeholderClassName, className, onLoad } = _a, imageProps = __rest(_a, ["alt", "wrapperClassName", "placeholderClassName", "className", "onLoad"]);
+    const shouldDelay = ENV_DELAY_ENABLED && ENV_DELAY_MS > 0;
+    const [isMounted, setIsMounted] = useState(!shouldDelay);
+    const [isLoaded, setIsLoaded] = useState(false);
+    useEffect(() => {
+        if (!shouldDelay || isMounted) {
+            return;
+        }
+        const timer = window.setTimeout(() => {
+            setIsMounted(true);
+        }, ENV_DELAY_MS);
+        return () => window.clearTimeout(timer);
+    }, [isMounted, shouldDelay]);
+    return (jsxs("div", { className: cn("relative", wrapperClassName), children: [(!isMounted || !isLoaded) && (jsxs("div", { "aria-hidden": "true", className: cn("absolute inset-0 rounded-[inherit] border animate-pulse shadow-sm bg-white/70 dark:bg-white/5", themeBgColor, placeholderClassName), children: [jsx("div", { className: cn("absolute inset-x-0 top-0 h-28 rounded-[inherit] bg-linear-to-b from-white/80 to-transparent dark:from-white/14 dark:to-transparent", themeViaColor) }), jsx("div", { className: "absolute inset-0 rounded-[inherit] bg-white/20 dark:bg-white/0" })] })), isMounted && (jsx(Image, Object.assign({}, imageProps, { alt: alt, onLoad: (event) => {
+                    setIsLoaded(true);
+                    onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);
+                }, className: cn("transition duration-300", isLoaded ? "opacity-100" : "opacity-0", className) })))] }));
+}
+
+export { DelayedImg };

package/dist/main/index.d.ts

@@ -8,6 +8,7 @@ export * from './rich-text-expert';
 export * from './faq-interactive';
 export * from './price-plan-interactive';
 export * from './gallery/gallery-interactive';
+export * from './delayed-img';
 export { MoneyPriceInteractive } from './money-price/money-price-interactive';
 export { MoneyPriceButton } from './money-price/money-price-button';
 export { CreditOverviewClient } from './credit/credit-overview-client';

package/dist/main/index.js

@@ -11,6 +11,7 @@ var richTextExpert = require('./rich-text-expert.js');
 var faqInteractive = require('./faq-interactive.js');
 var pricePlanInteractive = require('./price-plan-interactive.js');
 var galleryInteractive = require('./gallery/gallery-interactive.js');
+var delayedImg = require('./delayed-img.js');
 var moneyPriceInteractive = require('./money-price/money-price-interactive.js');
 var moneyPriceButton = require('./money-price/money-price-button.js');
 var creditOverviewClient = require('./credit/credit-overview-client.js');
@@ -29,6 +30,7 @@ exports.richText = richTextExpert.richText;
 exports.FAQInteractive = faqInteractive.FAQInteractive;
 exports.PricePlanInteractive = pricePlanInteractive.PricePlanInteractive;
 exports.GalleryInteractive = galleryInteractive.GalleryInteractive;
+exports.DelayedImg = delayedImg.DelayedImg;
 exports.MoneyPriceInteractive = moneyPriceInteractive.MoneyPriceInteractive;
 exports.MoneyPriceButton = moneyPriceButton.MoneyPriceButton;
 exports.CreditOverviewClient = creditOverviewClient.CreditOverviewClient;

package/dist/main/index.mjs

@@ -9,6 +9,7 @@ export { createRichTextRenderer, richText } from './rich-text-expert.mjs';
 export { FAQInteractive } from './faq-interactive.mjs';
 export { PricePlanInteractive } from './price-plan-interactive.mjs';
 export { GalleryInteractive } from './gallery/gallery-interactive.mjs';
+export { DelayedImg } from './delayed-img.mjs';
 export { MoneyPriceInteractive } from './money-price/money-price-interactive.mjs';
 export { MoneyPriceButton } from './money-price/money-price-button.mjs';
 export { CreditOverviewClient } from './credit/credit-overview-client.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/third-ui",
-  "version": "14.0.1",
+  "version": "14.0.2",
   "description": "Third-party integrated UI components for windrun-huaiin projects",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/clerk/fingerprint/fingerprint-client.ts

@@ -5,7 +5,40 @@
  */
 
 import FingerprintJS from '@fingerprintjs/fingerprintjs';
-import { FINGERPRINT_COOKIE_NAME, FINGERPRINT_HEADER_NAME, FINGERPRINT_SOURCE_REFER, FINGERPRINT_STORAGE_KEY, isValidFingerprintId } from './fingerprint-shared';
+import {
+  FINGERPRINT_COOKIE_NAME,
+  FINGERPRINT_FIRST_TOUCH_COOKIE_NAME,
+  FINGERPRINT_FIRST_TOUCH_HEADER,
+  FINGERPRINT_FIRST_TOUCH_STORAGE_KEY,
+  FINGERPRINT_HEADER_NAME,
+  FINGERPRINT_SOURCE_REFER,
+  FINGERPRINT_STORAGE_KEY,
+  isValidFingerprintId
+} from './fingerprint-shared';
+
+const FIRST_TOUCH_MAX_LENGTH = 2048;
+const FIRST_TOUCH_COOKIE_DAYS = 30;
+
+type FirstTouchData = {
+  landingUrl?: string;
+  landingPath?: string;
+  landingHost?: string;
+  externalReferrer?: string;
+  capturedAt?: string;
+  ref?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  utmId?: string;
+  gclid?: string;
+  fbclid?: string;
+  msclkid?: string;
+  ttclid?: string;
+  twclid?: string;
+  liFatId?: string;
+};
 
 /**
  * 检查浏览器存储（localStorage 和 cookie）中的指纹 ID
@@ -17,7 +50,7 @@ function checkStoredFingerprintId(): string | null {
   }
 
   // 优先检查 localStorage
-  const localStorageId = localStorage.getItem(FINGERPRINT_STORAGE_KEY);
+  const localStorageId = getLocalStorageValue(FINGERPRINT_STORAGE_KEY);
   if (localStorageId && isValidFingerprintId(localStorageId)) {
     return localStorageId;
   }
@@ -26,13 +59,149 @@ function checkStoredFingerprintId(): string | null {
   const cookieId = getCookieValue(FINGERPRINT_COOKIE_NAME);
   if (cookieId && isValidFingerprintId(cookieId)) {
     // 同步到 localStorage
-    localStorage.setItem(FINGERPRINT_STORAGE_KEY, cookieId);
+    setLocalStorageValue(FINGERPRINT_STORAGE_KEY, cookieId);
     return cookieId;
   }
 
   return null;
 }
 
+function normalizeString(value: string | null | undefined, maxLength = FIRST_TOUCH_MAX_LENGTH): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return trimmed.length > maxLength ? trimmed.slice(0, maxLength) : trimmed;
+}
+
+function readFirstTouchFromStorage(): FirstTouchData | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  const localStorageValue = getLocalStorageValue(FINGERPRINT_FIRST_TOUCH_STORAGE_KEY);
+  if (localStorageValue) {
+    const parsed = parseFirstTouchValue(localStorageValue);
+    if (parsed) {
+      syncFirstTouchStorage(parsed);
+      return parsed;
+    }
+  }
+
+  const cookieValue = getCookieValue(FINGERPRINT_FIRST_TOUCH_COOKIE_NAME);
+  if (cookieValue) {
+    const parsed = parseFirstTouchValue(cookieValue);
+    if (parsed) {
+      syncFirstTouchStorage(parsed);
+      return parsed;
+    }
+  }
+
+  return null;
+}
+
+function parseFirstTouchValue(value: string): FirstTouchData | null {
+  try {
+    const decoded = decodeURIComponent(value);
+    const parsed = JSON.parse(decoded) as FirstTouchData;
+    return sanitizeFirstTouchData(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function sanitizeFirstTouchData(data: FirstTouchData | null | undefined): FirstTouchData | null {
+  if (!data) {
+    return null;
+  }
+
+  const sanitized: FirstTouchData = {
+    landingUrl: normalizeString(data.landingUrl),
+    landingPath: normalizeString(data.landingPath, 512),
+    landingHost: normalizeString(data.landingHost, 255),
+    externalReferrer: normalizeString(data.externalReferrer),
+    capturedAt: normalizeString(data.capturedAt, 64),
+    ref: normalizeString(data.ref, 512),
+    utmSource: normalizeString(data.utmSource, 512),
+    utmMedium: normalizeString(data.utmMedium, 512),
+    utmCampaign: normalizeString(data.utmCampaign, 512),
+    utmTerm: normalizeString(data.utmTerm, 512),
+    utmContent: normalizeString(data.utmContent, 512),
+    utmId: normalizeString(data.utmId, 512),
+    gclid: normalizeString(data.gclid, 512),
+    fbclid: normalizeString(data.fbclid, 512),
+    msclkid: normalizeString(data.msclkid, 512),
+    ttclid: normalizeString(data.ttclid, 512),
+    twclid: normalizeString(data.twclid, 512),
+    liFatId: normalizeString(data.liFatId, 512),
+  };
+
+  return Object.values(sanitized).some(Boolean) ? sanitized : null;
+}
+
+function serializeFirstTouchData(data: FirstTouchData): string {
+  return encodeURIComponent(JSON.stringify(data));
+}
+
+function syncFirstTouchStorage(data: FirstTouchData): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const serialized = serializeFirstTouchData(data);
+  setLocalStorageValue(FINGERPRINT_FIRST_TOUCH_STORAGE_KEY, serialized);
+  setCookie(FINGERPRINT_FIRST_TOUCH_COOKIE_NAME, serialized, FIRST_TOUCH_COOKIE_DAYS);
+}
+
+function buildFirstTouchData(): FirstTouchData | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  const url = new URL(window.location.href);
+  const data = sanitizeFirstTouchData({
+    landingUrl: url.toString(),
+    landingPath: url.pathname,
+    landingHost: url.host,
+    externalReferrer: document.referrer || undefined,
+    capturedAt: new Date().toISOString(),
+    ref: url.searchParams.get('ref') ?? undefined,
+    utmSource: url.searchParams.get('utm_source') ?? undefined,
+    utmMedium: url.searchParams.get('utm_medium') ?? undefined,
+    utmCampaign: url.searchParams.get('utm_campaign') ?? undefined,
+    utmTerm: url.searchParams.get('utm_term') ?? undefined,
+    utmContent: url.searchParams.get('utm_content') ?? undefined,
+    utmId: url.searchParams.get('utm_id') ?? undefined,
+    gclid: url.searchParams.get('gclid') ?? undefined,
+    fbclid: url.searchParams.get('fbclid') ?? undefined,
+    msclkid: url.searchParams.get('msclkid') ?? undefined,
+    ttclid: url.searchParams.get('ttclid') ?? undefined,
+    twclid: url.searchParams.get('twclid') ?? undefined,
+    liFatId: url.searchParams.get('li_fat_id') ?? undefined,
+  });
+
+  return data;
+}
+
+export function getOrCreateFirstTouchData(): FirstTouchData | null {
+  const existing = readFirstTouchFromStorage();
+  if (existing) {
+    return existing;
+  }
+
+  const created = buildFirstTouchData();
+  if (created) {
+    syncFirstTouchStorage(created);
+  }
+
+  return created;
+}
+
 /**
  * 生成基于真实浏览器特征的fingerprint ID
  * 使用 FingerprintJS 收集浏览器特征并生成唯一标识
@@ -56,7 +225,7 @@ export async function generateFingerprintId(): Promise<string> {
     const fingerprintId = `fp_${result.visitorId}`;
 
     // 存储到 localStorage 和 cookie
-    localStorage.setItem(FINGERPRINT_STORAGE_KEY, fingerprintId);
+    setLocalStorageValue(FINGERPRINT_STORAGE_KEY, fingerprintId);
     setCookie(FINGERPRINT_COOKIE_NAME, fingerprintId, 365);
 
     console.log('Generated new fingerprint ID:', fingerprintId);
@@ -65,7 +234,7 @@ export async function generateFingerprintId(): Promise<string> {
     console.warn('Failed to generate fingerprint with FingerprintJS:', error);
     // 降级方案：生成基于时间戳和随机数的 ID
     const fallbackId = `fp_fallback_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
-    localStorage.setItem(FINGERPRINT_STORAGE_KEY, fallbackId);
+    setLocalStorageValue(FINGERPRINT_STORAGE_KEY, fallbackId);
     setCookie(FINGERPRINT_COOKIE_NAME, fallbackId, 365);
 
     console.log('Generated fallback fingerprint ID:', fallbackId);
@@ -92,7 +261,7 @@ export function setFingerprintId(fingerprintId: string): void {
     throw new Error('Invalid fingerprint ID');
   }
 
-  localStorage.setItem(FINGERPRINT_STORAGE_KEY, fingerprintId);
+  setLocalStorageValue(FINGERPRINT_STORAGE_KEY, fingerprintId);
   setCookie(FINGERPRINT_COOKIE_NAME, fingerprintId, 365);
 }
 
@@ -104,7 +273,7 @@ export function clearFingerprintId(): void {
     throw new Error('clearFingerprintId can only be used in browser environment');
   }
 
-  localStorage.removeItem(FINGERPRINT_STORAGE_KEY);
+  removeLocalStorageValue(FINGERPRINT_STORAGE_KEY);
   deleteCookie(FINGERPRINT_COOKIE_NAME);
 }
 
@@ -127,9 +296,16 @@ export async function getOrGenerateFingerprintId(): Promise<string> {
  */
 export async function createFingerprintHeaders(): Promise<Record<string, string>> {
   const fingerprintId = await getOrGenerateFingerprintId();
-  return {
+  const headers: Record<string, string> = {
     [FINGERPRINT_HEADER_NAME]: fingerprintId,
   };
+
+  const firstTouch = getOrCreateFirstTouchData();
+  if (firstTouch) {
+    headers[FINGERPRINT_FIRST_TOUCH_HEADER] = serializeFirstTouchData(firstTouch);
+  }
+
+  return headers;
 }
 
 /**
@@ -164,12 +340,16 @@ function getCookieValue(name: string): string | null {
     return null;
   }
 
-  const value = `; ${document.cookie}`;
-  const parts = value.split(`; ${name}=`);
-  if (parts.length === 2) {
-    return parts.pop()?.split(';').shift() || null;
+  try {
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) {
+      return parts.pop()?.split(';').shift() || null;
+    }
+    return null;
+  } catch {
+    return null;
   }
-  return null;
 }
 
 function setCookie(name: string, value: string, days: number): void {
@@ -177,9 +357,13 @@ function setCookie(name: string, value: string, days: number): void {
     return;
   }
 
-  const expires = new Date();
-  expires.setTime(expires.getTime() + days * 24 * 60 * 60 * 1000);
-  document.cookie = `${name}=${value};expires=${expires.toUTCString()};path=/;SameSite=Lax`;
+  try {
+    const expires = new Date();
+    expires.setTime(expires.getTime() + days * 24 * 60 * 60 * 1000);
+    document.cookie = `${name}=${value};expires=${expires.toUTCString()};path=/;SameSite=Lax`;
+  } catch {
+    // Ignore storage failures so attribution never blocks page flow.
+  }
 }
 
 function deleteCookie(name: string): void {
@@ -187,5 +371,45 @@ function deleteCookie(name: string): void {
     return;
   }
 
-  document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`;
-}
+  try {
+    document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`;
+  } catch {
+    // Ignore storage failures so attribution never blocks page flow.
+  }
+}
+
+function getLocalStorageValue(key: string): string | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function setLocalStorageValue(key: string, value: string): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // Ignore storage failures so attribution never blocks page flow.
+  }
+}
+
+function removeLocalStorageValue(key: string): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+    // Ignore storage failures so attribution never blocks page flow.
+  }
+}

package/src/clerk/fingerprint/fingerprint-shared.ts

@@ -8,6 +8,9 @@ export const FINGERPRINT_STORAGE_KEY = '__x_fingerprint_id';
 export const FINGERPRINT_HEADER_NAME = 'x-fingerprint-id-v8';
 export const FINGERPRINT_COOKIE_NAME = '__x_fingerprint_id';
 export const FINGERPRINT_SOURCE_REFER = 'x-source-ref';
+export const FINGERPRINT_FIRST_TOUCH_STORAGE_KEY = '__x_first_touch';
+export const FINGERPRINT_FIRST_TOUCH_COOKIE_NAME = '__x_first_touch';
+export const FINGERPRINT_FIRST_TOUCH_HEADER = 'x-first-touch';
 
 /**
  * 验证fingerprint ID格式
@@ -27,4 +30,7 @@ export const FINGERPRINT_CONSTANTS = {
   STORAGE_KEY: FINGERPRINT_STORAGE_KEY,
   HEADER_NAME: FINGERPRINT_HEADER_NAME,
   COOKIE_NAME: FINGERPRINT_COOKIE_NAME,
-} as const;
+  FIRST_TOUCH_STORAGE_KEY: FINGERPRINT_FIRST_TOUCH_STORAGE_KEY,
+  FIRST_TOUCH_COOKIE_NAME: FINGERPRINT_FIRST_TOUCH_COOKIE_NAME,
+  FIRST_TOUCH_HEADER: FINGERPRINT_FIRST_TOUCH_HEADER,
+} as const;

package/src/clerk/fingerprint/use-fingerprint.ts

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useState } from 'react';
 import {
   createFingerprintHeaders,
+  getOrCreateFirstTouchData,
   getOrGenerateFingerprintId
 } from './fingerprint-client';
 import type {
@@ -47,6 +48,8 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
    */
   const initializeFingerprintId = useCallback(async () => {
     try {
+      // Capture first-touch as early as possible before any in-site navigation can overwrite context.
+      getOrCreateFirstTouchData();
       const currentFingerprintId = await getOrGenerateFingerprintId();
       console.log('Initialized fingerprintId:', currentFingerprintId);
       setFingerprintIdState(currentFingerprintId);
@@ -185,4 +188,4 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
     initializeAnonymousUser,
     refreshUserData,
   };
-}
+}