@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/design/editor/layout/__tests__/persistence-restore.test.tsx

@@ -75,7 +75,22 @@ vi.mock("@/server/serverFns/design/pages", () => ({
 vi.mock("@/server/serverFns/design/designs", () => ({
   updateDesignFn: vi.fn(),
 }));
-vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {} }));
+vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {}, useAppHotkeys: () => appHotkeys }));
+
+// DesignEditorLayout 挂载 use-unsaved-guard（任务 2）：无 RouterProvider 的
+// 单测环境把 useBlocker 替换为 idle resolver（真实 blocker 注册属 router
+// 集成行为，见 hooks/__tests__/use-unsaved-guard.test.tsx）
+vi.mock("@tanstack/react-router", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: () => ({
+    status: "idle" as const,
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  }),
+}));
 vi.mock("@/components/design/editor/versions/page-version-panel", () => ({
   PageVersionPanel: () => null,
 }));
@@ -88,6 +103,7 @@ vi.mock("@/components/design/editor/layout/design-doc-panel", () => ({
 
 import { DesignRightSidebar } from "../design-right-sidebar";
 import { DesignEditorLayout } from "../design-editor-layout";
+import { appHotkeys } from "@/lib/hotkeys/registry";
 import type { Design } from "@allbluecn/kernel";
 
 const designFixture = {

package/src/components/design/editor/layout/__tests__/ssr-localstorage-smoke.test.tsx

@@ -72,10 +72,26 @@ vi.mock("@/server/serverFns/design/pages", () => ({
 vi.mock("@/server/serverFns/design/designs", () => ({
   updateDesignFn: vi.fn(),
 }));
-vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {} }));
+vi.mock("@tanstack/react-hotkeys", () => ({ useHotkey: () => {}, useAppHotkeys: () => appHotkeys }));
+
+// DesignEditorLayout 挂载 use-unsaved-guard（任务 2）：本冒烟测试无
+// RouterProvider（node + renderToString），把 useBlocker 替换为 idle
+// resolver——真实 blocker 注册属 router 集成行为，SSR 渲染期本就零 window 访问
+vi.mock("@tanstack/react-router", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useBlocker: () => ({
+    status: "idle" as const,
+    current: undefined,
+    next: undefined,
+    action: undefined,
+    proceed: undefined,
+    reset: undefined,
+  }),
+}));
 
 import { DesignRightSidebar } from "../design-right-sidebar";
 import { DesignEditorLayout } from "../design-editor-layout";
+import { appHotkeys } from "@/lib/hotkeys/registry";
 import { useTrackColumns } from "@/components/harness/workbench/use-track-columns";
 
 const designFixture = {

package/src/components/design/editor/layout/design-editor-layout.tsx

@@ -21,7 +21,7 @@ import { emitEvent, AppEvents } from "@/lib/events";
 import { DesignLeftSidebar } from "./design-left-sidebar";
 import { DesignRightSidebar } from "./design-right-sidebar";
 import { DesignNavigation } from "./design-navigation";
-import { useHotkey } from "@tanstack/react-hotkeys";
+import { useAppHotkeys, useHotkey } from "@tanstack/react-hotkeys";
 import type { Editor } from "@tiptap/react";
 import { AnnotationOverlay } from "@/components/design/editor/annotation/overlay/annotation-overlay";
 import { ElementContext } from "./element-context";
@@ -64,6 +64,7 @@ import {
 import type { PrototypeScene } from "@/server/serverFns/design/ai/generate-prototype";
 import { useDebouncer } from "@/lib/pacer";
 import { isCollabEnabled } from "@/lib/collab/env";
+import { useUnsavedGuard } from "@/hooks/use-unsaved-guard";
 import { useDesignLeftPanelPreference } from "./hooks/use-design-left-panel-preference";
 import { useDesignPageLoad } from "./hooks/use-design-page-load";
 import { usePageVersionEvents } from "./hooks/use-page-version-events";
@@ -569,6 +570,13 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
     collab: collabEnabled,
   });
 
+  // 未保存拦截（任务 2）：SPA 导航 dirty 弹 AlertDialog，刷新/关闭走
+  // enableBeforeUnload 原生警告。协同态豁免：collab 下双通道保存让位（T29）
+  // dirty 恒真不代表未落库（Y.Doc 是权威副本），拦截反成误报
+  const unsavedGuard = useUnsavedGuard({
+    isDirty: () => !collabEnabled && (loaded.canvasDirty || loaded.docDirty),
+  });
+
   const switchPage = useCallback(async (pageId: string) => {
     if (loaded.canvasDirty && loaded.activePageId) await autoSave.saveCanvasRef.current();
     if (loaded.docDirty && loaded.activePageId) await autoSave.saveDoc();
@@ -588,7 +596,9 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
     }
   }, [prd.id]);
 
-  useHotkey("Mod+S", autoSave.saveAll);
+  // 声明即绑定：save 条目单一来源（lib/hotkeys/registry.ts），禁止手写 chord
+  const hk = useAppHotkeys();
+  useHotkey(hk["save"], autoSave.saveAll);
 
   const [aiModel, setAiModel] = useState("");
 
@@ -669,6 +679,7 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
             </CanvasProvider>
           </div>
         </div>
+        {unsavedGuard.dialog}
       </div>
     </ElementContext.Provider>
   );

package/src/components/design/editor/layout/hooks/use-design-auto-save.ts

@@ -182,30 +182,14 @@ export function useDesignAutoSave({
     await Promise.all([saveCanvasRef.current("manual"), saveDoc("manual")]);
   }, [canvasDebouncer, saveDoc]);
 
-  const docDirtyRef = useRef(docDirty);
-  docDirtyRef.current = docDirty;
-  const canvasDirtyRef = useRef(canvasDirty);
-  canvasDirtyRef.current = canvasDirty;
+  // 未保存拦截（任务 2）：手写 beforeunload preventDefault 已迁
+  // use-unsaved-guard（useBlocker + enableBeforeUnload 函数形态，挂载于
+  // design-editor-layout），SPA 导航与刷新统一由该 hook 拦截
 
   useEffect(() => {
     if (activePageId) noPageToastShownRef.current = false;
   }, [activePageId]);
 
-  useEffect(() => {
-    const handleBeforeUnload = (e: BeforeUnloadEvent) => {
-      canvasDebouncer.cancel();
-      docDebouncer.cancel();
-      // 关闭/刷新前若有未落库编辑（防抖窗口内的内容已被 cancel 丢弃），
-      // 触发浏览器原生「未保存更改」确认，给用户阻止误关的机会
-      if (canvasDirtyRef.current || docDirtyRef.current) {
-        e.preventDefault();
-        e.returnValue = "";
-      }
-    };
-    window.addEventListener("beforeunload", handleBeforeUnload);
-    return () => window.removeEventListener("beforeunload", handleBeforeUnload);
-  }, [canvasDebouncer, docDebouncer]);
-
   const handleDocContentChange = useCallback((content: DocContent) => {
     setDocContent(content);
     setDocDirty(true);

package/src/components/devtools/devtools-panel.tsx

@@ -0,0 +1,56 @@
+// 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 { Suspense, lazy, useEffect, useState } from "react";
+
+// DEV 门控放在模块顶层三元上：生产构建时 import.meta.env.DEV 被静态替换为
+// false，动态 import 落入死分支被 tree-shake，devtools chunk 不进生产产物。
+const ReactQueryDevtools = import.meta.env.DEV
+  ? lazy(() =>
+      import("@tanstack/react-query-devtools").then((m) => ({
+        default: m.ReactQueryDevtools,
+      })),
+    )
+  : null;
+
+const TanStackRouterDevtools = import.meta.env.DEV
+  ? lazy(() =>
+      import("@tanstack/react-router-devtools").then((m) => ({
+        default: m.TanStackRouterDevtools,
+      })),
+    )
+  : null;
+
+export function DevtoolsPanel() {
+  // SSR 安全：dev 模式下 SSR 渲染期（mounted=false）返回 null，挂载后再
+  // 加载面板——lazy 组件只在客户端渲染，hydration 前后零差异。
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!import.meta.env.DEV || !mounted) return null;
+
+  return (
+    <Suspense fallback={null}>
+      {ReactQueryDevtools ? <ReactQueryDevtools initialIsOpen={false} /> : null}
+      {TanStackRouterDevtools ? (
+        <TanStackRouterDevtools initialIsOpen={false} />
+      ) : null}
+    </Suspense>
+  );
+}

package/src/components/forms/__tests__/create-app-form.test.tsx

@@ -0,0 +1,131 @@
+// 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 } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { z } from "zod";
+import { useAppForm } from "../create-app-form";
+
+const schema = z.object({
+  name: z.string().min(2, "名称至少2个字"),
+});
+
+type SubmitValues = { name: string };
+
+type SubmitFn = (value: SubmitValues) => Promise<void> | void;
+
+function Harness({ onSubmit, initialValue = "" }: {
+  onSubmit: SubmitFn;
+  initialValue?: string;
+}) {
+  const form = useAppForm({
+    defaultValues: { name: initialValue },
+    validators: [{ run: schema, triggers: ["change"] }],
+    onSubmit: ({ value }) => onSubmit(value),
+  });
+  return (
+    <form.AppForm>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          form.handleSubmit();
+        }}
+      >
+        <form.AppField name="name" label="名称" />
+        <button type="submit">提交</button>
+      </form>
+    </form.AppForm>
+  );
+}
+
+function SubmitHarness({ onSubmit }: { onSubmit: SubmitFn }) {
+  const form = useAppForm({
+    defaultValues: { name: "有效名称" },
+    validators: [{ run: schema, triggers: ["change"] }],
+    onSubmit: ({ value }) => onSubmit(value),
+  });
+  return (
+    <form.AppForm>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          form.handleSubmit();
+        }}
+      >
+        <form.AppField name="name" />
+        <form.AppSubmit>提交</form.AppSubmit>
+      </form>
+    </form.AppForm>
+  );
+}
+
+describe("create-app-form 工厂", () => {
+  it("useAppForm 渲染 form.AppField 默认输入与 AppSubmit 按钮", () => {
+    render(<SubmitHarness onSubmit={vi.fn()} />);
+    expect(screen.getByRole("textbox")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "提交" })).toBeInTheDocument();
+  });
+
+  it("校验错误经 AppFieldError 在 touch 后显示（isTouched 守卫）", async () => {
+    render(<Harness onSubmit={vi.fn()} />);
+    const input = screen.getByRole("textbox");
+    fireEvent.change(input, { target: { value: "A" } });
+    // 未 touch：isTouched 守卫生效，错误不显示
+    expect(screen.queryByText("名称至少2个字")).not.toBeInTheDocument();
+    fireEvent.blur(input);
+    await waitFor(() =>
+      expect(screen.getByText("名称至少2个字")).toBeInTheDocument(),
+    );
+  });
+
+  it("提交被校验拦截时字段已 touch、错误可见；有效值提交透传 values", async () => {
+    const onSubmit = vi.fn();
+    render(<Harness onSubmit={onSubmit} initialValue="A" />);
+    const input = screen.getByRole("textbox");
+    // 无效值直接提交：form-core 提交流程先 touch 全部字段再拦截 onSubmit
+    fireEvent.click(screen.getByRole("button", { name: "提交" }));
+    await waitFor(() =>
+      expect(screen.getByText("名称至少2个字")).toBeInTheDocument(),
+    );
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    fireEvent.change(input, { target: { value: "有效名称" } });
+    fireEvent.click(screen.getByRole("button", { name: "提交" }));
+    await waitFor(() =>
+      expect(onSubmit).toHaveBeenCalledWith({ name: "有效名称" }),
+    );
+  });
+
+  it("form.AppSubmit 走 form.Subscribe isSubmitting 单通道：提交中禁用", async () => {
+    let resolveSubmit: () => void = () => {};
+    const deferred = new Promise<void>((resolve) => {
+      resolveSubmit = resolve;
+    });
+    const onSubmit = vi.fn(() => deferred);
+
+    render(<SubmitHarness onSubmit={onSubmit} />);
+    const button = screen.getByRole("button", { name: "提交" });
+    expect(button).not.toBeDisabled();
+    fireEvent.click(button);
+    await waitFor(() => expect(button).toBeDisabled());
+    resolveSubmit();
+    await waitFor(() => expect(button).not.toBeDisabled());
+    expect(onSubmit).toHaveBeenCalledWith({ name: "有效名称" });
+  });
+});

package/src/components/forms/app-field-error.tsx

@@ -17,8 +17,28 @@
 
 import type { AnyFieldApi } from "@tanstack/react-form"
 
+/**
+ * 字段错误可见性的唯一口径：touch 守卫（blur 或提交尝试后）+ 校验未过。
+ * 表单库在每次提交尝试会 touch 全部字段，故提交被校验拦截时错误必然可见。
+ */
+export function hasVisibleFieldError(field: AnyFieldApi): boolean {
+  return field.meta.isTouched && !field.meta.isValid
+}
+
+/**
+ * 首条可见错误文本，供自绘错误 UI（IconInput/PasswordInput 等）消费。
+ * 与 AppFieldError 共享同一守卫语义。
+ */
+export function firstFieldErrorMessage(field: AnyFieldApi): string | undefined {
+  if (!hasVisibleFieldError(field)) return undefined
+  const first = field.errors
+    .map((e) => (typeof e === "string" ? e : e?.message ?? String(e)))
+    .find(Boolean)
+  return first ?? undefined
+}
+
 export function AppFieldError({ field }: { field: AnyFieldApi }) {
-  if (!field.meta.isTouched || field.meta.isValid) return null
+  if (!hasVisibleFieldError(field)) return null
   return (
     <span className="block text-sm text-destructive mt-1">
       {/* 校验错误可为纯字符串（无 message 属性），直接渲染会输出字面量 undefined */}

package/src/components/forms/app-field.tsx

@@ -18,6 +18,7 @@
 import type {
   AnyFieldApi,
   AnyReactFormApi,
+  FieldValidators,
 } from "@tanstack/react-form"
 import type { ReactNode } from "react"
 import {
@@ -29,19 +30,18 @@ import {
 import { Input } from "@/components/ui/input"
 import { AppFieldError } from "./app-field-error"
 
-/**
- * TODO(待决策)：TanStack Form v2（alpha）的 validators 泛型尚未稳定，
- * 精确映射 FieldValidators 需随 v2 正式版补全；当前经 AnyReactFormApi 通道透传。
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AppFieldValidators<TValue> = any
-
 export interface AppFieldProps<TValue> {
   name: string
   form: AnyReactFormApi
   label?: string
   description?: string
-  validators?: AppFieldValidators<TValue>
+  /**
+   * 字段级校验器（TanStack Form v2 Validator 配置数组）。值类型经 TValue 约束；
+   * 所属表单在 App* 封装层为 any 擦除（AnyReactFormApi 通道），由 useAppForm
+   * 的表单级 validators 承担精确类型。
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 表单数据形状在封装层擦除，与 AnyFieldApi 同口径
+  validators?: FieldValidators<any, string, TValue>
   children?: (field: AnyFieldApi) => ReactNode
   renderError?: boolean
 }

package/src/components/forms/app-submit.tsx

@@ -20,22 +20,25 @@ import type { ReactNode } from "react"
 import type { AnyReactFormApi } from "@tanstack/react-form"
 import { Button } from "@/components/ui/button"
 
+export interface AppSubmitProps {
+  /** 显式传 form 走 Subscribe isSubmitting 单通道；免传时用工厂产物 form.AppSubmit */
+  form?: AnyReactFormApi
+  isSubmitting?: boolean
+  children: ReactNode
+  disabled?: boolean
+}
+
 export function AppSubmit({
   form,
   isSubmitting,
   children,
   disabled = false,
-}: {
-  form?: AnyReactFormApi
-  isSubmitting?: boolean
-  children: ReactNode
-  disabled?: boolean
-}) {
+}: AppSubmitProps) {
   if (form && isSubmitting === undefined) {
     return (
-      <form.Subscribe<boolean>
-selector={(state: any) => state.isSubmitting}
-         children={(isSub: boolean) => (
+      <form.Subscribe
+        selector={(state) => state.isSubmitting}
+        children={(isSub) => (
           <Button type="submit" disabled={isSub || disabled}>
             {isSub ? (
               <Loader2 className="mr-2 h-4 w-4 animate-spin" />

package/src/components/forms/create-app-form.tsx

@@ -0,0 +1,124 @@
+// 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 { createFormHook, getFormHookHelpers } from "@tanstack/react-form"
+import { AppCheckbox, type AppCheckboxProps } from "./app-checkbox"
+import { AppCombobox, type AppComboboxProps } from "./app-combobox"
+import { AppDatePicker, type AppDatePickerProps } from "./app-date-picker"
+import { AppField, type AppFieldProps } from "./app-field"
+import { AppFieldError } from "./app-field-error"
+import { AppInput, type AppInputProps } from "./app-input"
+import { AppArrayField, type AppArrayFieldProps } from "./app-array-field"
+import { AppSection } from "./app-section"
+import { AppSelect, type AppSelectProps } from "./app-select"
+import { AppSubmit, type AppSubmitProps } from "./app-submit"
+import { AppSwitch, type AppSwitchProps } from "./app-switch"
+import { AppTextarea, type AppTextareaProps } from "./app-textarea"
+
+/**
+ * App* 表单套件的唯一消费入口（TanStack Form v2 createFormHook 工厂）。
+ *
+ * - `useAppForm`：创建携带已注册组件树的表单 API；表单树内经
+ *   `form.AppField` / `field.AppFieldError` 等按名消费，无需再显式传 `form`。
+ * - `formComponents`：挂在表单 API 上的组件（`form.AppXxx`）。它们经由
+ *   useFormContext 从最近的 `form.AppForm` 取表单——因此使用这些组件的
+ *   子树必须包在 `<form.AppForm>` 内。
+ * - `fieldComponents`：挂在字段 API 上的组件（`field.AppXxx`），由
+ *   fieldComponent 助手从字段上下文注入当前 field，仅在 `form.Field`
+ *   渲染回调内可用。
+ * - 提交状态单通道：一切提交态消费 `form.Subscribe isSubmitting`
+ *   （form.AppSubmit 内部同源），禁止另立 useState loading 通道。
+ */
+const { fieldComponent } = getFormHookHelpers()
+
+/** AppFieldError 免传 field：由字段上下文注入（isTouched 守卫语义见其实现） */
+const AppFieldErrorBound = fieldComponent.loose(AppFieldError, "field")
+
+// useFormContext 仅由 createFormHook 返回（包内不单独导出），绑定层组件在
+// 渲染期才调用它；函数声明提升保证上方 options 求值时绑定组件已可用。
+const { useAppForm, appFormOptions, useFormContext } = createFormHook({
+  formComponents: {
+    AppField: AppFieldBound,
+    AppInput: AppInputBound,
+    AppTextarea: AppTextareaBound,
+    AppCheckbox: AppCheckboxBound,
+    AppSwitch: AppSwitchBound,
+    AppSelect: AppSelectBound,
+    AppCombobox: AppComboboxBound,
+    AppDatePicker: AppDatePickerBound,
+    AppArrayField: AppArrayFieldBound,
+    AppSubmit: AppSubmitBound,
+    AppSection,
+  },
+  fieldComponents: {
+    AppFieldError: AppFieldErrorBound,
+  },
+})
+
+export { useAppForm, appFormOptions }
+
+function AppFieldBound<TValue>(props: Omit<AppFieldProps<TValue>, "form">) {
+  const form = useFormContext()
+  return <AppField {...props} form={form} />
+}
+
+function AppInputBound(props: Omit<AppInputProps, "form">) {
+  const form = useFormContext()
+  return <AppInput {...props} form={form} />
+}
+
+function AppTextareaBound(props: Omit<AppTextareaProps, "form">) {
+  const form = useFormContext()
+  return <AppTextarea {...props} form={form} />
+}
+
+function AppCheckboxBound(props: Omit<AppCheckboxProps, "form">) {
+  const form = useFormContext()
+  return <AppCheckbox {...props} form={form} />
+}
+
+function AppSwitchBound(props: Omit<AppSwitchProps, "form">) {
+  const form = useFormContext()
+  return <AppSwitch {...props} form={form} />
+}
+
+function AppSelectBound(props: Omit<AppSelectProps, "form">) {
+  const form = useFormContext()
+  return <AppSelect {...props} form={form} />
+}
+
+function AppComboboxBound(props: Omit<AppComboboxProps, "form">) {
+  const form = useFormContext()
+  return <AppCombobox {...props} form={form} />
+}
+
+function AppDatePickerBound(props: Omit<AppDatePickerProps, "form">) {
+  const form = useFormContext()
+  return <AppDatePicker {...props} form={form} />
+}
+
+function AppArrayFieldBound<TItem>(
+  props: Omit<AppArrayFieldProps<TItem>, "form">,
+) {
+  const form = useFormContext()
+  return <AppArrayField {...props} form={form} />
+}
+
+function AppSubmitBound(props: Omit<AppSubmitProps, "form">) {
+  const form = useFormContext()
+  return <AppSubmit {...props} form={form} />
+}

package/src/components/forms/index.ts

@@ -26,6 +26,5 @@ export { AppDatePicker } from "./app-date-picker"
 export { AppArrayField, type AppArrayFieldProps } from "./app-array-field"
 export { AppSection } from "./app-section"
 export { AppSubmit } from "./app-submit"
-export { AppFormDialog } from "./app-form-dialog"
-export { useFormSubmit } from "./hooks/use-form-submit"
-export type { FormSubmitConfig, AsyncValidator } from "./types"
+export { AppFieldError, firstFieldErrorMessage } from "./app-field-error"
+export { useAppForm, appFormOptions } from "./create-app-form"

package/src/components/harness/__tests__/gallery-behavior.test.tsx

@@ -9,7 +9,14 @@ import { Route as HarnessRoute } from "@/routes/_nav/harness/route.lazy"
 import type { GalleryItem } from "../gallery/gallery-types"
 import { m } from "@/paraglide/messages.js"
 
-const { listGenerationRunsFn, createVariantFn, attachToStoryFn, attachToKbFn, attachPrototypeToDesignFn, listStoriesFn, listKnowledgeFn, listDesignsFn } = vi.hoisted(() => ({
+type VideoGenerationState = {
+  isActive: boolean
+  progress: number | undefined
+  status: string | null
+  start: (item: GalleryItem, referenceImage?: string) => boolean
+  stop: () => void
+}
+const { listGenerationRunsFn, createVariantFn, attachToStoryFn, attachToKbFn, attachPrototypeToDesignFn, listStoriesFn, listKnowledgeFn, listDesignsFn, videoGeneration } = vi.hoisted(() => ({
   listGenerationRunsFn: vi.fn<() => Promise<{ runs: GalleryItem[]; nextCursor: string | null }>>(),
   createVariantFn: vi.fn<() => Promise<{ runId: string; artifacts: unknown[]; images: unknown[] }>>(),
   attachToStoryFn: vi.fn(),
@@ -18,9 +25,11 @@ const { listGenerationRunsFn, createVariantFn, attachToStoryFn, attachToKbFn, at
   listStoriesFn: vi.fn(),
   listKnowledgeFn: vi.fn(),
   listDesignsFn: vi.fn(),
+  videoGeneration: vi.fn<() => VideoGenerationState>(),
 }))
 vi.mock("@/components/billing/feature-gate", () => ({ FeatureGate: ({ children }: { children: React.ReactNode }) => children }))
 vi.mock("@/server/serverFns/harness/gallery", () => ({ listGenerationRunsFn, createVariantFn }))
+vi.mock("@/components/harness/gallery/use-video-generation", () => ({ useVideoGeneration: videoGeneration }))
 vi.mock("@/server/serverFns/harness/attach-to-story", () => ({ attachToStoryFn }))
 vi.mock("@/server/serverFns/harness/attach-to-kb", () => ({ attachToKbFn }))
 vi.mock("@/server/serverFns/harness/attach-prototype", () => ({ attachPrototypeToDesignFn }))
@@ -56,6 +65,8 @@ beforeEach(() => {
   vi.mocked(listStoriesFn).mockReset()
   vi.mocked(listKnowledgeFn).mockReset()
   vi.mocked(listDesignsFn).mockReset()
+  videoGeneration.mockClear()
+  videoGeneration.mockImplementation(() => ({ isActive: false, progress: undefined, status: null, start: vi.fn(() => true), stop: vi.fn() }))
 })
 afterEach(() => { cleanup(); clients.splice(0).forEach((value) => value.clear()) })
 
@@ -118,6 +129,31 @@ describe("gallery behavior", () => {
     expect(screen.getAllByRole("button", { name: "生成变体" })).toHaveLength(2)
   })
 
+  it("shows streaming progress on the generating video card and stops from it", async () => {
+    const start = vi.fn(() => true)
+    const stop = vi.fn()
+    videoGeneration.mockImplementation(() => ({ isActive: true, progress: 42, status: "processing", start, stop }))
+    vi.mocked(listGenerationRunsFn).mockResolvedValue({ runs: [item("a"), item("b", "video")], nextCursor: null })
+    grid()
+    const stopButtons = await screen.findAllByRole("button", { name: m.gallery_videoStop() })
+    expect(stopButtons).toHaveLength(1) // 仅生成中的视频卡
+    expect(screen.getByText(m.gallery_videoProgress({ progress: 42 }))).toBeInTheDocument()
+    // 生成中的卡片不再提供变体入口，图片卡不受影响
+    expect(screen.getAllByRole("button", { name: m.gallery_createVariant() })).toHaveLength(1)
+    fireEvent.click(stopButtons[0])
+    expect(stop).toHaveBeenCalledTimes(1)
+    expect(start).not.toHaveBeenCalled()
+  })
+
+  it("routes video variant clicks to the streaming hook (toast covered by hook tests)", async () => {
+    const start = vi.fn((_item: GalleryItem, _referenceImage?: string) => false)
+    videoGeneration.mockImplementation(() => ({ isActive: false, progress: undefined, status: null, start, stop: vi.fn() }))
+    vi.mocked(listGenerationRunsFn).mockResolvedValue({ runs: [item("b", "video")], nextCursor: null })
+    grid()
+    fireEvent.click(await screen.findByRole("button", { name: m.gallery_createVariant() }))
+    expect(start.mock.calls[0]?.[0]).toMatchObject({ id: "b" })
+  })
+
   it("keeps the gallery and localizes variant failures", async () => {
     vi.mocked(listGenerationRunsFn).mockResolvedValue({ runs: [item("a")], nextCursor: null })
     vi.mocked(createVariantFn).mockRejectedValue(new Error("provider failure"))

package/src/components/harness/__tests__/harness-workbench-first-send.test.tsx

@@ -79,7 +79,10 @@ vi.mock("@tanstack/react-router", () => ({
   ),
 }))
 
-vi.mock("@tanstack/react-query", () => ({
+vi.mock("@tanstack/react-query", async (importOriginal) => ({
+  // queryOptions 工厂（lib/queries/agents）经组件 import 链在此求值，
+  // 需要真实 queryOptions；useQuery 仍按本测试口径桩化
+  ...(await importOriginal<typeof import("@tanstack/react-query")>()),
   useQuery: () => ({ data: undefined }),
 }))