@windrun-huaiin/third-ui 30.1.0 → 31.0.0

package/dist/main/pill-select/x-pill-select.mjs

@@ -24,7 +24,7 @@ function XPillSelect(props) {
     const isAllSelected = props.mode === 'multiple' &&
         allOptionValues.length > 0 &&
         allOptionValues.every((value) => selectedValues.includes(value));
-    const aggregatedSelectedLabel = isAllSelected ? (allSelectedLabel === null || allSelectedLabel === void 0 ? void 0 : allSelectedLabel.trim()) || '全部' : null;
+    const aggregatedSelectedLabel = isAllSelected ? (allSelectedLabel === null || allSelectedLabel === void 0 ? void 0 : allSelectedLabel.trim()) || 'All' : null;
     const hasVisiblePillLimit = props.mode === 'multiple' && typeof maxVisiblePills === 'number' && maxVisiblePills >= 0;
     const visibleSelectedValues = aggregatedSelectedLabel || !hasVisiblePillLimit
         ? selectedValues
@@ -124,7 +124,7 @@ function XPillSelect(props) {
                                             event.stopPropagation();
                                             removeValue(selectedValue);
                                         }, disabled: disabled, className: cn('inline-flex max-w-full items-center rounded-full font-semibold transition', compact ? 'gap-1 px-2.5 py-0.5 text-[11px]' : 'gap-1.5 px-3 py-1 text-xs', themeBgColor, themeIconColor, 'hover:brightness-95 dark:hover:brightness-110', disabled && 'cursor-not-allowed opacity-60'), title: optionLabel, children: jsx("span", { className: cn('truncate', maxPillWidthClassName), children: optionLabel }) }, selectedValue));
-                                }), hiddenSelectedCount > 0 ? (jsxs("span", { className: cn('inline-flex max-w-full items-center rounded-full font-semibold transition', compact ? 'px-2.5 py-0.5 text-[11px]' : 'px-3 py-1 text-xs', 'bg-neutral-200 text-neutral-700 dark:bg-neutral-800 dark:text-white'), title: `还有 ${hiddenSelectedCount} 项未展开`, children: ["+", hiddenSelectedCount] })) : null] }))) : (jsx("span", { className: cn(compact ? 'text-xs' : 'text-sm', 'text-slate-500 dark:text-slate-400'), children: emptyLabel })) }), jsx(ChevronDownIcon, { className: cn(compact ? 'h-3.5 w-3.5' : 'h-4 w-4', 'shrink-0 text-slate-500 transition-transform dark:text-slate-400', open && 'rotate-180') })] }), open ? (jsxs("div", { role: "listbox", "aria-multiselectable": props.mode === 'multiple' ? true : undefined, className: cn('absolute left-0 right-0 top-[calc(100%+0.375rem)] z-50 rounded-3xl border border-black/10 bg-neutral-100 shadow-xl dark:border-white/10 dark:bg-neutral-900', compact ? 'space-y-2.5 p-3' : 'space-y-3 p-4', open && themeBorderColor), children: [inputEnabled ? (jsx("input", { value: draftValue, onChange: (event) => setDraftValue(event.target.value.replaceAll(',', '')), onKeyDown: (event) => {
+                                }), hiddenSelectedCount > 0 ? (jsxs("span", { className: cn('inline-flex max-w-full items-center rounded-full font-semibold transition', compact ? 'px-2.5 py-0.5 text-[11px]' : 'px-3 py-1 text-xs', 'bg-neutral-200 text-neutral-700 dark:bg-neutral-800 dark:text-white'), title: `${hiddenSelectedCount} items remain unexpanded`, children: ["+", hiddenSelectedCount] })) : null] }))) : (jsx("span", { className: cn(compact ? 'text-xs' : 'text-sm', 'text-slate-500 dark:text-slate-400'), children: emptyLabel })) }), jsx(ChevronDownIcon, { className: cn(compact ? 'h-3.5 w-3.5' : 'h-4 w-4', 'shrink-0 text-slate-500 transition-transform dark:text-slate-400', open && 'rotate-180') })] }), open ? (jsxs("div", { role: "listbox", "aria-multiselectable": props.mode === 'multiple' ? true : undefined, className: cn('absolute left-0 right-0 top-[calc(100%+0.375rem)] z-50 rounded-3xl border border-black/10 bg-neutral-100 shadow-xl dark:border-white/10 dark:bg-neutral-900', compact ? 'space-y-2.5 p-3' : 'space-y-3 p-4', open && themeBorderColor), children: [inputEnabled ? (jsx("input", { value: draftValue, onChange: (event) => setDraftValue(event.target.value.replaceAll(',', '')), onKeyDown: (event) => {
                             if (event.key !== 'Enter') {
                                 return;
                             }

package/dist/main/server.d.ts

@@ -12,5 +12,5 @@ export type { CreditOverviewData, CreditBucket, CreditBucketStatus, Subscription
 export { MoneyPrice } from './money-price/money-price';
 export { getActiveProviderConfigUtil, getCreditsFromPriceIdUtil, getPriceConfigUtil } from './money-price/money-price-config-util';
 export { buildMoneyPriceData } from './money-price/money-price-data';
-export type { MoneyPriceConfig, MoneyPriceProps, MoneyPriceInteractiveProps, MoneyPriceButtonProps, MoneyPriceData, InitUserContext, PaymentProvider, PaymentProviderConfig, EnhancePricePlan, SubscriptionProductConfig, CreditPackProductConfig, UserContext } from './money-price/money-price-types';
+export type { MoneyPriceConfig, MoneyPriceProps, MoneyPriceInteractiveProps, MoneyPriceButtonProps, MoneyPriceData, MoneyPriceAnimeTone, MoneyPriceStrictDiffAnime, InitUserContext, PaymentProvider, PaymentProviderConfig, EnhancePricePlan, SubscriptionProductConfig, CreditPackProductConfig, UserContext } from './money-price/money-price-types';
 export { UserState } from './money-price/money-price-types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windrun-huaiin/third-ui",
-  "version": "30.1.0",
+  "version": "31.0.0",
   "description": "Third-party integrated UI components for windrun-huaiin projects",
   "exports": {
     "./clerk": {
@@ -221,9 +221,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@clerk/localizations": "^4.2.2",
-    "@clerk/nextjs": "^7.0.5",
-    "@clerk/shared": "^4.3.1",
+    "@clerk/localizations": "^4.6.2",
+    "@clerk/nextjs": "^7.3.3",
+    "@clerk/shared": "^4.10.2",
     "@fingerprintjs/fingerprintjs": "^5.1.0",
     "animejs": "^4.4.1",
     "class-variance-authority": "^0.7.1",
@@ -243,9 +243,9 @@
     "tslib": "^2.8.1",
     "unified": "^11.0.5",
     "zod": "^4.3.6",
-    "@windrun-huaiin/base-ui": "^30.1.0",
-    "@windrun-huaiin/lib": "^30.0.0",
-    "@windrun-huaiin/contracts": "^30.0.0"
+    "@windrun-huaiin/base-ui": "^31.0.0",
+    "@windrun-huaiin/lib": "^31.0.0",
+    "@windrun-huaiin/contracts": "^31.0.0"
   },
   "peerDependencies": {
     "clsx": "^2.1.1",
@@ -281,6 +281,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://d8ger.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caofanCPU/next-ai-build.git",
+    "directory": "packages/third-ui"
+  },
   "scripts": {
     "build": "rollup -c rollup.config.mjs",
     "build:prod": "rollup -c rollup.config.mjs",

package/src/ai/ai-prompt-textarea.tsx

@@ -188,7 +188,7 @@ export function AIPromptTextarea({
     }
   }
 
-  // 渲染标题组件
+  // Render the title component.
   const renderTitle = () => {
     if (!title?.trim()) return null
     
@@ -200,7 +200,7 @@ export function AIPromptTextarea({
     )
   }
 
-  // 渲染textarea组件
+  // Render the textarea component.
   const renderTextarea = (isEmbedded = false) => (
     <textarea
       ref={textareaRef}
@@ -220,7 +220,7 @@ export function AIPromptTextarea({
     />
   )
 
-  // 渲染单词计数
+  // Render the word count.
   const renderWordCount = () => {
     if (!showWordCount) return null
     
@@ -238,7 +238,7 @@ export function AIPromptTextarea({
     )
   }
 
-  // 如果有标题且需要嵌入，则渲染内部标题布局
+  // Render the embedded title layout when a title is present and embedded mode is enabled.
   if (embed && (title)) {
     return (
       <div className="space-y-2">
@@ -256,7 +256,7 @@ export function AIPromptTextarea({
     )
   }
 
-  // 默认布局：外部标题或无标题
+  // Default layout: external title or no title.
   return (
     <div className="space-y-2">
       {renderTitle()}
@@ -264,4 +264,4 @@ export function AIPromptTextarea({
       {renderWordCount()}
     </div>
   )
-} 
+} 

package/src/clerk/clerk-auth-appearance.ts

@@ -0,0 +1,16 @@
+export const clerkAuthModalAppearance = {
+  elements: {
+    modalContent: '!items-start !pt-16 sm:!pt-24',
+    cardBox: '!mt-0',
+  },
+};
+
+export const clerkAuthPageAppearance = {
+  elements: {
+    rootBox: 'w-full',
+    cardBox: 'mx-auto',
+  },
+};
+
+export const clerkAuthPageContainerClassName =
+  'flex min-h-[calc(100dvh-var(--fd-banner-height,0px)-var(--fd-header-height,3.5rem))] w-full items-start justify-center px-6 pt-[calc(var(--fd-header-height,3.5rem)+2rem)] pb-6 md:px-8 md:pt-[calc(var(--fd-header-height,3.5rem)+4.5rem)] md:pb-8';

package/src/clerk/clerk-page-context-generator.tsx

@@ -7,9 +7,7 @@
 
 import { SignUpWithFingerprint } from './signup-with-fingerprint-client';
 import { SignInWithFingerprint } from './signin-with-fingerprint-client';
-
-const clerkPageContainerClassName =
-  'flex min-h-dvh w-full items-start justify-center px-6 pt-[calc(var(--fd-banner-height,0px)+var(--fd-header-height,3.5rem)+1rem)] pb-6 md:px-8 md:pt-[calc(var(--fd-banner-height,0px)+var(--fd-header-height,3.5rem)+1.5rem)] md:pb-8';
+import { clerkAuthPageContainerClassName } from './clerk-auth-appearance';
 
 /**
  * Create a SignUp page with fingerprint support
@@ -18,7 +16,7 @@ const clerkPageContainerClassName =
 export function createSignUpPageWithFingerprint() {
   return function SignUpPage() {
     return (
-      <div className={clerkPageContainerClassName}>
+      <div className={clerkAuthPageContainerClassName}>
         <SignUpWithFingerprint />
       </div>
     );
@@ -32,7 +30,7 @@ export function createSignUpPageWithFingerprint() {
 export function createSignInPageWithFingerprint() {
   return function SignInPage() {
     return (
-      <div className={clerkPageContainerClassName}>
+      <div className={clerkAuthPageContainerClassName}>
         <SignInWithFingerprint />
       </div>
     );

package/src/clerk/clerk-page-generator.tsx

@@ -1,14 +1,15 @@
 import { SignIn, SignUp, Waitlist } from '@clerk/nextjs';
-
-const clerkPageContainerClassName =
-  'flex min-h-dvh w-full items-start justify-center px-6 pt-[calc(var(--fd-banner-height,0px)+var(--fd-header-height,3.5rem)+1rem)] pb-6 md:px-8 md:pt-[calc(var(--fd-banner-height,0px)+var(--fd-header-height,3.5rem)+1.5rem)] md:pb-8';
+import {
+  clerkAuthPageAppearance,
+  clerkAuthPageContainerClassName,
+} from './clerk-auth-appearance';
 
 // Legacy page generators (for backward compatibility)
 export function createSignInPage() {
   return function SignInPage() {
     return (
-      <div className={clerkPageContainerClassName}>
-        <SignIn />
+      <div className={clerkAuthPageContainerClassName}>
+        <SignIn appearance={clerkAuthPageAppearance} />
       </div>
     );
   };
@@ -17,8 +18,8 @@ export function createSignInPage() {
 export function createSignUpPage() {
   return function SignUpPage() {
     return (
-      <div className={clerkPageContainerClassName}>
-        <SignUp />
+      <div className={clerkAuthPageContainerClassName}>
+        <SignUp appearance={clerkAuthPageAppearance} />
       </div>
     );
   };
@@ -27,7 +28,7 @@ export function createSignUpPage() {
 export function createWaitlistPage() {
   return function WaitlistPage() {
     return (
-      <div className={clerkPageContainerClassName}>
+      <div className={clerkAuthPageContainerClassName}>
         <Waitlist />
       </div>
     );

package/src/clerk/clerk-user-client.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react';
 import { ClerkLoaded, ClerkLoading, SignInButton, UserButton, useAuth } from "@clerk/nextjs";
 import { ReceiptTextIcon, ShieldUserIcon } from '@windrun-huaiin/base-ui/icons';
 import { themeButtonGradientClass } from '@windrun-huaiin/base-ui/lib';
+import { clerkAuthModalAppearance } from './clerk-auth-appearance';
 import { SignUpButtonWithFingerprint } from './signup-button-with-fingerprint-client';
 
 interface ClerkUserData {
@@ -51,11 +52,19 @@ export function ClerkUserClient({ data }: { data: ClerkUserData }) {
                 )}
               </div>
             )}
-            <SignInButton mode={data.clerkAuthInModal ? 'modal' : 'redirect'}>
-              <button className="w-16 sm:w-20 h-8 sm:h-9 px-1.5 sm:px-2 border border-gray-300 rounded-full hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800 text-center text-xs sm:text-sm whitespace-nowrap">
-                {data.signIn}
-              </button>
-            </SignInButton>
+            {data.clerkAuthInModal ? (
+              <SignInButton mode="modal" appearance={clerkAuthModalAppearance}>
+                <button className="w-16 sm:w-20 h-8 sm:h-9 px-1.5 sm:px-2 border border-gray-300 rounded-full hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800 text-center text-xs sm:text-sm whitespace-nowrap">
+                  {data.signIn}
+                </button>
+              </SignInButton>
+            ) : (
+              <SignInButton mode="redirect">
+                <button className="w-16 sm:w-20 h-8 sm:h-9 px-1.5 sm:px-2 border border-gray-300 rounded-full hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800 text-center text-xs sm:text-sm whitespace-nowrap">
+                  {data.signIn}
+                </button>
+              </SignInButton>
+            )}
           </>
         )}
 

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

@@ -1,7 +1,7 @@
 /**
  * Fingerprint Client Utilities
- * 客户端专用的指纹生成和管理逻辑
- * 只能在浏览器环境中使用
+ * Client-only fingerprint generation and management logic.
+ * Must be used only in browser environments.
  */
 
 import FingerprintJS from '@fingerprintjs/fingerprintjs';
@@ -41,24 +41,24 @@ type FirstTouchData = {
 };
 
 /**
- * 检查浏览器存储（localStorage 和 cookie）中的指纹 ID
- * 返回有效的 ID 或 null
+ * Check fingerprint ID in browser storage, including localStorage and cookies.
+ * Returns a valid ID or null.
  */
 function checkStoredFingerprintId(): string | null {
   if (typeof window === 'undefined') {
     return null;
   }
 
-  // 优先检查 localStorage
+  // Prefer localStorage.
   const localStorageId = getLocalStorageValue(FINGERPRINT_STORAGE_KEY);
   if (localStorageId && isValidFingerprintId(localStorageId)) {
     return localStorageId;
   }
 
-  // 检查 cookie
+  // Check cookies.
   const cookieId = getCookieValue(FINGERPRINT_COOKIE_NAME);
   if (cookieId && isValidFingerprintId(cookieId)) {
-    // 同步到 localStorage
+    // Sync back to localStorage.
     setLocalStorageValue(FINGERPRINT_STORAGE_KEY, cookieId);
     return cookieId;
   }
@@ -203,34 +203,34 @@ export function getOrCreateFirstTouchData(): FirstTouchData | null {
 }
 
 /**
- * 生成基于真实浏览器特征的fingerprint ID
- * 使用 FingerprintJS 收集浏览器特征并生成唯一标识
+ * Generate a fingerprint ID from real browser characteristics.
+ * Uses FingerprintJS to collect browser signals and create a stable identifier.
  */
 export async function generateFingerprintId(): Promise<string> {
   if (typeof window === 'undefined') {
     throw new Error('generateFingerprintId can only be used in browser environment');
   }
 
-  // 检查现有 ID
+  // Check for an existing ID.
   const existingId = checkStoredFingerprintId();
   if (existingId) {
     return existingId;
   }
 
   try {
-    // 使用 FingerprintJS 生成指纹
+    // Generate a fingerprint with FingerprintJS.
     const fp = await FingerprintJS.load();
     const result = await fp.get();
     const fingerprintId = `fp_${result.visitorId}`;
 
-    // 存储到 localStorage 和 cookie
+    // Store in localStorage and cookies.
     setLocalStorageValue(FINGERPRINT_STORAGE_KEY, fingerprintId);
     setCookie(FINGERPRINT_COOKIE_NAME, fingerprintId, 365);
 
     return fingerprintId;
   } catch (error) {
     console.warn('Failed to generate fingerprint with FingerprintJS:', error);
-    // 降级方案：生成基于时间戳和随机数的 ID
+    // Fallback: generate an ID from timestamp and randomness.
     const fallbackId = `fp_fallback_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
     setLocalStorageValue(FINGERPRINT_STORAGE_KEY, fallbackId);
     setCookie(FINGERPRINT_COOKIE_NAME, fallbackId, 365);
@@ -240,14 +240,14 @@ export async function generateFingerprintId(): Promise<string> {
 }
 
 /**
- * 获取当前的fingerprint ID
+ * Get the current fingerprint ID.
  */
 export function getFingerprintId(): string | null {
   return checkStoredFingerprintId();
 }
 
 /**
- * 设置fingerprint ID到存储
+ * Store a fingerprint ID.
  */
 export function setFingerprintId(fingerprintId: string): void {
   if (typeof window === 'undefined') {
@@ -263,7 +263,7 @@ export function setFingerprintId(fingerprintId: string): void {
 }
 
 /**
- * 清除fingerprint ID
+ * Clear the fingerprint ID.
  */
 export function clearFingerprintId(): void {
   if (typeof window === 'undefined') {
@@ -275,8 +275,8 @@ export function clearFingerprintId(): void {
 }
 
 /**
- * 获取或生成fingerprint ID
- * 如果不存在则自动生成新的
+ * Get or generate a fingerprint ID.
+ * Automatically creates one when none exists.
  */
 export async function getOrGenerateFingerprintId(): Promise<string> {
   const existingId = checkStoredFingerprintId();
@@ -288,7 +288,7 @@ export async function getOrGenerateFingerprintId(): Promise<string> {
 }
 
 /**
- * 创建包含fingerprint ID的fetch headers
+ * Create fetch headers containing the fingerprint ID.
  */
 export async function createFingerprintHeaders(): Promise<Record<string, string>> {
   const fingerprintId = await getOrGenerateFingerprintId();
@@ -330,7 +330,7 @@ export function createFingerprintFetch() {
   };
 }
 
-// Cookie 辅助函数 (私有)
+// Private cookie helpers.
 function getCookieValue(name: string): string | null {
   if (typeof document === 'undefined') {
     return null;

package/src/clerk/fingerprint/fingerprint-provider.tsx

@@ -109,7 +109,7 @@ function useFingerprintStatusTranslations(): FingerprintStatusTranslations {
 
 /**
  * Fingerprint Provider Component
- * 为应用提供fingerprint和匿名用户管理功能
+ * Provides fingerprint and anonymous user management for the application.
  */
 export function FingerprintProvider({ 
   children,
@@ -137,7 +137,7 @@ export function useFingerprintContext(): FingerprintContextType {
 
 /**
  * Safe hook to use fingerprint context - returns null if no provider
- * 安全版本的fingerprint context hook - 如果没有Provider则返回null
+ * Returns null when no provider is available.
  */
 export function useFingerprintContextSafe(): FingerprintContextType | null {
   const context = useContext(FingerprintContext);
@@ -162,7 +162,7 @@ export function withFingerprint<P extends object>(
 }
 
 /**
- * 组件：显示用户状态和积分信息（用于调试）
+ * Component for displaying user status and credit information for debugging.
  */
 export function FingerprintStatus() {
   const translations = useFingerprintStatusTranslations();
@@ -400,7 +400,7 @@ export function FingerprintStatus() {
 
   return (
     <>
-      {/* 灯泡按钮 */}
+      {/* Lightbulb button */}
       {!isOpen && (
         <button
           onClick={handleToggle}
@@ -417,7 +417,7 @@ export function FingerprintStatus() {
         </button>
       )}
 
-      {/* 面板 */}
+      {/* Panel */}
       {isOpen && (
         <>
           <div onClick={handleBackdropClick} className="fixed inset-0 z-9998 bg-black/60 backdrop-blur-sm" />
@@ -622,9 +622,9 @@ export function FingerprintStatus() {
 }
 
 
-/* ==================== 新增辅助组件 ==================== */
+/* ==================== Helper Components ==================== */
 
-// 标题行：左侧图标+标题，右侧信息（右对齐）
+// Header row with icon and title on the left, right-aligned metadata on the right.
 function PanelHeader({ icon, title, rightInfo }: { icon: React.ReactNode; title: string; rightInfo: React.ReactNode }) {
   return (
     <div className="flex items-center justify-between mb-3">
@@ -643,7 +643,7 @@ function PanelHeader({ icon, title, rightInfo }: { icon: React.ReactNode; title:
   );
 }
 
-// 复用：普通 PanelSection 支持右侧信息
+// Reusable PanelSection with optional right-side metadata.
 interface PanelSectionProps {
   icon: React.ReactNode;
   title: string;
@@ -727,19 +727,19 @@ function StatusTag({
   const normalized = value.toLowerCase();
 
   const colorMap: Record<string, string> = {
-    // 绿色：正常/活跃
+    // Green: normal or active.
     registered: 'bg-green-100 text-green-700 dark:bg-green-500/20 dark:text-green-300',
     active: 'bg-green-100 text-green-700 dark:bg-green-500/20 dark:text-green-300',
     trialing: 'bg-green-100 text-green-700 dark:bg-green-500/20 dark:text-green-300',
 
-    // 灰色：失效/删除
+    // Gray: inactive or deleted.
     canceled: 'bg-slate-100 text-slate-600 dark:bg-slate-700 dark:text-slate-400',
     frozen: 'bg-slate-100 text-slate-600 dark:bg-slate-700 dark:text-slate-400',
     deleted: 'bg-slate-100 text-slate-600 dark:bg-slate-700 dark:text-slate-400',
     expired: 'bg-slate-100 text-slate-600 dark:bg-slate-700 dark:text-slate-400',
     past_due: 'bg-slate-100 text-slate-600 dark:bg-slate-700 dark:text-slate-400',
 
-    // 橙色：待处理/异常
+    // Amber: pending or exceptional states.
     pending: 'bg-amber-100 text-amber-700 dark:bg-amber-500/20 dark:text-amber-300',
     failed: 'bg-amber-100 text-amber-700 dark:bg-amber-500/20 dark:text-amber-300',
     unpaid: 'bg-amber-100 text-amber-700 dark:bg-amber-500/20 dark:text-amber-300',

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

@@ -1,7 +1,7 @@
 /**
  * Fingerprint Server Utilities
- * 服务端专用的指纹ID提取和验证逻辑
- * 可以安全地在服务端使用，不依赖浏览器API或FingerprintJS
+ * Server-only fingerprint ID extraction and validation logic.
+ * Safe for server usage without browser APIs or FingerprintJS.
  */
 
 import {
@@ -11,16 +11,16 @@ import {
 } from './fingerprint-shared';
 
 /**
- * 从请求中提取fingerprint ID
- * 优先级：header > cookie > query参数
- * 可以安全地在服务端使用
+ * Extract fingerprint ID from a request.
+ * Priority: header > cookie > query parameter.
+ * Safe to use on the server.
  */
 export function extractFingerprintId(
   headers: Headers | Record<string, string>,
   cookies?: Record<string, string>,
   query?: Record<string, string | undefined>
 ): string | null {
-  // 1. 从header中获取
+  // 1. Read from header.
   const headerValue = headers instanceof Headers 
     ? headers.get(FINGERPRINT_HEADER_NAME)
     : headers[FINGERPRINT_HEADER_NAME];
@@ -29,7 +29,7 @@ export function extractFingerprintId(
     return headerValue;
   }
 
-  // 2. 从cookie中获取
+  // 2. Read from cookie.
   if (cookies) {
     const cookieValue = cookies[FINGERPRINT_COOKIE_NAME];
     if (cookieValue && isValidFingerprintId(cookieValue)) {
@@ -37,7 +37,7 @@ export function extractFingerprintId(
     }
   }
 
-  // 3. 从query参数中获取
+  // 3. Read from query parameters.
   if (query) {
     const queryValue = query.fingerprint_id || query.fp_id;
     if (queryValue && isValidFingerprintId(queryValue)) {
@@ -49,22 +49,22 @@ export function extractFingerprintId(
 }
 
 /**
- * 生成服务端降级fingerprint ID
- * 当客户端无法生成fingerprint时使用
- * 可以安全地在服务端使用
+ * Generate a server-side fallback fingerprint ID.
+ * Used when the client cannot generate a fingerprint.
+ * Safe to use on the server.
  */
 export function generateServerFingerprintId(): string {
   return `fp_server_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
 }
 
 /**
- * 从Next.js Request对象中提取fingerprint ID
- * 便捷方法，适用于Next.js API路由
+ * Extract fingerprint ID from a Next.js Request object.
+ * Convenience helper for Next.js API routes.
  */
 export function extractFingerprintFromNextRequest(request: Request): string | null {
   const headers = request.headers;
   
-  // 尝试从cookies获取（需要解析cookie header）
+  // Try cookies by parsing the cookie header.
   const cookieHeader = headers.get('cookie');
   const cookies: Record<string, string> = {};
   
@@ -77,7 +77,7 @@ export function extractFingerprintFromNextRequest(request: Request): string | nu
     });
   }
 
-  // 尝试从URL query参数获取
+  // Try URL query parameters.
   const url = new URL(request.url);
   const query: Record<string, string> = {};
   url.searchParams.forEach((value, key) => {
@@ -93,8 +93,8 @@ type NextCookiesLike = {
 };
 
 /**
- * 从Next.js runtime提供的headers/cookies实例里提取fingerprint ID
- * 供App Router服务端组件和Server Actions直接复用
+ * Extract fingerprint ID from Next.js runtime headers/cookies stores.
+ * Reusable in App Router server components and Server Actions.
  */
 export function extractFingerprintFromNextStores(params: {
   headers: NextHeadersLike;

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

@@ -1,9 +1,9 @@
 /**
  * Fingerprint Shared Utilities
- * 客户端和服务端共享的常量、类型和验证逻辑
+ * Shared constants, types, and validation logic for client and server.
  */
 
-// Fingerprint ID的存储键和header名
+// Storage keys and header names for fingerprint IDs.
 export const FINGERPRINT_STORAGE_KEY = '__x_fingerprint_id';
 export const FINGERPRINT_DEBUG_OVERRIDE_STORAGE_KEY = '__x_fingerprint_debug_override';
 export const FINGERPRINT_HEADER_NAME = 'x-fingerprint-id-v8';
@@ -15,16 +15,16 @@ export const FINGERPRINT_FIRST_TOUCH_HEADER = 'x-first-touch';
 export const FINGERPRINT_DEBUG_PREFIX = 'fp_test_dbg_';
 
 /**
- * 验证fingerprint ID格式
- * 可以在客户端和服务端使用
+ * Validate fingerprint ID format.
+ * Safe to use on both client and server.
  */
 export function isValidFingerprintId(fingerprintId: string): boolean {
   if (!fingerprintId) return false;
-  // 支持多种格式：
-  // - fp_ + FingerprintJS visitorId (变长字符串)
-  // - fp_fallback_ + 时间戳_随机字符串 (客户端降级方案)
-  // - fp_server_ + 时间戳_随机字符串 (服务端降级)
-  // - fp_test_dbg_ + 时间戳_随机字符串 (调试并发测试)
+  // Supported formats:
+  // - fp_ + FingerprintJS visitorId with variable length.
+  // - fp_fallback_ + timestamp + random string for client fallback.
+  // - fp_server_ + timestamp + random string for server fallback.
+  // - fp_test_dbg_ + timestamp + random string for debug concurrency tests.
   return /^fp(_fallback|_server|_test_dbg)?_[a-zA-Z0-9_]+$/.test(fingerprintId);
 }
 
@@ -36,7 +36,7 @@ export function isDebugFingerprintId(fingerprintId: string | null | undefined):
   return fingerprintId.startsWith(FINGERPRINT_DEBUG_PREFIX);
 }
 
-// 常量导出
+// Exported constants.
 export const FINGERPRINT_CONSTANTS = {
   STORAGE_KEY: FINGERPRINT_STORAGE_KEY,
   DEBUG_OVERRIDE_STORAGE_KEY: FINGERPRINT_DEBUG_OVERRIDE_STORAGE_KEY,

package/src/clerk/fingerprint/types.ts

@@ -1,6 +1,5 @@
 /**
  * Fingerprint System Types
- * 指纹识别系统的类型定义
  */
 
 export interface XUser {