@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/design/editor/collaboration/design-comment-review-panel.tsx

@@ -25,7 +25,7 @@ import { toast } from '@/components/ui/toast';
 import { useSession } from "@/components/shared-kit/auth/auth-client";
 import { maskEmail, formatTime, formatEditedTime } from "@/lib/comment-utils";
 import { UserAvatar } from "@/components/shared-kit";
-import type { AvatarConfig, ShapeType } from "@allbluecn/kernel";
+import type { AvatarConfig } from "@allbluecn/kernel";
 import { listCommentsFn, ignoreCommentFn } from "@/server/serverFns/design/comments";
 import { m } from "@/paraglide/messages.js";
 
@@ -39,7 +39,7 @@ interface CommentUser {
   username: string;
   email: string;
   avatarConfig?: AvatarConfig | null;
-  bgShape?: ShapeType | null;
+  bgShape?: string | null;
   bgColor?: string | null;
 }
 
@@ -65,13 +65,13 @@ export function DesignCommentReviewPanel({ designId }: DesignCommentReviewPanelP
   useEffect(() => {
     if (!session?.user?.id) {
       listCommentsFn({ data: { designId } })
-        .then((all: Awaited<ReturnType<typeof listCommentsFn>>) => setComments(all.map((c: any) => ({ ...c, createdAt: c.createdAt.toISOString(), updatedAt: c.updatedAt?.toISOString() ?? '', user: { ...c.user, avatarConfig: c.user.avatarConfig as AvatarConfig | null, bgShape: c.user.bgShape as ShapeType | null, bgColor: c.user.bgColor } }))))
+        .then((all: Awaited<ReturnType<typeof listCommentsFn>>) => setComments(all.map((c: any) => ({ ...c, createdAt: c.createdAt.toISOString(), updatedAt: c.updatedAt?.toISOString() ?? '', user: { ...c.user, avatarConfig: c.user.avatarConfig as AvatarConfig | null, bgShape: c.user.bgShape, bgColor: c.user.bgColor } }))))
         .catch(() => {});
       return;
     }
     listCommentsFn({ data: { designId, includeResolved: true } })
       .then((all: Awaited<ReturnType<typeof listCommentsFn>>) => {
-        const mapped = all.map((c: any) => ({ ...c, createdAt: c.createdAt.toISOString(), updatedAt: c.updatedAt?.toISOString() ?? '', user: { ...c.user, avatarConfig: c.user.avatarConfig as AvatarConfig | null, bgShape: c.user.bgShape as ShapeType | null, bgColor: c.user.bgColor } }));
+        const mapped = all.map((c: any) => ({ ...c, createdAt: c.createdAt.toISOString(), updatedAt: c.updatedAt?.toISOString() ?? '', user: { ...c.user, avatarConfig: c.user.avatarConfig as AvatarConfig | null, bgShape: c.user.bgShape, bgColor: c.user.bgColor } }));
         setComments(mapped.filter((c: any) => !c.resolved));
         setIgnoredIds(new Set(mapped.filter((c: any) => c.resolved).map((c: any) => c.id)));
       })
@@ -159,7 +159,7 @@ export function DesignCommentReviewPanel({ designId }: DesignCommentReviewPanelP
                   <div key={c.id} className="flex gap-2 text-xs">
                     <UserAvatar
                       avatarConfig={c.user.avatarConfig as AvatarConfig | null | undefined}
-                      bgShape={c.user.bgShape as ShapeType | null | undefined}
+                      bgShape={c.user.bgShape}
                       bgColor={c.user.bgColor}
                       name={c.user.username}
                       className="size-7"

package/src/components/design/editor/dashboard/create-design-dialog.tsx

@@ -87,7 +87,7 @@ export function CreateDesignDialog({ open, onOpenChange, onSuccess }: CreateDesi
 
   return (
     <Dialog open={open} onOpenChange={handleOpenChange}>
-      <DialogContent className="sm:max-w-260 -mt-50">
+      <DialogContent className="sm:max-w-[min(65rem,calc(100%-4rem))] max-w-[calc(100%-4rem)] max-h-[calc(100dvh-2rem)] [@media(min-height:64rem)]:-mt-50 overflow-y-auto">
         <DialogHeader>
           <DialogTitle className="text-xl">{m.prd_dialog_createTitle()}</DialogTitle>
         </DialogHeader>

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

@@ -23,7 +23,6 @@ import { Link } from "@tanstack/react-router";
 import { Card } from "@/components/ui/card";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
-import { TagBadge } from '@/components/tags/tag-badge'
 import { GridPattern } from "@/components/shared-kit/decorative/grid-pattern";
 import { LayoutPanelTopIcon } from "@/components/shared-kit/layout/layout-panel-top";
 import { ConfirmDialog } from "@/components/confirm-dialog";
@@ -131,8 +130,7 @@ export function DesignDashboard() {
     return prds.filter(
       (p) =>
         p.name.toLowerCase().includes(q) ||
-        (p.description || "").toLowerCase().includes(q) ||
-        (p.designTags?.some((pt) => pt.tag.name.toLowerCase().includes(q))),
+        (p.description || "").toLowerCase().includes(q),
     );
   }, [prds, search]);
 
@@ -241,13 +239,6 @@ export function DesignDashboard() {
                     </Button>
                   </div>
                   <h3 className="mt-4 font-medium text-lg truncate">{prd.name}</h3>
-                  {prd.designTags && prd.designTags.length > 0 && (
-                    <div className="mt-1.5 flex flex-wrap gap-1">
-                      {prd.designTags.map((pt) => (
-                        <TagBadge key={pt.tag.id} tag={pt.tag} className="text-xs" />
-                      ))}
-                    </div>
-                  )}
                   <p className="mt-1 line-clamp-2 min-h-10 text-sm text-muted-foreground">
                     {prd.description?.trim() || m.dashboard_dashboard_noDescription()}
                   </p>

package/src/components/design/editor/layout/__tests__/collab-param-wiring.test.tsx

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 设计编辑器 collab 参数链路测试（任务 30 装配验收）：
+// DesignEditorLayout 计算 isCollabEnabled() → ① useDesignAutoSave 收到
+// collab=...（T29 保存让位接线）② CanvasPresenceLayer 收到 collab +
+// loadedSceneDoc（画布协同装配入口参数链）。isCollabEnabled=false（desktop/
+// 未配置 WS）时两者收到 false——全短路零开销。
+
+import React, { createContext } from 'react'
+import { render, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const envState = vi.hoisted(() => ({ enabled: true }))
+vi.mock('@/lib/collab/env', () => ({
+  isCollabEnabled: () => envState.enabled,
+  getCollabWsUrl: () => (envState.enabled ? 'ws://collab.test' : ''),
+}))
+
+const captured = vi.hoisted(() => ({
+  autoSave: [] as Array<Record<string, unknown>>,
+  presence: [] as Array<Record<string, unknown>>,
+}))
+
+vi.mock('../hooks/use-design-auto-save', () => ({
+  useDesignAutoSave: (args: Record<string, unknown>) => {
+    captured.autoSave.push(args)
+    return {
+      canvasSaving: false,
+      docSaving: false,
+      canvasDirty: false,
+      docDirty: false,
+      saveCanvasNow: async () => {},
+      saveCanvasRef: { current: async () => {} },
+      saveDoc: async () => {},
+      saveAll: async () => {},
+      handleDocChange: () => {},
+      handleSceneGenerated: () => {},
+      handleDocContentChange: () => {},
+      registerCanvasJSON: () => {},
+    }
+  },
+}))
+
+vi.mock('@/components/design/canvas/plugins/presence/presence-layer', () => ({
+  CanvasPresenceLayer: (props: Record<string, unknown>) => {
+    captured.presence.push(props)
+    return null
+  },
+}))
+
+vi.mock('@tanstack/react-hotkeys', () => ({
+  useHotkey: () => {},
+}))
+
+vi.mock('@/components/design/editor/layout/design-left-sidebar', () => ({
+  DesignLeftSidebar: () => null,
+}))
+vi.mock('@/components/design/editor/layout/design-right-sidebar', () => ({
+  DesignRightSidebar: () => null,
+}))
+vi.mock('@/components/design/editor/layout/design-navigation', () => ({
+  DesignNavigation: () => null,
+}))
+vi.mock('@/components/design/canvas/panels/layer-panel', () => ({
+  LayerPanel: () => null,
+}))
+vi.mock('@/components/design/canvas/panels/toolbar', () => ({
+  CanvasToolbar: () => null,
+}))
+vi.mock('@/components/design/editor/annotation/overlay/annotation-overlay', () => ({
+  AnnotationOverlay: () => null,
+}))
+vi.mock('@/components/design/canvas/react/canvas-context', () => ({
+  CanvasContext: createContext(null),
+  CanvasProvider: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+}))
+vi.mock('@/components/design/canvas/react/canvas-root', () => ({
+  CanvasRoot: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+}))
+vi.mock('@/components/design/canvas/react/workbench', () => ({
+  CanvasControls: () => null,
+}))
+vi.mock('@/components/design/canvas/react/hooks', () => ({
+  useCanvasEngineOptional: () => null,
+  useCanvasSnapshotOptional: () => null,
+  useSelection: () => [],
+  useDeleteSelection: () => () => {},
+}))
+vi.mock('@/components/ui/toast', () => ({
+  toast: { success: vi.fn(), error: vi.fn(), warning: vi.fn() },
+}))
+vi.mock('@/server/serverFns/design/pages', () => ({
+  getDesignPageFn: vi.fn().mockRejectedValue(new Error('not found')),
+  updateDesignPageFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/design/designs', () => ({
+  updateDesignFn: vi.fn(),
+}))
+
+import { DesignEditorLayout } from '../design-editor-layout'
+import type { Design } from '@allbluecn/kernel'
+
+const designFixture = {
+  id: 'design_1',
+  name: 'test',
+  ownerId: 'user_1',
+  workspaceId: 'ws_1',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+} as unknown as Design
+
+beforeEach(() => {
+  captured.autoSave = []
+  captured.presence = []
+  envState.enabled = true
+  localStorage.clear()
+})
+
+describe('DesignEditorLayout collab 参数链（任务 30 装配）', () => {
+  it('collab 可用 → useDesignAutoSave 收到 collab=true', () => {
+    render(<DesignEditorLayout prd={designFixture} />)
+    expect(captured.autoSave.length).toBeGreaterThan(0)
+    expect(captured.autoSave[0]?.collab).toBe(true)
+  })
+
+  it('collab 可用 → CanvasPresenceLayer 收到 collab=true', () => {
+    render(<DesignEditorLayout prd={designFixture} />)
+    expect(captured.presence.length).toBeGreaterThan(0)
+    expect(captured.presence[0]?.collab).toBe(true)
+  })
+
+  it('collab 不可用（desktop/未配置 WS）→ auto-save collab=false（非协同零变化）', () => {
+    envState.enabled = false
+    render(<DesignEditorLayout prd={designFixture} />)
+    expect(captured.autoSave[0]?.collab).toBe(false)
+    expect(captured.presence[0]?.collab).toBe(false)
+  })
+
+  it('CanvasPresenceLayer 收到 pageLoaded 门控（canvasLoadedRef 镜像，审查 C1）', async () => {
+    // loadPage 仅在 localStorage 有 lastPage 时自启（use-design-page-load）：
+    // 渲染前种入 → 挂载首帧 loadPage 已发起（canvasLoadedRef=false，编辑面
+    // 门控关闭）→ loadPage 落定（mock 拒绝 → catch 分支 + canvasLoadedRef=true）
+    localStorage.setItem('lastPage_design_1', 'page-1')
+    render(<DesignEditorLayout prd={designFixture} />)
+    expect(captured.presence[0]?.pageLoaded).toBe(false)
+    await waitFor(() => {
+      expect(captured.presence.some((p) => p.pageLoaded === true)).toBe(true)
+    })
+  })
+})

package/src/components/design/editor/layout/__tests__/no-page-save-toast.test.tsx

@@ -23,6 +23,14 @@ vi.mock("@tanstack/react-hotkeys", () => ({
   },
 }));
 
+// 单机模式前提钉住（任务 30 装配后布局按 isCollabEnabled 门控保存让位）：
+// worktree .env 注入 VITE_COLLAB_WS_URL 会让真实判定为协同态、保存全短路，
+// 本测试的无页保存提示路径即不可达——非协同语义显式 mock
+vi.mock("@/lib/collab/env", () => ({
+  isCollabEnabled: () => false,
+  getCollabWsUrl: () => "",
+}));
+
 // 左栏探针：捕获布局下发的 onPageSelect（switchPage），测试按需模拟页面树自动选中
 let sidebarOnPageSelect: ((pageId: string) => void) | null = null;
 vi.mock("@/components/design/editor/layout/design-left-sidebar", () => ({

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

@@ -35,6 +35,7 @@ import { CanvasProvider } from "@/components/design/canvas/react/canvas-context"
 import { CanvasRoot } from "@/components/design/canvas/react/canvas-root";
 import { CanvasControls } from "@/components/design/canvas/react/workbench";
 import { CanvasToolbar } from "@/components/design/canvas/panels/toolbar";
+import { CanvasPresenceLayer } from "@/components/design/canvas/plugins/presence/presence-layer";
 import { typeNameOf } from "@/components/design/canvas/panels/panel-schema";
 import { LayerPanel } from "@/components/design/canvas/panels/layer-panel";
 import {
@@ -62,6 +63,7 @@ import {
 } from "./context-menu-items";
 import type { PrototypeScene } from "@/server/serverFns/design/ai/generate-prototype";
 import { useDebouncer } from "@/lib/pacer";
+import { isCollabEnabled } from "@/lib/collab/env";
 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";
@@ -116,6 +118,13 @@ type EditorShellProps = {
   onAiModelChange: (model: string) => void;
   onAnnotate: (nodeId: string) => void;
   onSceneGenerated: (scene: PrototypeScene) => void;
+  // 协同入口参数（任务 30 装配）：布局层按 isCollabEnabled() 计算，直通
+  // CanvasPresenceLayer（门控建连；false = 全短路零挂载）
+  collabEnabled: boolean;
+  // 页面数据装载完成（canvasLoadedRef 渲染时镜像）：协同编辑面门控——
+  // 「activePageId 先行、sceneDoc 未到」窗口内引擎持旧页文档，Y 写通道
+  // 关闭（审查 C1，与 auto-save 同口径）
+  pageLoaded: boolean;
 };
 
 function EditorShell(props: EditorShellProps) {
@@ -124,6 +133,7 @@ function EditorShell(props: EditorShellProps) {
     docAutoSaveTime, docSaving,
     editorRef, registerCanvasJSON, canvasAutoSaveTime, canvasSaving, leftPanelOpen,
     onToggleLeft, onPageSelect, aiModel, onAiModelChange, onAnnotate, onSceneGenerated,
+    collabEnabled, pageLoaded,
   } = props;
 
   const selection = useSelection();
@@ -458,6 +468,14 @@ function EditorShell(props: EditorShellProps) {
             <CanvasRoot className="h-full">
               <CanvasToolbarBar saving={canvasSaving} autoSaveTime={canvasAutoSaveTime} />
             </CanvasRoot>
+            {/* 画布协同（P4a presence + P4b 编辑协同装配）：collab=false 时内部
+                渲染 null（挂载零侵入）；loadedSceneDoc 供 loadDoc 防覆盖守卫 */}
+            <CanvasPresenceLayer
+              pageId={activePageId}
+              collab={collabEnabled}
+              loadedSceneDoc={sceneDoc}
+              pageLoaded={pageLoaded}
+            />
           </div>
           <AnnotationOverlay containerRef={contentAreaRef} selectedComponentId={selectedComponentId} sceneDoc={sceneDoc} />
         </div>
@@ -503,6 +521,10 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
   const editorRef = useRef<Editor | null>(null);
   const [prd, setDesign] = useState<Design>(initialDesign);
   const { leftPanelOpen, setLeftPanelOpen } = useDesignLeftPanelPreference();
+  // 协同入口判定（任务 30 装配）：desktop 版 / 未配置 WS → false，全链路
+  // 短路（auto-save 双通道照常、画布协同 UI 零挂载）；调用时读取（非模块
+  // 常量）保证 env 变化按渲染生效
+  const collabEnabled = isCollabEnabled();
 
   // 加载域（activePageId/sceneDoc/docContent/预览态/dirty 标志）
   // 文档自动保存防抖（经 pacer，禁止手写 setTimeout）；单实例同时传给
@@ -523,7 +545,9 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
     setIsPreviewing: loaded.setIsPreviewing,
   });
 
-  // 自动保存域：画布 + 文档双通道（含官方 JSON 导出器注册）
+  // 自动保存域：画布 + 文档双通道（含官方 JSON 导出器注册）；协同态
+  // collab=true 双通道短路（T29 保存让位——Y.Doc 是权威副本，落库由 collab
+  // 服务端回写导出器接管，DB 双写互吞）
   const autoSave = useDesignAutoSave({
     activePageId: loaded.activePageId,
     sceneDoc: loaded.sceneDoc,
@@ -542,6 +566,7 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
     setDocAutoSaveTime: loaded.setDocAutoSaveTime,
     docSaveFnRef,
     docDebouncer,
+    collab: collabEnabled,
   });
 
   const switchPage = useCallback(async (pageId: string) => {
@@ -638,6 +663,8 @@ export function DesignEditorLayout({ prd: initialDesign }: DesignEditorLayoutPro
                 onAiModelChange={setAiModel}
                 onAnnotate={handleAnnotate}
                 onSceneGenerated={autoSave.handleSceneGenerated}
+                collabEnabled={collabEnabled}
+                pageLoaded={loaded.canvasLoadedRef.current}
               />
             </CanvasProvider>
           </div>

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

@@ -33,7 +33,6 @@ import { NameConfirmDialog } from "@/components/shared-kit/dialogs/name-confirm-
 import { useRouter } from "@tanstack/react-router";
 import { ICON_MAP, type Design } from "@allbluecn/kernel";
 import { deleteDesignFn } from "@/server/serverFns/design/designs";
-import { TagBadge } from '@/components/tags/tag-badge'
 import {
   Share2,
   History,
@@ -163,9 +162,6 @@ export function DesignNavigation({
             </span>
           )}
 
-          {prd.designTags?.map((pt) => (
-            <TagBadge key={pt.tag.id} tag={pt.tag} className="shrink-0" />
-          ))}
         </div>
 
         <div className="flex items-center gap-1">

package/src/components/design/editor/layout/hooks/__tests__/use-design-auto-save-collab.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+/**
+ * 画布保存让位（Yjs 多人协作任务 29，§5.3 写入路由）：协同态下 useDesignAutoSave
+ * 画布+文档双通道全部短路——updateDesignPageFn 零调用（Y.Doc 是权威副本，落库
+ * 由 collab 服务端回写导出器接管；DB 双写互吞）。非协同（缺省）零行为变化回归。
+ */
+
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/paraglide/messages.js", () => ({
+  m: { canvas_save_noPage: () => "[i18n] canvas_save_noPage" },
+}));
+vi.mock("@/components/ui/toast", () => ({
+  toast: { success: vi.fn(), error: vi.fn(), warning: vi.fn() },
+}));
+vi.mock("@/server/serverFns/design/pages", () => ({
+  updateDesignPageFn: vi.fn(async () => ({ id: "p1" })),
+}));
+vi.mock("@/lib/time-format", () => ({ formatSaveTime: () => "just now" }));
+
+import { updateDesignPageFn } from "@/server/serverFns/design/pages";
+import { useDesignAutoSave } from "../use-design-auto-save";
+import type { SceneDocument } from "@/components/design/canvas/document/types";
+
+const emptyScene = {
+  version: 1 as const,
+  meta: { device: "desktop" as const },
+  nodes: [
+    { id: "board", kind: "group", type: "board", parentId: null, x: 0, y: 0, width: 1200, height: 812, style: {}, props: {} },
+  ],
+};
+
+type HookArgs = Parameters<typeof useDesignAutoSave>[0];
+
+function baseArgs(over: Partial<HookArgs> = {}): HookArgs {
+  return {
+    activePageId: "page_1",
+    sceneDoc: emptyScene as unknown as SceneDocument,
+    setSceneDoc: vi.fn(),
+    docContent: { html: "<p>文档</p>", markdown: "文档" },
+    setDocContent: vi.fn(),
+    canvasDirty: false,
+    setCanvasDirty: vi.fn(),
+    docDirty: false,
+    setDocDirty: vi.fn(),
+    isPreviewingRef: { current: false },
+    canvasLoadedRef: { current: true },
+    lastLoadedDocRef: { current: null },
+    timezone: "Asia/Shanghai",
+    setCanvasAutoSaveTime: vi.fn(),
+    setDocAutoSaveTime: vi.fn(),
+    docSaveFnRef: { current: async () => {} },
+    docDebouncer: { maybeExecute: vi.fn(), cancel: vi.fn() },
+    ...over,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("useDesignAutoSave × 协同态保存让位", () => {
+  it("collab=true：画布手动保存短路（updateDesignPageFn 零调用，不报错）", async () => {
+    const { result } = renderHook((props: HookArgs) => useDesignAutoSave(props), {
+      initialProps: baseArgs({ collab: true }),
+    });
+
+    await act(async () => {
+      await result.current.saveCanvasNow("manual");
+    });
+
+    expect(updateDesignPageFn).not.toHaveBeenCalled();
+  });
+
+  it("collab=true：文档手动保存同样短路（双通道让位）", async () => {
+    const { result } = renderHook((props: HookArgs) => useDesignAutoSave(props), {
+      initialProps: baseArgs({ collab: true }),
+    });
+
+    await act(async () => {
+      await result.current.saveDoc("manual");
+    });
+
+    expect(updateDesignPageFn).not.toHaveBeenCalled();
+  });
+
+  it("collab=true：saveAll（Mod+S 路径）整体零调用", async () => {
+    const { result } = renderHook((props: HookArgs) => useDesignAutoSave(props), {
+      initialProps: baseArgs({ collab: true }),
+    });
+
+    await act(async () => {
+      await result.current.saveAll();
+    });
+
+    expect(updateDesignPageFn).not.toHaveBeenCalled();
+  });
+
+  it("collab 缺省（false）：画布保存照常调用 updateDesignPageFn（非协同零变化回归）", async () => {
+    const { result } = renderHook((props: HookArgs) => useDesignAutoSave(props), {
+      initialProps: baseArgs(),
+    });
+
+    await act(async () => {
+      await result.current.saveCanvasNow("manual");
+    });
+
+    expect(updateDesignPageFn).toHaveBeenCalledTimes(1);
+    expect(updateDesignPageFn).toHaveBeenCalledWith({
+      data: expect.objectContaining({ pageId: "page_1" }),
+    });
+  });
+
+  it("collab 缺省（false）：文档保存照常调用 updateDesignPageFn", async () => {
+    const { result } = renderHook((props: HookArgs) => useDesignAutoSave(props), {
+      initialProps: baseArgs(),
+    });
+
+    await act(async () => {
+      await result.current.saveDoc("manual");
+    });
+
+    expect(updateDesignPageFn).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -37,6 +37,7 @@ export function useDesignAutoSave({
   setDocAutoSaveTime,
   docSaveFnRef,
   docDebouncer,
+  collab = false,
 }: {
   activePageId: string | null;
   sceneDoc: SceneDocument;
@@ -54,13 +55,25 @@ export function useDesignAutoSave({
   setCanvasAutoSaveTime: (time: string | null) => void;
   setDocAutoSaveTime: (time: string | null) => void;
   /** 文档保存后置注入槽：由壳层创建并同步传给 useDesignPageLoad，
-   * 使 loadPage 首行的 cancel 作用于本 hook 真正调度 saveDoc 的同一实例 */
+   * 使 loadPage 的 cancel 作用于本 hook 真正调度 saveDoc 的同一实例 */
   docSaveFnRef: { current: () => Promise<void> };
   docDebouncer: { maybeExecute: () => void; cancel: () => void };
+  /**
+   * 协同态开关（任务 29，画布保存让位）：true = 画布+文档双通道保存全部短路
+   * （updateDesignPageFn 零调用）——Y.Doc 是权威副本，落库由 collab 服务端
+   * 回写导出器接管；DB 双写会互吞（§5.3 写入路由）。与 story-detail-body 的
+   * collab 双模式对齐：非协同（缺省 false）零行为变化。dirty/保存时间等
+   * UI 会话状态照常维护——仅 DB 落库让位。
+   */
+  collab?: boolean;
 }) {
   const [canvasSaving, setCanvasSaving] = useState(false);
   const [docSaving, setDocSaving] = useState(false);
 
+  // 协同态 ref 镜像（callback deps 不含 collab 以免重建防抖链，同 sceneDocRef 惯例）
+  const collabRef = useRef(collab);
+  collabRef.current = collab;
+
   // handleDocChange 的空画布倒退守卫需要读取最新 sceneDoc（callback deps
   // 不含它以免重建防抖链），用 ref 镜像
   const sceneDocRef = useRef(sceneDoc);
@@ -81,6 +94,8 @@ export function useDesignAutoSave({
   // 的 maybeExecute 作用于同一调度器；saveDoc 仍后置经 docSaveFnRef 解耦
 
   const saveCanvasNow = useCallback(async (type: AutoMode = "auto") => {
+    // 协同态保存让位（任务 29）：DB 落库由 collab 回写导出器接管，双写互吞
+    if (collabRef.current) return;
     if (!activePageId) {
       // 静默丢内容的用户可见兜底：无页面（如左栏折叠导致页面树未挂载）时
       // 保存被跳过，至少提示一次，避免用户误以为内容已落库
@@ -134,6 +149,8 @@ export function useDesignAutoSave({
   }, [canvasDebouncer, isPreviewingRef, setSceneDoc, setCanvasDirty]);
 
   const saveDoc = useCallback(async (type: AutoMode = "auto") => {
+    // 协同态保存让位（任务 29）：文档面同画布——Y fragment 是权威，双写互吞
+    if (collabRef.current) return;
     if (!activePageId || isPreviewingRef.current) return;
 
     const isEmpty = !docContent.markdown.trim();

package/src/components/design/editor/share/share-comment-panel.tsx

@@ -25,7 +25,7 @@ import { toast } from "@/components/ui/toast";
 import { useSession } from "@/components/shared-kit/auth/auth-client";
 import { maskEmail, formatTime, formatEditedTime } from "@/lib/comment-utils";
 import { UserAvatar } from "@/components/shared-kit";
-import type { AvatarConfig, ShapeType } from "@allbluecn/kernel";
+import type { AvatarConfig } from "@allbluecn/kernel";
 import {
   listCommentsFn,
   createCommentFn,
@@ -33,22 +33,11 @@ import {
 } from "@/server/serverFns/design/comments";
 import { m } from "@/paraglide/messages.js";
 
-interface CommentUser {
-  id: string;
-  username: string;
-  email: string;
-  avatarConfig?: AvatarConfig | null;
-  bgShape?: ShapeType | null;
-  bgColor?: string | null;
-}
-
-interface Comment {
-  id: string;
-  content: string;
-  createdAt: string;
-  updatedAt: string;
-  user: CommentUser;
-}
+// 与 listCommentsFn 返回诚实对齐（prisma include user select 全字段）：
+// user.bgShape 是 DB 自由串（UserAvatar 内部 toAvatarShape 归一，非法值归 null），
+// 不再谎称 kernel ShapeType；日期字段沿用 serverFn 声明类型（formatTime /
+// formatEditedTime 均接受 Date | string）。
+type Comment = Awaited<ReturnType<typeof listCommentsFn>>[number];
 
 interface ShareCommentPanelProps {
   designId: string;
@@ -65,7 +54,7 @@ export function ShareCommentPanel({ designId }: ShareCommentPanelProps) {
 
   useEffect(() => {
     listCommentsFn({ data: { designId } })
-      .then((data) => setComments(data as unknown as Comment[]))
+      .then(setComments)
       .catch(() => {});
   }, [designId]);
 
@@ -80,7 +69,33 @@ export function ShareCommentPanel({ designId }: ShareCommentPanelProps) {
       const newComment = await createCommentFn({
         data: { designId, content: text },
       });
-      setComments((prev) => [...prev, newComment as unknown as Comment]);
+      // createCommentFn 返回值不含 user include——乐观插入的用户取自当前
+      // session（创建者即本人），否则渲染 c.user.* 直接抛 TypeError
+      const u = session?.user;
+      const fresh: Comment = {
+        id: newComment.id,
+        designId: newComment.designId,
+        pageId: newComment.pageId,
+        elementId: newComment.elementId,
+        userId: newComment.userId,
+        content: newComment.content,
+        parentId: newComment.parentId,
+        position: newComment.position,
+        resolved: newComment.resolved,
+        createdAt: newComment.createdAt,
+        updatedAt: newComment.updatedAt,
+        user: {
+          id: u?.id ?? "",
+          username: u?.name ?? "",
+          email: u?.email ?? "",
+          avatarConfig: u?.avatarConfig ?? null,
+          bgShape: u?.bgShape ?? null,
+          bgColor: u?.bgColor ?? null,
+        },
+      };
+      // 列表按 createdAt desc（最新在前），新评论前插到顶部，免得先沉底、
+      // 重开面板才归位
+      setComments((prev) => [fresh, ...prev]);
       form.setFieldValue("text", "");
       toast.success(m.shareComment_sent());
     } catch {
@@ -135,8 +150,10 @@ export function ShareCommentPanel({ designId }: ShareCommentPanelProps) {
 
             return (
               <div key={c.id} className="flex gap-2 text-xs mt-2">
+                {/* avatarConfig 是 prisma Json（JsonValue），按全应用口径收窄为
+                    AvatarConfig 契约（同 auth.config session callback 的 cast） */}
                 <UserAvatar
-                  avatarConfig={c.user.avatarConfig}
+                  avatarConfig={c.user.avatarConfig as AvatarConfig | null}
                   bgShape={c.user.bgShape}
                   bgColor={c.user.bgColor}
                   name={c.user.username}

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

@@ -125,6 +125,9 @@ export function ShareLayout({ designId, share, versionLabel }: ShareLayoutProps)
         icon={share.design.icon}
         showAllConnections={showAllConnections}
         onToggleAllConnections={() => setShowAllConnections((v) => !v)}
+        shareToken={share.token}
+        designId={designId}
+        designver={versionLabel}
       />
       <div className="flex-1 flex overflow-hidden">
         <div className="w-56 border-r bg-muted/10 flex flex-col overflow-hidden shrink-0">