@allbluecn/web-app 0.17.2 → 0.18.1

package/allblue-ui/src/ui/toast.tsx

@@ -0,0 +1,308 @@
+import * as React from "react"
+import { Toast as ToastPrimitive } from "@base-ui/react/toast"
+import { cn } from "cn"
+
+import { Button } from "./button"
+import { XIcon, CircleCheckIcon, InfoIcon, TriangleAlertIcon, OctagonXIcon, Loader2Icon } from "lucide-react"
+
+const toastManager = ToastPrimitive.createToastManager()
+
+// 双端历史分叉：web 顶部居中堆叠（top-center），admin 右下角堆叠（bottom-right）。
+// 差异为纯 class 组 + swipeDirection，通过 position 参数承载，行为逐字节等价于原实现。
+type ToasterPosition = "top-center" | "bottom-right"
+
+const ToastPositionContext = React.createContext<ToasterPosition>("top-center")
+
+interface SonnerToastOptions {
+  description?: React.ReactNode
+  duration?: number
+  action?: { label: React.ReactNode; onClick?: () => void }
+}
+
+function buildOptions(message: React.ReactNode, type: string | undefined, opts?: SonnerToastOptions) {
+  return {
+    type,
+    title: message,
+    description: opts?.description,
+    timeout: opts?.duration,
+    actionProps: opts?.action
+      ? { children: opts.action.label, onClick: opts.action.onClick }
+      : undefined,
+  }
+}
+
+const toast = Object.assign(
+  (message: React.ReactNode, opts?: SonnerToastOptions) =>
+    toastManager.add(buildOptions(message, undefined, opts)),
+  {
+    success: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, "success", opts)),
+    error: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, "error", opts)),
+    warning: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, "warning", opts)),
+    info: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, "info", opts)),
+    loading: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, "loading", { ...opts, duration: 0 })),
+    message: (message: React.ReactNode, opts?: SonnerToastOptions) =>
+      toastManager.add(buildOptions(message, undefined, opts)),
+    dismiss: (id?: string) => toastManager.close(id),
+    promise: <Value,>(
+      promiseValue: Promise<Value>,
+      options: {
+        loading: string
+        success: string | ((result: Value) => string)
+        error: string | ((error: unknown) => string)
+      },
+    ) =>
+      toastManager.promise(promiseValue, {
+        loading: options.loading,
+        success: options.success,
+        error: options.error,
+      }),
+  },
+)
+
+function ToastProvider({ ...props }: ToastPrimitive.Provider.Props) {
+  return <ToastPrimitive.Provider {...props} />
+}
+
+function ToastPortal({ ...props }: ToastPrimitive.Portal.Props) {
+  return <ToastPrimitive.Portal data-slot="toast-portal" {...props} />
+}
+
+function ToastViewport({ className, ...props }: ToastPrimitive.Viewport.Props) {
+  const top = React.useContext(ToastPositionContext) === "top-center"
+  return (
+    <ToastPrimitive.Viewport
+      data-slot="toast-viewport"
+      className={cn(
+        top
+          ? "pointer-events-none fixed top-4 left-0 right-0 z-50 mx-auto w-full max-w-sm outline-none sm:top-6"
+          : "pointer-events-none fixed bottom-4 right-4 z-50 w-full max-w-sm outline-none sm:bottom-6 sm:right-6",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function Toast({ className, ...props }: ToastPrimitive.Root.Props) {
+  const top = React.useContext(ToastPositionContext) === "top-center"
+  return (
+    <ToastPrimitive.Root
+      data-slot="toast"
+      className={cn(
+        top
+          ? "group/toast pointer-events-auto absolute top-0 right-0 left-0 z-[calc(1000-var(--toast-index))] mx-auto w-full origin-top rounded-2xl border bg-popover text-popover-foreground shadow-lg will-change-transform outline-none select-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50"
+          : "group/toast pointer-events-auto absolute right-0 bottom-0 z-[calc(1000-var(--toast-index))] w-full origin-bottom rounded-2xl border bg-popover text-popover-foreground shadow-lg will-change-transform outline-none select-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50",
+        top
+          ? "[--gap:0.75rem] [--height:var(--toast-frontmost-height,var(--toast-height))] [--offset-y:calc(var(--toast-offset-y)+calc(var(--toast-index)*var(--gap))+var(--toast-swipe-movement-y))] [--peek:0.75rem] [--scale:calc(max(0,1-(var(--toast-index)*0.1)))] [--shrink:calc(1-var(--scale))]"
+          : "[--gap:0.75rem] [--height:var(--toast-frontmost-height,var(--toast-height))] [--offset-y:calc(var(--toast-offset-y)*-1+calc(var(--toast-index)*var(--gap)*-1)+var(--toast-swipe-movement-y))] [--peek:0.75rem] [--scale:calc(max(0,1-(var(--toast-index)*0.1)))] [--shrink:calc(1-var(--scale))]",
+        top
+          ? "h-(--height) [transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)+(var(--toast-index)*var(--peek))+(var(--shrink)*var(--height))))_scale(var(--scale))] [transition:transform_500ms_cubic-bezier(0.22,1,0.36,1),opacity_500ms,height_150ms]"
+          : "h-(--height) [transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)-(var(--toast-index)*var(--peek))-(var(--shrink)*var(--height))))_scale(var(--scale))] [transition:transform_500ms_cubic-bezier(0.22,1,0.36,1),opacity_500ms,height_150ms]",
+        top
+          ? "after:absolute after:bottom-full after:left-0 after:h-[calc(var(--gap)+1px)] after:w-full after:content-['']"
+          : "after:absolute after:top-full after:left-0 after:h-[calc(var(--gap)+1px)] after:w-full after:content-['']",
+        "data-expanded:h-(--toast-height) data-expanded:[transform:translateX(var(--toast-swipe-movement-x))_translateY(var(--offset-y))]",
+        top
+          ? "data-limited:opacity-0 data-starting-style:[transform:translateY(-150%)]"
+          : "data-limited:opacity-0 data-starting-style:[transform:translateY(150%)]",
+        top
+          ? "[&[data-ending-style]:not([data-limited]):not([data-swipe-direction])]:[transform:translateY(-150%)]"
+          : "[&[data-ending-style]:not([data-limited]):not([data-swipe-direction])]:[transform:translateY(150%)]",
+        "data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]",
+        "data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]",
+        "data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]",
+        "data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]",
+        "data-expanded:data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ToastContent({ className, ...props }: ToastPrimitive.Content.Props) {
+  return (
+    <ToastPrimitive.Content
+      data-slot="toast-content"
+      className={cn(
+        "flex h-full items-center gap-3 overflow-hidden p-4 transition-opacity duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] data-behind:opacity-0 data-expanded:opacity-100",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ToastTitle({ className, ...props }: ToastPrimitive.Title.Props) {
+  return (
+    <ToastPrimitive.Title
+      data-slot="toast-title"
+      className={cn("text-sm font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastDescription({
+  className,
+  ...props
+}: ToastPrimitive.Description.Props) {
+  return (
+    <ToastPrimitive.Description
+      data-slot="toast-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastAction({
+  className,
+  render = <Button variant="outline" size="sm" />,
+  ...props
+}: ToastPrimitive.Action.Props) {
+  return (
+    <ToastPrimitive.Action
+      data-slot="toast-action"
+      render={render}
+      className={cn("shrink-0", className)}
+      {...props}
+    />
+  )
+}
+
+function ToastClose({
+  className,
+  children,
+  render = <Button variant="ghost" size="icon-sm" />,
+  ...props
+}: ToastPrimitive.Close.Props) {
+  return (
+    <ToastPrimitive.Close
+      data-slot="toast-close"
+      aria-label="Close toast"
+      render={render}
+      className={cn(
+        "relative shrink-0 text-muted-foreground after:absolute after:-inset-2 after:content-[''] hover:text-foreground",
+        className
+      )}
+      {...props}
+    >
+      {children ?? (
+        <XIcon aria-hidden="true" />
+      )}
+    </ToastPrimitive.Close>
+  )
+}
+
+function ToastIcon({ type }: { type: string | undefined }) {
+  let icon: React.ReactNode = null
+
+  if (type === "success") {
+    icon = (
+      <CircleCheckIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "info") {
+    icon = (
+      <InfoIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "warning") {
+    icon = (
+      <TriangleAlertIcon aria-hidden="true" />
+    )
+  }
+
+  if (type === "error") {
+    icon = (
+      <OctagonXIcon className="text-destructive" aria-hidden="true" />
+    )
+  }
+
+  if (type === "loading") {
+    icon = (
+      <Loader2Icon className="animate-spin" aria-hidden="true" />
+    )
+  }
+
+  if (!icon) {
+    return null
+  }
+
+  return (
+    <span
+      data-slot="toast-icon"
+      className="shrink-0 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4"
+    >
+      {icon}
+    </span>
+  )
+}
+
+function ToastList() {
+  const { toasts } = ToastPrimitive.useToastManager()
+  const top = React.useContext(ToastPositionContext) === "top-center"
+
+  return toasts.map((toastItem) => (
+    <Toast key={toastItem.id} toast={toastItem} swipeDirection={top ? "up" : undefined}>
+      <ToastContent>
+        <ToastIcon type={toastItem.type} />
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <ToastTitle />
+          <ToastDescription />
+        </div>
+        <ToastAction />
+        <ToastClose />
+      </ToastContent>
+    </Toast>
+  ))
+}
+
+function Toaster({
+  children,
+  position = "top-center",
+  ...props
+}: ToastPrimitive.Provider.Props & { position?: ToasterPosition }) {
+  return (
+    <ToastPositionContext.Provider value={position}>
+      <ToastProvider toastManager={toastManager} {...props}>
+        {children}
+        <ToastPortal>
+          <ToastViewport>
+            <ToastList />
+          </ToastViewport>
+        </ToastPortal>
+      </ToastProvider>
+    </ToastPositionContext.Provider>
+  )
+}
+
+const createToastManager = ToastPrimitive.createToastManager
+const useToastManager = ToastPrimitive.useToastManager
+
+export {
+  Toaster,
+  Toast,
+  ToastAction,
+  ToastClose,
+  ToastContent,
+  ToastDescription,
+  ToastPortal,
+  ToastProvider,
+  ToastTitle,
+  ToastViewport,
+  createToastManager,
+  toast,
+  useToastManager,
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@allbluecn/web-app",
-  "version": "0.17.2",
+  "version": "0.18.1",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
     "src",
     "public",
-    "vite.shared.ts"
+    "vite.shared.ts",
+    "allblue-ui"
   ],
   "exports": {
     "./vite.shared": {
@@ -41,17 +42,9 @@
       "types": "./src/components/shared-kit/icons/lucide-icon-picker/icon-set.ts",
       "default": "./src/components/shared-kit/icons/lucide-icon-picker/icon-set.ts"
     },
-    "./prototype": {
-      "types": "./src/components/prototype/index.ts",
-      "default": "./src/components/prototype/index.ts"
-    },
-    "./user-avatar": {
-      "types": "./src/components/shared-kit/avatars/user-avatar.tsx",
-      "default": "./src/components/shared-kit/avatars/user-avatar.tsx"
-    },
-    "./lib/datetime": {
-      "types": "./src/lib/datetime.ts",
-      "default": "./src/lib/datetime.ts"
+    "./design/canvas": {
+      "types": "./src/components/design/canvas/index.ts",
+      "default": "./src/components/design/canvas/index.ts"
     },
     "./lib/pacer": {
       "types": "./src/lib/pacer.ts",
@@ -60,18 +53,14 @@
     "./ai-gateway/tools": {
       "types": "./src/server/ai-gateway/tools.ts",
       "default": "./src/server/ai-gateway/tools.ts"
-    },
-    "./ai-gateway/prompts/definitions": {
-      "types": "./src/server/ai-gateway/prompts/definitions.ts",
-      "default": "./src/server/ai-gateway/prompts/definitions.ts"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@allbluecn/database": "0.9.1",
-    "@allbluecn/kernel": "0.9.0",
+    "@allbluecn/database": "0.9.2",
+    "@allbluecn/kernel": "0.9.1",
     "@ariakit/react": "^0.4.28",
     "@auth/core": "^0.41.2",
     "@auth/prisma-adapter": "^2.11.2",
@@ -87,6 +76,10 @@
     "@fontsource-variable/inter": "^5.3.0",
     "@fumadocs/language": "^0.2.4",
     "@iconify/react": "^6.0.2",
+    "@leafer-in/arrow": "2.3.0",
+    "@leafer-in/color": "2.3.0",
+    "@leafer-in/editor": "2.3.0",
+    "@leafer-ui/core": "2.3.0",
     "@lobehub/icons": "^5.19.3",
     "@lucide/lab": "^0.2.0",
     "@mind-elixir/export-html": "3.0.0",
@@ -94,6 +87,7 @@
     "@open-file-viewer/core": "^0.1.43",
     "@open-file-viewer/react": "^0.1.43",
     "@opentelemetry/api": "^1.9.1",
+    "@paper-design/shaders": "0.0.81",
     "@phosphor-icons/react": "^2.1.10",
     "@prisma/client": "^7.8.0",
     "@radix-ui/react-dialog": "^1.1.23",
@@ -137,20 +131,20 @@
     "@tanstack/db": "0.8.6",
     "@tanstack/hotkeys": "^0.8.0",
     "@tanstack/markdown": "^0.0.15",
-    "@tanstack/pacer": "^0.22.0",
+    "@tanstack/pacer": "^0.23.1",
     "@tanstack/query-db-collection": "1.2.11",
     "@tanstack/react-db": "0.3.6",
     "@tanstack/react-form": "2.0.0-alpha.2",
     "@tanstack/react-hotkeys": "^0.10.0",
-    "@tanstack/react-pacer": "^0.23.0",
-    "@tanstack/react-query": "^5.102.8",
-    "@tanstack/react-router": "1.170.32",
-    "@tanstack/react-router-ssr-query": "^1.167.2",
-    "@tanstack/react-start": "^1.168.49",
-    "@tanstack/react-store": "^0.11.1",
-    "@tanstack/react-table": "^9.2.3",
-    "@tanstack/react-virtual": "^3.14.10",
-    "@tanstack/store": "^0.11.1",
+    "@tanstack/react-pacer": "^0.24.1",
+    "@tanstack/react-query": "^5.104.1",
+    "@tanstack/react-router": "1.170.41",
+    "@tanstack/react-router-ssr-query": "^1.167.3",
+    "@tanstack/react-start": "1.168.60",
+    "@tanstack/react-store": "^0.11.2",
+    "@tanstack/react-table": "^9.2.6",
+    "@tanstack/react-virtual": "^3.14.13",
+    "@tanstack/store": "^0.11.2",
     "@tiptap/core": "^3.31.3",
     "@tiptap/extension-code-block-lowlight": "^3.31.3",
     "@tiptap/extension-color": "^3.31.3",
@@ -203,6 +197,8 @@
     "isomorphic-dompurify": "^3.22.0",
     "jszip": "^3.10.2",
     "katex": "^0.18.7",
+    "leafer-editor": "2.3.0",
+    "leafer-x-easy-snap": "^1.11.0",
     "lowlight": "^3.3.0",
     "lucide": "^1.47.0",
     "lucide-react": "^1.47.0",
@@ -218,9 +214,11 @@
     "pdfjs-dist": "^6.3.289",
     "pg": "^8.22.0",
     "pinyin-pro": "^3.29.3",
+    "polygon-clipping": "^0.15.7",
     "prisma": "^7.8.0",
     "radix-ui": "^1.4.3",
     "react": "19.2.4",
+    "react-colorful": "5.8.0",
     "react-day-picker": "^10.0.1",
     "react-dom": "19.2.4",
     "react-hotkeys-hook": "^5.3.2",
@@ -249,8 +247,8 @@
     "@tanstack/devtools": "0.14.2",
     "@tanstack/devtools-ui": "0.7.1",
     "@tanstack/react-ai-devtools": "0.2.71",
-    "@tanstack/react-query-devtools": "5.102.8",
-    "@tanstack/react-router-devtools": "1.167.1",
+    "@tanstack/react-query-devtools": "5.104.1",
+    "@tanstack/react-router-devtools": "1.167.2",
     "@testing-library/jest-dom": "7.0.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
@@ -268,6 +266,7 @@
     "@vitest/coverage-v8": "5.0.0",
     "@vitest/ui": "5.0.0",
     "eslint": "^9",
+    "eslint-plugin-unused-imports": "^4.4.1",
     "jsdom": "^29.1.1",
     "msw": "2.15.0",
     "playwright": "^1.60.0",
@@ -275,11 +274,13 @@
     "shadcn": "^4.21.0",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.22.0",
-    "typescript": "^7",
-    "vite": "^8.3.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "vite": "^8.3.3",
     "vitest": "5.0.0",
     "vitest-browser-react": "2.3.0",
-    "wrangler": "^4.99.0"
+    "wrangler": "^4.99.0",
+    "@allbluecn/ui": "0.1.0"
   },
   "prisma": {
     "version": "7.8.0",

package/src/__tests__/integration/login-email-acceptance.test.ts

@@ -49,8 +49,8 @@ const EMAIL_OPEN = `${RUN}open@example.com`
 
 function run_email(r: string) { return `user_${r}` }
 
-let createdUserIds: string[] = []
-let createdCodeIds: string[] = []
+const createdUserIds: string[] = []
+const createdCodeIds: string[] = []
 
 beforeAll(async () => {
   // 清理旧同前缀数据 + 造码

package/src/__tests__/integration/login-email-p2-acceptance.test.ts

@@ -29,7 +29,6 @@ import { subscribeChangelogFn, confirmChangelogSubscriptionFn } from '@/server/s
 import { unsubscribeByEmailTokenFn } from '@/server/serverFns/email-unsubscribe'
 import { sendTemplateEmail } from '@/server/email'
 import { signUnsubscribeToken } from '@/server/email/deliverability'
-import { generateEmailToken } from '@/server/email/outbox'
 
 const RUN = `p2acc${Date.now().toString(36)}`
 const EMAIL = `${RUN}@example.com`

package/src/__tests__/knowledge/public/canonical-id.test.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { describe, it, expect } from 'vitest'
+import {
+  legalCanonicalId,
+  complianceCanonicalId,
+  dictionaryCanonicalId,
+  bookmarkCanonicalId,
+  parseGithubUrl,
+} from '@/server/knowledge/public/canonical-id'
+
+describe('canonicalId 生成', () => {
+  it('法律:优先用编号,空则用 title', () => {
+    expect(legalCanonicalId({ title: '民法典', code: '主席令第45号' })).toBe('主席令第45号')
+    expect(legalCanonicalId({ title: '民法典', code: '' })).toBe('民法典')
+  })
+
+  it('合规:优先用编号,空则用 title', () => {
+    expect(complianceCanonicalId({ title: 'GDPR', code: 'GDPR-Art.5' })).toBe('GDPR-Art.5')
+    expect(complianceCanonicalId({ title: 'GDPR', code: undefined })).toBe('GDPR')
+  })
+
+  it('词典:title@industry', () => {
+    expect(dictionaryCanonicalId('API', '通用')).toBe('API@通用')
+    expect(dictionaryCanonicalId('API', '')).toBe('API@通用')
+  })
+
+  it('网站:URL 规范化(去协议/查询/小写域名/去尾斜杠)', () => {
+    expect(bookmarkCanonicalId('https://GitHub.com/facebook/react')).toBe('github.com/facebook/react')
+    expect(bookmarkCanonicalId('http://example.com/a/?b=1')).toBe('example.com/a')
+    expect(bookmarkCanonicalId('https://example.com/')).toBe('example.com')
+  })
+})
+
+describe('parseGithubUrl', () => {
+  it('解析标准 GitHub 仓库 URL', () => {
+    expect(parseGithubUrl('https://github.com/facebook/react')).toEqual({
+      owner: 'facebook', repo: 'react',
+    })
+  })
+  it('处理 .git 后缀', () => {
+    expect(parseGithubUrl('https://github.com/vuejs/core.git')).toEqual({
+      owner: 'vuejs', repo: 'core',
+    })
+  })
+  it('非 GitHub URL 返回 null', () => {
+    expect(parseGithubUrl('https://gitlab.com/user/repo')).toBeNull()
+  })
+  it('路径不足返回 null', () => {
+    expect(parseGithubUrl('https://github.com/facebook')).toBeNull()
+  })
+})

package/src/__tests__/knowledge/public/favicon.test.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const fetchMock = vi.fn()
+vi.stubGlobal('fetch', fetchMock)
+
+import { resolveFavicon } from '@/server/knowledge/public/favicon'
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('resolveFavicon', () => {
+  it('从 HTML link 标签解析 favicon', async () => {
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      text: async () =>
+        '<html><head><link rel="icon" href="/favicon.ico"></head></html>',
+    })
+    const url = await resolveFavicon('https://example.com')
+    expect(url).toBe('https://example.com/favicon.ico')
+  })
+
+  it('解析绝对路径 favicon', async () => {
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      text: async () =>
+        '<link rel="shortcut icon" href="https://cdn.example.com/icon.png">',
+    })
+    const url = await resolveFavicon('https://example.com/page')
+    expect(url).toBe('https://cdn.example.com/icon.png')
+  })
+
+  it('无 link 标签时回退 origin/favicon.ico', async () => {
+    fetchMock.mockResolvedValueOnce({ ok: true, text: async () => '<html></html>' })
+    const url = await resolveFavicon('https://example.com')
+    expect(url).toBe('https://example.com/favicon.ico')
+  })
+
+  it('fetch 失败回退 Google s2 服务', async () => {
+    fetchMock.mockRejectedValueOnce(new Error('timeout'))
+    const url = await resolveFavicon('https://example.com')
+    expect(url).toBe('https://www.google.com/s2/favicons?domain=example.com&sz=64')
+  })
+
+  // SEC-05：favicon 同步曾无任何 SSRF 防护直 fetch 用户 URL（可探测云元数据/内网）。
+  // 守卫拒绝时不发任何请求，直接走 Google s2 兜底（域名参数无害化）。
+  it.each([
+    ['云元数据 169.254.x', 'http://169.254.169.254/latest/meta-data/'],
+    ['回环 127.x', 'http://127.0.0.1:8080/admin'],
+    ['A 类内网 10.x', 'http://10.0.0.8/icon'],
+    ['IPv4-mapped IPv6 回环', 'http://[::ffff:127.0.0.1]/x'],
+    ['mDNS 域 .local', 'http://nas.local/favicon'],
+    ['十进制整数 IP 混淆', 'http://2130706433/favicon'],
+  ])('SSRF：%s 被守卫拒绝，不发请求直接走 Google s2 兜底', async (_name, raw) => {
+    const url = await resolveFavicon(raw)
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(url).toContain('https://www.google.com/s2/favicons?domain=')
+  })
+
+  it('公网 URL fetch 以 redirect:error 发起（防 302 跳私网）', async () => {
+    fetchMock.mockResolvedValueOnce({ ok: true, text: async () => '<html></html>' })
+    await resolveFavicon('https://example.com')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][1]).toMatchObject({ redirect: 'error' })
+  })
+})