@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/tiptap/notion-like/notion-like-editor-header.tsx

@@ -15,9 +15,8 @@
 // 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 { useContext, useEffect, useState } from "react"
+import { useContext } from "react"
 import { EditorContext } from "@tiptap/react"
-import { FolderOpen } from "lucide-react"
 
 // --- Tiptap UI ---
 import { UndoRedoButton } from "../ui/undo-redo-button/index.tsx"
@@ -26,27 +25,11 @@ import { UndoRedoButton } from "../ui/undo-redo-button/index.tsx"
 import { Spacer } from "../ui-primitive/spacer/index.tsx"
 import { ButtonGroup } from "../ui-primitive/button-group/index.tsx"
 
-// --- Desktop integration ---
-import { isDesktop } from "@/lib/desktop-detect"
-import { insertLocalFile } from "../extensions/local-file/insert-local-file.ts"
-import { Button } from "@/components/ui/button"
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger,
-} from "@/components/ui/tooltip"
-
 // --- Styles ---
 import "./notion-like-editor-header.scss"
-import { m } from "@/paraglide/messages.js";
 
 export function NotionEditorHeader() {
   const { editor } = useContext(EditorContext)!
-  const [showLocalFileBtn, setShowLocalFileBtn] = useState(false)
-
-  useEffect(() => {
-    setShowLocalFileBtn(isDesktop())
-  }, [])
 
   return (
     <header className="notion-like-editor-header">
@@ -56,19 +39,6 @@ export function NotionEditorHeader() {
           <UndoRedoButton action="undo" />
           <UndoRedoButton action="redo" />
         </ButtonGroup>
-
-        {showLocalFileBtn && editor && (
-          <ButtonGroup>
-            <Tooltip>
-              <TooltipTrigger render={<Button variant="ghost"
-                  size="sm"
-                  onClick={() => insertLocalFile(editor)} />}>
-                  <FolderOpen className="size-4" />
-                </TooltipTrigger>
-              <TooltipContent> {m['editor_insert-local-file']() } </TooltipContent>
-            </Tooltip>
-          </ButtonGroup>
-        )}
       </div>
     </header>
   )

package/src/components/tiptap/notion-like/notion-like-editor.tsx

@@ -20,6 +20,7 @@ import type { DocumentSuggestion, MentionUserSource, AiModelState } from "./use-
 import { useCallback, useContext, useEffect, useMemo, useRef, useState, createContext } from "react"
 import { useDebouncedCallback, EDITOR_CHANGE_DEBOUNCE_MS } from "@/lib/pacer"
 import { EditorContent, EditorContext, useEditor, type Editor } from "@tiptap/react"
+import type { Transaction } from "@tiptap/pm/state"
 import { createPortal } from "react-dom"
 
 // --- Extensions（装配单一来源，见 editor-extensions.ts 头注） ---
@@ -85,6 +86,15 @@ export interface DocumentPreviewData {
 export interface NotionDocEditorProps {
   content?: { html: string; markdown: string } | { text: string } | string
   onChange?: (content: { html: string; markdown: string }) => void
+  /**
+   * 用户编辑同步信号（任务 2 审查修复①）：onUpdate 同步触发，先于
+   * EDITOR_CHANGE_DEBOUNCE_MS(500ms) 的 onChange——消费方以此在防抖窗口内
+   * 维持「有未落库编辑」判定，堵导航拦截的 dirty 盲区。仅用户编辑触发：
+   * addToHistory=false 的事务（y-sync 远端同步等）与 UniqueID 插件追加的
+   * 初始化 ID 归一化（__uniqueIDTransaction，审查修复② 的来源）不触发；
+   * undo/redo 走 historyKey meta 不受影响。
+   */
+  onDirtySignal?: () => void
   placeholder?: string
   readOnly?: boolean
   showTocSidebar?: boolean
@@ -257,6 +267,7 @@ export function EditorContentArea({ hideDragHandle, hideInsertButton, hideAi }:
 function NotionDocEditorContent({
   content,
   onChange,
+  onDirtySignal,
   placeholder,
   readOnly = false,
   showTocSidebar = false,
@@ -279,6 +290,9 @@ function NotionDocEditorContent({
   const onChangeRef = useRef(onChange)
   onChangeRef.current = onChange
 
+  const onDirtySignalRef = useRef(onDirtySignal)
+  onDirtySignalRef.current = onDirtySignal
+
   const getInitialContent = useCallback(
     () => resolveContentHtml(content),
     [content]
@@ -312,8 +326,23 @@ function NotionDocEditorContent({
       onTocContent: setTocContent,
       collab,
     }),
-    onUpdate: ({ editor: ed }: { editor: Editor }) => {
+    onUpdate: ({ editor: ed, transaction, appendedTransactions }: { editor: Editor; transaction: Transaction; appendedTransactions?: Transaction[] }) => {
       if (!onChangeRef.current) return
+      // 同步 dirty 信号：先于 500ms onChange 防抖。仅用户编辑触发——排除两
+      // 类程序性 docChanged 事务：addToHistory=false（y-sync 远端同步等）与
+      // UniqueID 插件追加的 ID 归一化（__uniqueIDTransaction，挂载初始化即
+      // 审查修复② 的来源）。Enter 建新段时用户事务与 uniqueID 追加并存，
+      // 由「基础事务 docChanged」兜底不误吞。
+      const baseIsUserEdit =
+        transaction.docChanged &&
+        transaction.getMeta("addToHistory") !== false &&
+        transaction.getMeta("__uniqueIDTransaction") !== true
+      const appendedUserEdit = appendedTransactions?.some(
+        (t) => t.docChanged && t.getMeta("__uniqueIDTransaction") !== true
+      )
+      if (baseIsUserEdit || appendedUserEdit) {
+        onDirtySignalRef.current?.()
+      }
       debouncedSave(ed)
     },
   }), [readOnly, editorClassName, getInitialContent, placeholder, setTocContent, collab])
@@ -396,6 +425,7 @@ export function NotionDocEditor({
   content,
   placeholder,
   onChange,
+  onDirtySignal,
   readOnly = false,
   showTocSidebar = false,
   tocSidebarClassName,
@@ -419,6 +449,7 @@ export function NotionDocEditor({
         content={content}
         placeholder={resolvedPlaceholder}
         onChange={onChange}
+        onDirtySignal={onDirtySignal}
         readOnly={readOnly}
         showTocSidebar={showTocSidebar}
         tocSidebarClassName={tocSidebarClassName}

package/src/components/workspace/__tests__/dialogs/create-workspace-dialog.test.tsx

@@ -27,34 +27,8 @@ vi.mock("@tanstack/react-router", () => ({
   Link: ({ children }: any) => <a>{children}</a>,
 }));
 
-vi.mock("@tanstack/react-form", () => {
-  const makeField = (value: string) => ({
-    value,
-    handleChange: vi.fn(),
-    handleBlur: vi.fn(),
-    meta: { errors: [] },
-  });
-  return {
-    useForm: () => {
-      const fields = {
-        name: makeField(""),
-        icon: makeField("folder"),
-        description: makeField(""),
-      };
-      return {
-        handleSubmit: (e: any) => e.preventDefault(),
-        setFieldValue: () => {},
-        state: { values: { name: "", icon: "folder", description: "" } },
-        fields,
-        Field: ({ name, children }: { name: "name" | "icon" | "description"; children: unknown }) =>
-          typeof children === "function"
-            ? (children as (field: unknown) => unknown)(fields[name])
-            : null,
-      };
-    },
-  };
-});
-
+// 表单走真实 create-app-form 工厂（@tanstack/react-form 原生跑在 jsdom），
+// 不再 mock useForm——顺带覆盖 field.AppFieldError 命名空间消费路径。
 describe("CreateWorkspaceDialog", () => {
   it("打开时渲染标题", () => {
     render(<CreateWorkspaceDialog open={true} onOpenChange={() => {}} />);

package/src/components/workspace/__tests__/dialogs/edit-workspace-dialog.test.tsx

@@ -26,34 +26,8 @@ vi.mock("@tanstack/react-router", () => ({
   useRouter: () => ({ navigate: vi.fn() }),
 }));
 
-vi.mock("@tanstack/react-form", () => {
-  const makeField = (value: string) => ({
-    value,
-    handleChange: vi.fn(),
-    handleBlur: vi.fn(),
-    meta: { errors: [] },
-  });
-  return {
-    useForm: () => {
-      const fields = {
-        name: makeField("测试"),
-        icon: makeField("folder"),
-        description: makeField(""),
-      };
-      return {
-        handleSubmit: (e: any) => e.preventDefault(),
-        setFieldValue: () => {},
-        state: { values: { name: "测试", icon: "folder", description: "" } },
-        fields,
-        Field: ({ name, children }: { name: "name" | "icon" | "description"; children: unknown }) =>
-          typeof children === "function"
-            ? (children as (field: unknown) => unknown)(fields[name])
-            : null,
-      };
-    },
-  };
-});
-
+// 表单走真实 create-app-form 工厂（@tanstack/react-form 原生跑在 jsdom），
+// 不再 mock useForm——顺带覆盖 field.AppFieldError 命名空间消费路径。
 describe("EditWorkspaceDialog", () => {
   it("打开时渲染标题", () => {
     render(

package/src/components/workspace/dialogs/create-workspace-dialog.tsx

@@ -16,7 +16,6 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useState } from "react";
-import { useForm } from "@tanstack/react-form";
 import { Link, useRouter } from "@tanstack/react-router";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
@@ -28,7 +27,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/components/ui/dialog";
-import { AppFieldError } from "@/components/forms/app-field-error";
+import { useAppForm } from "@/components/forms/create-app-form";
 import { LucideIconPicker } from "@/components/shared-kit/icons/lucide-icon-picker";
 import { createWorkspaceFn } from "@/server/serverFns/workspace";
 import { workspaceFormSchema } from "../schemas/create-workspace";
@@ -48,53 +47,49 @@ export function CreateWorkspaceDialog({
   onSuccess,
 }: CreateWorkspaceDialogProps) {
   const router = useRouter();
-  const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
   const [showUpgrade, setShowUpgrade] = useState(false);
 
-  const form = useForm({
+  const form = useAppForm({
     defaultValues: {
       name: "",
       description: "",
       icon: "",
     },
     validators: [{ run: workspaceFormSchema, triggers: ['change'] }],
-  });
-
-  const handleSubmit = async () => {
-    if (!form.state.values.name.trim()) {
-      setError(m.workspace_createWorkspace_nameRequired());
-      return;
-    }
-    setLoading(true);
-    setError("");
-    try {
-      const workspace = await createWorkspaceFn({
-        data: {
-          icon: form.state.values.icon,
-          name: form.state.values.name.trim(),
-          description: form.state.values.description.trim(),
-        },
-      });
-      onOpenChange(false);
-      onSuccess?.();
-      emitEvent(AppEvents.workspace.created);
-      await router.navigate({ to: "/workspaces/$workspaceId", params: { workspaceId: workspace.id } });
-    } catch (err) {
-      // serverFn RPC 错误经序列化只保留 message（name/resource 属性丢失），
-      // ResourceLimitError 的 message 格式为 "Resource <key> limit reached (u/l)"
-      const isWorkspaceLimit =
-        err instanceof Error &&
-        err.message.startsWith("Resource workspaces limit reached");
-      if (isWorkspaceLimit) {
-        setShowUpgrade(true);
+    onSubmit: async ({ value }) => {
+      // schema min(1) 放行纯空白串（"   "），保留原提交前守卫兜底
+      if (!value.name.trim()) {
+        setError(m.workspace_createWorkspace_nameRequired());
         return;
       }
-      setError(errorMessage(err, m.workspace_createWorkspace_createFailed()));
-    } finally {
-      setLoading(false);
-    }
-  };
+      setError("");
+      try {
+        const workspace = await createWorkspaceFn({
+          data: {
+            icon: value.icon,
+            name: value.name.trim(),
+            description: value.description.trim(),
+          },
+        });
+        onOpenChange(false);
+        onSuccess?.();
+        emitEvent(AppEvents.workspace.created);
+        await router.navigate({ to: "/workspaces/$workspaceId", params: { workspaceId: workspace.id } });
+      } catch (err) {
+        // serverFn RPC 错误经序列化只保留 message（name/resource 属性丢失），
+        // ResourceLimitError 的 message 格式为 "Resource <key> limit reached (u/l)"
+        const isWorkspaceLimit =
+          err instanceof Error &&
+          err.message.startsWith("Resource workspaces limit reached");
+        if (isWorkspaceLimit) {
+          setShowUpgrade(true);
+          return;
+        }
+        setError(errorMessage(err, m.workspace_createWorkspace_createFailed()));
+      }
+    },
+  });
 
   const handleOpenChange = (newOpen: boolean) => {
     if (newOpen) {
@@ -145,7 +140,7 @@ export function CreateWorkspaceDialog({
                       maxLength={100}
                       className="h-10 w-full"
                     />
-                    <AppFieldError field={field} />
+                    <field.AppFieldError />
                   </div>
                 )} />
               </div>
@@ -160,7 +155,7 @@ export function CreateWorkspaceDialog({
                     maxLength={500}
                     className="flex-1 min-h-0 resize-none border-0 shadow-none bg-transparent px-3 py-2 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-0 focus-visible:border-0"
                   />
-                  <AppFieldError field={field} />
+                  <field.AppFieldError />
                 </div>
               )} />
 
@@ -173,9 +168,16 @@ export function CreateWorkspaceDialog({
           <Button variant="outline" onClick={() => handleOpenChange(false)}>
             {m.workspace_createWorkspace_cancel()}
           </Button>
-          <Button onClick={handleSubmit} disabled={loading}>
-            {loading ? m.workspace_createWorkspace_creating() : m.workspace_createWorkspace_create()}
-          </Button>
+          <form.Subscribe selector={(state) => state.isSubmitting}>
+            {(isSubmitting) => (
+              <Button
+                onClick={() => form.handleSubmit()}
+                disabled={isSubmitting}
+              >
+                {isSubmitting ? m.workspace_createWorkspace_creating() : m.workspace_createWorkspace_create()}
+              </Button>
+            )}
+          </form.Subscribe>
         </DialogFooter>
       </DialogContent>
     </Dialog>

package/src/components/workspace/dialogs/edit-workspace-dialog.tsx

@@ -16,7 +16,6 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useState } from "react";
-import { useForm } from "@tanstack/react-form";
 import { useRouter } from "@tanstack/react-router";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
@@ -28,7 +27,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/components/ui/dialog";
-import { AppFieldError } from "@/components/forms/app-field-error";
+import { useAppForm } from "@/components/forms/create-app-form";
 import { LucideIconPicker } from "@/components/shared-kit/icons/lucide-icon-picker";
 import { updateWorkspaceFn } from "@/server/serverFns/workspace";
 import { workspaceFormSchema } from "../schemas/create-workspace";
@@ -50,45 +49,41 @@ export function EditWorkspaceDialog({
   onSuccess,
 }: EditWorkspaceDialogProps) {
   const router = useRouter();
-  const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
 
-  const form = useForm({
+  const form = useAppForm({
     defaultValues: {
       name: workspace.name,
       description: workspace.description ?? "",
       icon: workspace.icon,
     },
     validators: [{ run: workspaceFormSchema, triggers: ['change'] }],
+    onSubmit: async ({ value }) => {
+      // schema min(1) 放行纯空白串（"   "），保留原提交前守卫兜底
+      if (!value.name.trim()) {
+        setError(m.workspace_createWorkspace_nameRequired());
+        return;
+      }
+      setError("");
+      try {
+        await updateWorkspaceFn({
+          data: {
+            workspaceId: workspace.id,
+            name: value.name.trim(),
+            icon: value.icon,
+            description: value.description.trim() || null,
+          },
+        });
+        onOpenChange(false);
+        onSuccess?.();
+        emitEvent(AppEvents.workspace.updated);
+        await router.invalidate();
+      } catch (err) {
+        setError(errorMessage(err, m.workspace_createWorkspace_createFailed()));
+      }
+    },
   });
 
-  const handleSubmit = async () => {
-    if (!form.state.values.name.trim()) {
-      setError(m.workspace_createWorkspace_nameRequired());
-      return;
-    }
-    setLoading(true);
-    setError("");
-    try {
-      await updateWorkspaceFn({
-        data: {
-          workspaceId: workspace.id,
-          name: form.state.values.name.trim(),
-          icon: form.state.values.icon,
-          description: form.state.values.description.trim() || null,
-        },
-      });
-      onOpenChange(false);
-      onSuccess?.();
-      emitEvent(AppEvents.workspace.updated);
-      await router.invalidate();
-    } catch (err) {
-      setError(errorMessage(err, m.workspace_createWorkspace_createFailed()));
-    } finally {
-      setLoading(false);
-    }
-  };
-
   const handleOpenChange = (newOpen: boolean) => {
     if (newOpen) {
       form.setFieldValue("name", workspace.name);
@@ -125,7 +120,7 @@ export function EditWorkspaceDialog({
                   maxLength={100}
                   className="h-10 w-full"
                 />
-                <AppFieldError field={field} />
+                <field.AppFieldError />
               </div>
             )} />
           </div>
@@ -140,7 +135,7 @@ export function EditWorkspaceDialog({
                 maxLength={500}
                 className="flex-1 min-h-0 resize-none border-0 shadow-none bg-transparent px-3 py-2 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-0 focus-visible:border-0"
               />
-              <AppFieldError field={field} />
+              <field.AppFieldError />
             </div>
           )} />
 
@@ -151,9 +146,16 @@ export function EditWorkspaceDialog({
           <Button variant="outline" onClick={() => handleOpenChange(false)}>
             {m.workspace_createWorkspace_cancel()}
           </Button>
-          <Button onClick={handleSubmit} disabled={loading}>
-            {loading ? m.workspace_createWorkspace_creating() : m.common_button_save()}
-          </Button>
+          <form.Subscribe selector={(state) => state.isSubmitting}>
+            {(isSubmitting) => (
+              <Button
+                onClick={() => form.handleSubmit()}
+                disabled={isSubmitting}
+              >
+                {isSubmitting ? m.workspace_createWorkspace_creating() : m.common_button_save()}
+              </Button>
+            )}
+          </form.Subscribe>
         </DialogFooter>
       </DialogContent>
     </Dialog>

package/src/design-engine/engine/engine-decor.ts

@@ -107,6 +107,8 @@ export class DecorEngine extends LeaferEngineBase {
       this.measurePointer = { clientX: e.clientX, clientY: e.clientY }
       this.measureRefresh()
     }
+    // 豁免热键收编（audit 2026-10-31）：engine 内部标注量测键状态机（非 React
+    // 组件层、keyup/blur 联动清位），useHotkey 表达不了引擎生命周期挂载
     window.addEventListener("keydown", onKeyDown)
     window.addEventListener("keyup", onKeyUp)
     window.addEventListener("blur", onBlur)

package/src/design-engine/engine/engine-path.ts

@@ -572,6 +572,8 @@ export class PathEditEngine extends DocEngine {
     host.addEventListener("pointerup", onPointerUp)
     host.addEventListener("click", swallow, true)
     host.addEventListener("dblclick", onDblClick, true)
+    // 豁免热键收编（audit 2026-10-31）：路径编辑锚点单键（1-4）在 window
+    // 捕获相、仅路径编辑态生效，与 React 层 useHotkey 的冒泡相注册时序不兼容
     window.addEventListener("keydown", onKey, true)
     this.pathEditInteractionIds = [
       () => host.removeEventListener("pointerdown", onPointerDown, true),

package/src/hooks/__tests__/use-unsaved-guard.test.tsx

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * useUnsavedGuard（useBlocker 统一未保存拦截，TanStack 优化计划任务 2）：
+ *
+ * ① dirty 态 SPA 导航被拦 → 渲染 AlertDialog（shadcn，非 window.confirm），
+ *    shouldBlockFn 随 dirty 翻转（过度拦截防线：仅 dirty 时 block）；
+ * ② 「离开」先执行 onSaveAndLeave（flush 保存）再 proceed（顺序断言）；
+ * ③ 「留下」调 reset，不触发 proceed / onSaveAndLeave；
+ * ④ clean 态零弹窗、shouldBlockFn=false（零拦截）；
+ * ⑤ beforeunload：dirty preventDefault（enableBeforeUnload 生效）、clean 放行；
+ * ⑥ SSR 安全：服务端渲染（effects 不跑）不炸且零弹窗输出。
+ *
+ * useBlocker mock 按 @tanstack/react-router 1.170.46 的 .d.ts 实际形态：
+ * 默认形态返回 void，withResolver: true 才返回 BlockerResolver
+ * （status: 'blocked' | 'idle' + proceed/reset）。beforeunload 语义复刻
+ * @tanstack/history 的 onBeforeUnload：enableBeforeUnload 为 boolean 时恒
+ * preventDefault，为 function 时在卸载时调用决定。
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react'
+import { renderToString } from 'react-dom/server'
+import { useUnsavedGuard } from '@/hooks/use-unsaved-guard'
+import { m } from '@/paraglide/messages.js'
+
+type BlockerResolverLike = {
+  status: 'blocked' | 'idle'
+  current: undefined
+  next: undefined
+  action: undefined
+  proceed: (() => void) | undefined
+  reset: (() => void) | undefined
+}
+
+const blockerState = vi.hoisted(() => ({
+  resolver: {
+    status: 'idle',
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  } as {
+    status: 'blocked' | 'idle'
+    current: undefined
+    next: undefined
+    action: undefined
+    proceed: (() => void) | undefined
+    reset: (() => void) | undefined
+  },
+  capturedOpts: null as {
+    shouldBlockFn: (args: unknown) => boolean | Promise<boolean>
+    enableBeforeUnload: boolean | (() => boolean)
+    withResolver?: boolean
+    disabled?: boolean
+  } | null,
+}))
+
+vi.mock('@tanstack/react-router', async () => {
+  const React = await import('react')
+  return {
+    useBlocker: (opts: NonNullable<typeof blockerState.capturedOpts>) => {
+      blockerState.capturedOpts = opts
+      // 复刻真实 useBlocker：挂载期注册 history.block 的 beforeunload 面
+      // （blockerFn 的 SPA 拦截部分由 resolver 状态承载，测试直接驱动）
+      React.useEffect(() => {
+        if (opts.disabled) return
+        const handler = (e: Event) => {
+          const enable =
+            typeof opts.enableBeforeUnload === 'function'
+              ? opts.enableBeforeUnload()
+              : (opts.enableBeforeUnload ?? true)
+          if (enable) e.preventDefault()
+        }
+        window.addEventListener('beforeunload', handler)
+        return () => window.removeEventListener('beforeunload', handler)
+      }, [opts.shouldBlockFn, opts.enableBeforeUnload, opts.disabled])
+      return blockerState.resolver
+    },
+  }
+})
+
+function idleResolver(): BlockerResolverLike {
+  return { status: 'idle', current: undefined, next: undefined, action: undefined, proceed: undefined, reset: undefined }
+}
+
+function blockedResolver(over: { proceed: () => void; reset: () => void }): BlockerResolverLike {
+  return { status: 'blocked', current: undefined, next: undefined, action: undefined, proceed: over.proceed, reset: over.reset }
+}
+
+function HookProbe(props: { isDirty: () => boolean; onSaveAndLeave?: () => Promise<void> | void }) {
+  const { dialog } = useUnsavedGuard(props)
+  return <>{dialog}</>
+}
+
+const SHOULD_BLOCK_ARGS = { action: 'PUSH', current: {}, next: {} }
+
+beforeEach(() => {
+  blockerState.resolver = idleResolver()
+  blockerState.capturedOpts = null
+})
+
+describe('useUnsavedGuard（useBlocker 统一未保存拦截）', () => {
+  it('① dirty 态渲染 AlertDialog（title/body/离开/留下），shouldBlockFn 随 dirty 翻转', () => {
+    blockerState.resolver = blockedResolver({ proceed: vi.fn(), reset: vi.fn() })
+    render(<HookProbe isDirty={() => true} />)
+
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+    expect(screen.getByText(m.common_unsaved_title())).toBeInTheDocument()
+    expect(screen.getByText(m.common_unsaved_body())).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: m.common_unsaved_leave() })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: m.common_unsaved_stay() })).toBeInTheDocument()
+    // 过度拦截防线：dirty 时 block（透传给 useBlocker 的 shouldBlockFn 生效）
+    expect(blockerState.capturedOpts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(true)
+    expect(blockerState.capturedOpts?.withResolver).toBe(true)
+  })
+
+  it('② 点「离开」先执行 onSaveAndLeave（flush 保存）再 proceed', async () => {
+    const order: string[] = []
+    blockerState.resolver = blockedResolver({
+      proceed: () => order.push('proceed'),
+      reset: vi.fn(),
+    })
+    render(
+      <HookProbe
+        isDirty={() => true}
+        onSaveAndLeave={async () => {
+          order.push('save')
+        }}
+      />,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: m.common_unsaved_leave() }))
+    await waitFor(() => expect(order).toContain('proceed'))
+    expect(order).toEqual(['save', 'proceed'])
+  })
+
+  it('③ 点「留下」调 reset，不触发 proceed / onSaveAndLeave', async () => {
+    const proceed = vi.fn()
+    const reset = vi.fn()
+    const onSaveAndLeave = vi.fn()
+    blockerState.resolver = blockedResolver({ proceed, reset })
+    render(<HookProbe isDirty={() => true} onSaveAndLeave={onSaveAndLeave} />)
+
+    fireEvent.click(screen.getByRole('button', { name: m.common_unsaved_stay() }))
+    await waitFor(() => expect(reset).toHaveBeenCalled())
+    expect(proceed).not.toHaveBeenCalled()
+    expect(onSaveAndLeave).not.toHaveBeenCalled()
+  })
+
+  it('④ clean 态零弹窗、shouldBlockFn=false（零拦截）', () => {
+    render(<HookProbe isDirty={() => false} onSaveAndLeave={vi.fn()} />)
+
+    expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument()
+    expect(blockerState.capturedOpts?.shouldBlockFn(SHOULD_BLOCK_ARGS)).toBe(false)
+  })
+
+  it('⑤ beforeunload：dirty preventDefault（enableBeforeUnload 函数形态生效）、clean 放行', () => {
+    const dirty = render(<HookProbe isDirty={() => true} />)
+    const dirtyEvent = new Event('beforeunload', { cancelable: true })
+    act(() => {
+      window.dispatchEvent(dirtyEvent)
+    })
+    expect(dirtyEvent.defaultPrevented).toBe(true)
+    dirty.unmount()
+
+    render(<HookProbe isDirty={() => false} />)
+    const cleanEvent = new Event('beforeunload', { cancelable: true })
+    act(() => {
+      window.dispatchEvent(cleanEvent)
+    })
+    expect(cleanEvent.defaultPrevented).toBe(false)
+  })
+
+  it('⑥ SSR 安全：renderToString（effects 不跑）不炸且零弹窗输出', () => {
+    const html = renderToString(<HookProbe isDirty={() => true} onSaveAndLeave={vi.fn()} />)
+    expect(html).toBe('')
+  })
+})