@windrun-huaiin/third-ui 30.0.0 → 31.0.0

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 {

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

@@ -21,7 +21,7 @@ import { FINGERPRINT_SOURCE_REFER, isDebugFingerprintId, isValidFingerprintId }
  * Accepts configuration to customize API endpoint and behavior
  */
 export function useFingerprint(config: FingerprintConfig): UseFingerprintResult {
-  // 服务端渲染检查
+  // Server-side rendering guard.
   if (typeof window === 'undefined') {
     return {
       fingerprintId: null,
@@ -51,7 +51,7 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
   }, []);
 
   /**
-   * 第一阶段：初始化fingerprint ID
+   * Phase 1: initialize fingerprint ID.
    */
   const initializeFingerprintId = useCallback(async () => {
     try {
@@ -68,7 +68,7 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
   }, []);
 
   /**
-   * 第二阶段：初始化匿名用户
+   * Phase 2: initialize anonymous user.
    */
   const initializeAnonymousUser = useCallback(async () => {
     if (!fingerprintId) {
@@ -140,7 +140,7 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
   }, [fingerprintId, config.apiEndpoint, isInitialized]);
 
   /**
-   * 刷新用户数据 - 使用POST请求（后端支持upsert逻辑）
+   * Refresh user data with a POST request; the backend supports upsert semantics.
    */
   const refreshUserData = useCallback(async () => {
     if (!fingerprintId) {
@@ -180,7 +180,7 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
     }
   }, [fingerprintId, config.apiEndpoint]);
 
-  // 第一阶段：页面加载完成后生成指纹ID
+  // Phase 1: generate fingerprint ID after page load.
   useEffect(() => {
     const initFingerprint = async () => {
       setIsLoading(true);
@@ -191,11 +191,11 @@ export function useFingerprint(config: FingerprintConfig): UseFingerprintResult
     initFingerprint();
   }, [initializeFingerprintId]);
 
-  // 第二阶段：有指纹ID后直接初始化用户（后端支持upsert逻辑）
+  // Phase 2: initialize the user once a fingerprint ID is available; the backend supports upsert semantics.
   useEffect(() => {
     if (!fingerprintId || isInitialized || isLoading || error || config.autoInitialize === false) return;
     
-    // 直接使用 POST 请求，后端会处理查询-不存在则创建的逻辑
+    // Use POST directly; the backend handles lookup and create-if-missing behavior.
     initializeAnonymousUser();
   }, [fingerprintId, isInitialized, isLoading, error, initializeAnonymousUser, config.autoInitialize]);
 

package/src/clerk/signin-with-fingerprint-client.tsx

@@ -2,17 +2,18 @@
 
 import { SignIn } from '@clerk/nextjs';
 import { useEffect } from 'react';
+import { clerkAuthPageAppearance } from './clerk-auth-appearance';
 import { useFingerprintContextSafe } from './fingerprint/fingerprint-provider';
 
 /**
  * SignIn component with fingerprint awareness
- * 如果没有FingerprintProvider，会优雅降级为普通SignIn组件
- * 如果有FingerprintProvider，会处理fingerprint相关逻辑
+ * Falls back to the standard SignIn component when FingerprintProvider is absent.
+ * Handles fingerprint-related metadata when FingerprintProvider is available.
  */
 export function SignInWithFingerprint() {
   const fingerprintContext = useFingerprintContextSafe();
   
-  // 如果没有fingerprint context，使用默认值
+  // Use defaults when fingerprint context is unavailable.
   const { 
     fingerprintId = null, 
     xUser = null, 
@@ -20,19 +21,18 @@ export function SignInWithFingerprint() {
     initializeAnonymousUser = async () => {}
   } = fingerprintContext || {};
 
-  // 准备传递给Clerk的metadata，包含匿名用户信息
+  // Prepare Clerk metadata with anonymous user information.
   const unsafeMetadata = {
     user_id: xUser?.userId || null, 
     fingerprint_id: fingerprintId || null,
   };
 
-  // 确保匿名用户已初始化
+  // Ensure the anonymous user has been initialized.
   useEffect(() => {
     if (!isInitialized && fingerprintId) {
       initializeAnonymousUser();
     }
   }, [fingerprintId, isInitialized, initializeAnonymousUser]);
 
-  return <SignIn unsafeMetadata={unsafeMetadata} />;
+  return <SignIn appearance={clerkAuthPageAppearance} unsafeMetadata={unsafeMetadata} />;
 }
-

package/src/clerk/signup-button-with-fingerprint-client.tsx

@@ -2,6 +2,7 @@
 
 import { SignUpButton, useClerk } from '@clerk/nextjs';
 import { useEffect } from 'react';
+import { clerkAuthModalAppearance } from './clerk-auth-appearance';
 import { useFingerprintContextSafe } from './fingerprint/fingerprint-provider';
 
 interface SignUpButtonWithFingerprintProps {
@@ -15,7 +16,7 @@ export function SignUpButtonWithFingerprint({
 }: SignUpButtonWithFingerprintProps) {
   if (mode === 'redirect') {
     return (
-      // 重定向模式则直接跳转到自定义注册页面
+      // Redirect mode navigates directly to the custom sign-up page.
       <SignUpButton>
         <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"
@@ -26,10 +27,10 @@ export function SignUpButtonWithFingerprint({
     )
   }
 
-  // 弹框模式则需要自定义注册按钮
+  // Modal mode requires a custom sign-up button.
   const fingerprintContext = useFingerprintContextSafe();
 
-  // 如果没有fingerprint context，使用默认值
+  // Use defaults when fingerprint context is unavailable.
   const { 
     fingerprintId = null, 
     xUser = null, 
@@ -43,7 +44,7 @@ export function SignUpButtonWithFingerprint({
     fingerprint_id: fingerprintId || null,
   };
 
-  // 确保匿名用户已初始化
+  // Ensure the anonymous user has been initialized.
   useEffect(() => {
     if (!isInitialized && fingerprintId) {
       initializeAnonymousUser();
@@ -55,6 +56,7 @@ export function SignUpButtonWithFingerprint({
 
   const handleClick = () => {
     openSignUp({
+      appearance: clerkAuthModalAppearance,
       unsafeMetadata,
     });
   };
@@ -67,4 +69,4 @@ export function SignUpButtonWithFingerprint({
       {signUp}
     </button>
     );
-}
+}

package/src/clerk/signup-with-fingerprint-client.tsx

@@ -2,17 +2,18 @@
 
 import { SignUp } from '@clerk/nextjs';
 import { useEffect } from 'react';
+import { clerkAuthPageAppearance } from './clerk-auth-appearance';
 import { useFingerprintContextSafe } from './fingerprint/fingerprint-provider';
 
 /**
  * SignUp component with fingerprint awareness
- * 如果没有FingerprintProvider，会优雅降级为普通SignUp组件
- * 如果有FingerprintProvider，会处理fingerprint相关逻辑
+ * Falls back to the standard SignUp component when FingerprintProvider is absent.
+ * Handles fingerprint-related metadata when FingerprintProvider is available.
  */
 export function SignUpWithFingerprint() {
   const fingerprintContext = useFingerprintContextSafe();
   
-  // 如果没有fingerprint context，使用默认值
+  // Use defaults when fingerprint context is unavailable.
   const { 
     fingerprintId = null, 
     xUser = null, 
@@ -20,19 +21,18 @@ export function SignUpWithFingerprint() {
     initializeAnonymousUser = async () => {}
   } = fingerprintContext || {};
 
-  // 准备传递给Clerk的metadata，包含匿名用户信息
+  // Prepare Clerk metadata with anonymous user information.
   const unsafeMetadata = {
     user_id: xUser?.userId || null,
     fingerprint_id: fingerprintId || null,
   };
 
-  // 确保匿名用户已初始化
+  // Ensure the anonymous user has been initialized.
   useEffect(() => {
     if (!isInitialized && fingerprintId) {
       initializeAnonymousUser();
     }
   }, [fingerprintId, isInitialized, initializeAnonymousUser]);
 
-  return <SignUp unsafeMetadata={unsafeMetadata} />;
+  return <SignUp appearance={clerkAuthPageAppearance} unsafeMetadata={unsafeMetadata} />;
 }
-

package/src/fuma/base/custom-home-layout.tsx

@@ -11,10 +11,10 @@ import {
   type MobileMenuAction,
 } from './custom-header';
 
-// - bannerHeight/headerHeight 换成你项目期望的 rem 值即可（如果没有 Banner 就把 bannerHeight 设成 0）。
-// - layoutStyle 同时把变量传给 HomeLayout 的 main 元素，这样内容整体会往下错开，不需要 has-banner/no-banner class。
-// - CustomHomeHeader 直接接受 HomeLayout 的各类 props（links、nav、searchToggle、themeSwitch、i18n 等），内部会复用 Fumadocs 原本的导航功能。
-// - Banner 部分仍然可以用你现有的 FumaBannerSuit（或者任何自定义 Banner 组件），因为 Header 是固定定位、z-index 也处理好了，开关只影响 bannerHeight。
+// - Set bannerHeight/headerHeight to the rem values expected by the project. Use bannerHeight = 0 when there is no banner.
+// - layoutStyle passes the variables to HomeLayout's main element, offsetting content without has-banner/no-banner classes.
+// - CustomHomeHeader accepts HomeLayout props such as links, nav, searchToggle, themeSwitch, and i18n, then reuses Fumadocs navigation behavior.
+// - The banner can still use FumaBannerSuit or any custom banner component. Header positioning and z-index are already handled; the toggle only affects bannerHeight.
 
 export interface CustomHomeLayoutProps {
   locale: string;

package/src/fuma/fuma-page-genarator.tsx

@@ -3,6 +3,7 @@ import { ReactNode, ReactElement, cloneElement, type CSSProperties } from 'react
 import { TocFooterWrapper } from './mdx/toc-footer-wrapper';
 import type { LLMCopyButtonProps, LLMCopyButton } from './mdx/toc-base';
 import { getAsNeededLocalizedUrl } from '@windrun-huaiin/lib/utils';
+import { notFound } from 'next/navigation';
 import { PortableClerkTOC, PortableClerkTOCTitle } from './mdx/toc-clerk-portable';
 import { themeSvgIconColor } from '@windrun-huaiin/base-ui/lib';
 
@@ -36,14 +37,6 @@ interface FumaPageParams {
    * The copy button component, must be LLMCopyButton
    */
   copyButtonComponent?: ReactElement<LLMCopyButtonProps, typeof LLMCopyButton>;
-  /* 
-   * The site icon component to use in NotFoundPage
-   */
-  siteIcon: ReactNode;
-  /* 
-   * The fallback page component to use when the page is not found
-   */
-  FallbackPage: React.ComponentType<{ siteIcon: ReactNode }>;
   /*
    * Supported locales for generating alternates metadata, defaults to ['en']
    */
@@ -89,8 +82,6 @@ export function createFumaPage({
   mdxSourceDir,
   githubBaseUrl,
   copyButtonComponent,
-  siteIcon,
-  FallbackPage,
   supportedLocales = ['en'],
   showBreadcrumb = true,
   showTableOfContent = true,
@@ -138,18 +129,7 @@ export function createFumaPage({
       totalElapsedMs: durationMs(pageStartedAt),
     });
     if (!page) {
-      return (
-        <DocsPage
-          full
-          breadcrumb={{ enabled: false }}
-          footer={{ enabled: false }}
-          tableOfContent={{ enabled: false }}
-          tableOfContentPopover={{ enabled: false }}
-          className="max-w-none px-0 py-0"
-        >
-          <FallbackPage siteIcon={siteIcon} />
-        </DocsPage>
-      );
+      notFound();
     }
 
     const path = githubBaseUrl ? `${mdxSourceDir}/${page.path}` : undefined;

package/src/fuma/heavy/mermaid.tsx

@@ -179,7 +179,7 @@ export function Mermaid({ chart, title, watermarkEnabled, watermarkText, handDra
   // prevent browser-level zoom (touchpad pinch/shortcut) from taking effect when the dialog is open
   useEffect(() => {
     if (!open) return;
-    // 初次打开时，默认放大到 400%
+    // Init default zoom out 400%
     resetTransform();
     const onGlobalWheel = (ev: WheelEvent) => {
       if (ev.ctrlKey || ev.metaKey) {

package/src/fuma/site-x.tsx

@@ -10,7 +10,6 @@ export type SiteXProps = Omit<HTMLAttributes<HTMLSpanElement>, 'type'> & {
 };
 
 export async function SiteX({ locale, type, namespace, tKey, className, ...props }: SiteXProps) {
-  // 默认命名空间和key
   let ns = namespace;
   let key = tKey;
   if (!ns) {