From d02d0ed7a45de31f9601ff6478ee04a9acea4545 Mon Sep 17 00:00:00 2001
From: Suzumiya <suzmii@qq.com>
Date: Mon, 14 Sep 2026 17:07:55 +0800
Subject: [PATCH] =?UTF-8?q?AGC=20=E8=B5=84=E6=BA=90=E7=94=BB=E5=B8=83?=
 =?UTF-8?q?=EF=BC=9A=E6=96=B0=E7=B4=A0=E6=9D=90=E4=B8=8D=E5=86=8D=E8=87=AA?=
 =?UTF-8?q?=E5=8A=A8=E9=87=8D=E6=8E=92=EF=BC=8C=E6=94=B9=E4=B8=BA=E6=98=BE?=
 =?UTF-8?q?=E5=BC=8F=E3=80=8C=E6=95=B4=E7=90=86=E7=94=BB=E5=B8=83=E3=80=8D?=
 =?UTF-8?q?=E5=B9=B6=E5=9C=A8=E7=94=9F=E6=88=90=E5=90=8E=E8=87=AA=E5=8A=A8?=
 =?UTF-8?q?=E8=81=9A=E7=84=A6=E6=96=B0=E7=B4=A0=E6=9D=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- useProjectResourceCanvasLayout：资源写意图新增 rederive 标记，显式整理那一笔按 rederive
  策略重算自动坐标（手动坐标原样保留），自动同步仍是 preserve 只补新卡
- useProjectResourceCanvasLayout：新增 rederiveNow()，复用既有写队列 / sidecar 写回链路，
  只在坐标确有变化时落盘，成功复用既有「布局已保存」提示
- index.tsx：两个排序模式的 rederiveAutomaticPositions 都固定 false，画布不再因为资源
  协调签名变化（新增素材、改标签、改分类、拓扑重建）整体重排
- index.tsx：依赖侧「关系图首次就绪」改为按项目作用域的一次性 flag，等该侧 sidecar ready
  后调用一次 rederiveNow()，之后一律只补新卡（切排序 tab 不重新武装）
- index.tsx：依赖/类型 tab 组新增「整理画布」按钮，作为整张画布重排的唯一显式入口
- index.tsx：新增 manifest.assets 新增 id 检测（seenManifestAssetIdsRef），把新卡交给既有
  pendingResourceFocusRef + advanceFocusGeneration() 裁决链聚焦；首次打开 / 切项目只登记
  基线不聚焦，重命名不改 id 天然不触发，已有同目标意图时不重复挂
- 新增 tests/resourceCanvasManualLayout.test.tsx（8 条）：新素材入库后既有自动坐标逐值不变、
  依赖侧首次就绪后不再重排、新素材自动聚焦、被搜索挡住走既有「清除搜索并定位」、
  「整理画布」重算并保留手动坐标、已经整齐时再按一次不写盘、首次打开与切项目不聚焦
---
 .../src/view/project-development/index.tsx    | 116 ++-
 .../useProjectResourceCanvasLayout.ts         |  67 +-
 .../tests/resourceCanvasManualLayout.test.tsx | 838 ++++++++++++++++++
 3 files changed, 1015 insertions(+), 6 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx

diff --git a/apps/ai-game-creator-shell/src/view/project-development/index.tsx b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
index 60842a4f6..14fa858a9 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/index.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
@@ -2369,7 +2369,8 @@ export default function ProjectDevelopmentView({
     topology: resourceLayoutTopology,
     initializationReady: resourceGraphInitializationReady,
     renderFallbackWhileBlocked: resourceGraphFailed,
-    rederiveAutomaticPositions: resourceGraphReady,
+    // 画布不再自动重派生：新增素材只补位，整张重排只能由「整理画布」显式发起。
+    rederiveAutomaticPositions: false,
   });
   const typeLayout = useProjectResourceCanvasLayout({
     projectPath,
@@ -2377,8 +2378,38 @@ export default function ProjectDevelopmentView({
     mode: 'type',
     resources: resourcesWithCanvasCardSize,
     initializationReady: true,
-    rederiveAutomaticPositions: true,
+    rederiveAutomaticPositions: false,
   });
+  /**
+   * 依赖视图的自动重派生只做一次：关系图首次就绪、且这一侧的 sidecar 已经读完的那一刻。
+   *
+   * 旧口径把 `rederiveAutomaticPositions` 长期等于 `resourceGraphReady`——只要关系图是
+   * 现成的，任何一次资源协调签名变化（新增一张素材、改一个标签、拓扑重建）都会丢掉全部
+   * 自动坐标重排整张画布。现在改成一次性：首次就绪时用显式重派生把坐标对齐到最终拓扑，
+   * 之后一律只补新卡。用 ref 记"这一次已经做过"，而不是让布尔长期为真；判据也放在
+   * `dependencyLayout.ready` 之后就绪，避免"关系图先就绪、sidecar 后读完"时把这一次重算
+   * 白白吃掉。按项目作用域记账：切排序 tab 不会重新武装它。
+   */
+  const dependencyRederiveScopeRef = useRef<string | null>(null);
+  const dependencyLayoutReady = dependencyLayout.ready;
+  const rederiveDependencyLayout = dependencyLayout.rederiveNow;
+  useEffect(() => {
+    if (!resourceGraphReady || !dependencyLayoutReady) {
+      return;
+    }
+    const scopeKey = JSON.stringify([projectPath, manifest.projectId]);
+    if (dependencyRederiveScopeRef.current === scopeKey) {
+      return;
+    }
+    dependencyRederiveScopeRef.current = scopeKey;
+    rederiveDependencyLayout();
+  }, [
+    dependencyLayoutReady,
+    manifest.projectId,
+    projectPath,
+    rederiveDependencyLayout,
+    resourceGraphReady,
+  ]);
   const activeResourceLayout =
     sortMode === 'dependency' ? dependencyLayout : typeLayout;
   const resourceLayout = activeResourceLayout.layout;
@@ -5103,6 +5134,72 @@ export default function ProjectDevelopmentView({
     [advanceFocusGeneration, manifest.assets, openUiDesignEditor],
   );
 
+  /**
+   * 新素材入库后自动聚焦：只认 `manifest.assets` 里**此前没见过**的 id。
+   *
+   * 存量素材不是"刚生成"：首次打开项目 / 切项目只登记基线，不然一进工作台就会跳到
+   * 最后一张卡上。重命名不改 id，天然不触发。
+   *
+   * 这里不自己造滚动或选中逻辑，只把意图交给既有的 `pendingResourceFocusRef` +
+   * `advanceFocusGeneration()` 裁决链：投影、两种布局落位、可见性、DOM 就绪都由那条链
+   * 负责，被搜索条件挡住时也沿用现成的「清除搜索并定位」提示与动作。
+   *
+   * 已有一条指向同一资源的聚焦意图时不再插手：显式生成链路（面板/工具栏生成）已经在
+   * 提交时就挂好了意图，重复设置只会把它更精细的提示文案顶掉。
+   */
+  const seenManifestAssetIdsRef = useRef<{
+    scopeKey: string;
+    ids: Set<string>;
+  } | null>(null);
+  useEffect(() => {
+    const scopeKey = JSON.stringify([projectPath, manifest.projectId]);
+    const assetIds = manifest.assets.map((asset) => asset.id);
+    const previous = seenManifestAssetIdsRef.current;
+    if (!previous || previous.scopeKey !== scopeKey) {
+      seenManifestAssetIdsRef.current = { scopeKey, ids: new Set(assetIds) };
+      return;
+    }
+    const addedIds = assetIds.filter((id) => !previous.ids.has(id));
+    for (const id of assetIds) {
+      previous.ids.add(id);
+    }
+    if (addedIds.length === 0) {
+      return;
+    }
+    // 一次可能进多条（例如一次派生产出多个产物）：聚焦清单里最后落地的那一条。
+    const addedAssetId = addedIds[addedIds.length - 1]!;
+    const resourceId = `asset:${addedAssetId}`;
+    // 资源投影是同步的：这里查不到对应资源说明这条素材不会出现在画布上，
+    // 不为它挂聚焦意图，免得裁决链一直停在"等待投影"。
+    if (!resources.some((resource) => resource.id === resourceId)) {
+      return;
+    }
+    if (pendingResourceFocusRef.current?.resourceId === resourceId) {
+      return;
+    }
+    const flowId = crypto.randomUUID();
+    const focusGeneration = advanceFocusGeneration();
+    activeFocusFlowIdRef.current = flowId;
+    pendingResourceFocusRef.current = {
+      flowId,
+      saveAttemptId: flowId,
+      sessionId: flowId,
+      draftId: flowId,
+      commitId: `asset-added:${addedAssetId}`,
+      projectPath,
+      projectId: manifest.projectId,
+      focusGeneration,
+      resourceId,
+      completed: false,
+    };
+  }, [
+    advanceFocusGeneration,
+    manifest.assets,
+    manifest.projectId,
+    projectPath,
+    resources,
+  ]);
+
   useEffect(() => {
     if (uiEditorRoute) return;
     const completed = manifest.assets.find(
@@ -7101,6 +7198,21 @@ export default function ProjectDevelopmentView({
                       <ListFilter size={15} aria-hidden="true" />
                       类型
                     </button>
+                    {/*
+                      画布不再自动重排，整张整理只由这一次显式动作发起：丢掉全部自动坐标、
+                      按当前资源与拓扑重算（手动拖过的卡原地不动）。进行中的保存/重算仍然由
+                      既有的「保存中 / 布局已保存」状态位反馈。
+                    */}
+                    <button
+                      type="button"
+                      aria-label="整理画布"
+                      disabled={!resourceLayoutReady}
+                      aria-busy={resourceLayoutSaving}
+                      onClick={() => activeResourceLayout.rederiveNow()}
+                    >
+                      <LayoutGrid size={15} aria-hidden="true" />
+                      整理画布
+                    </button>
                   </div>
                 </>
               ) : null}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
index 2a2444f4b..0a7a3c789 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
@@ -67,6 +67,15 @@ type ResourceLayoutWriteIntent = {
   scopeEpoch: number;
   resourceSignature: string;
   conflictRetries: number;
+  /**
+   * 显式「整理画布」写意图：这一笔写回按 `rederive` 策略丢掉全部自动坐标重算。
+   *
+   * 仍然是"坐标真的变了才落盘"（沿用既有 `changed` 门）：已经整齐的画布按一下不该产生
+   * 一次无意义的 CAS / revision 推进，也不该在关系图被截断这类"重算结果同样可信但不能
+   * 声称变过"的场景里凭空写一笔。自动（签名变化触发）的资源同步永远是 `false`，
+   * 只补新卡、不动既有坐标。
+   */
+  rederive: boolean;
 };
 
 type LayoutWriteIntent = ManualLayoutWriteIntent | ResourceLayoutWriteIntent;
@@ -74,9 +83,10 @@ type LayoutWriteIntent = ManualLayoutWriteIntent | ResourceLayoutWriteIntent;
 const MAX_RESOURCE_SYNC_CONFLICT_RETRIES = 2;
 
 /**
- * 自动坐标策略。`rederive` 在每次协调时丢弃全部自动坐标并按当前资源与拓扑重算，
- * PRD 要求的「关系图首次就绪 / `dependencyDepth` / 拓扑身份签名变化后按最终拓扑
- * 重算」依赖它；`preserve` 只补新资源 ID，不重排任何已存在的坐标。
+ * 自动坐标策略。`rederive` 丢掉全部自动坐标、按当前资源与拓扑重算（手动坐标原样保留）；
+ * 它现在只由显式动作触发——用户的「整理画布」按钮，以及「关系图首次就绪」那一次
+ * `rederiveNow()`。`preserve` 只补新资源 ID，不重排任何已存在的坐标，是画布默认口径：
+ * 新增一张素材不再牵动整张画布。
  */
 type AutomaticPositionPolicy = 'rederive' | 'preserve';
 
@@ -532,6 +542,7 @@ export function useProjectResourceCanvasLayout({
         scopeEpoch,
         resourceSignature: signature,
         conflictRetries,
+        rederive: false,
       });
     }
     if (mountedRef.current) {
@@ -565,7 +576,9 @@ export function useProjectResourceCanvasLayout({
     const writePolicy =
       intent.kind === 'manual'
         ? MANUAL_WRITE_AUTOMATIC_POSITION_POLICY
-        : automaticPositionPolicy(rederiveAutomaticPositions);
+        : intent.rederive
+          ? 'rederive'
+          : automaticPositionPolicy(rederiveAutomaticPositions);
     const reconciled = reconcileLayout(
       persistedLayoutRef.current,
       resourcesRef.current,
@@ -686,6 +699,9 @@ export function useProjectResourceCanvasLayout({
           if (intent.kind === 'manual') {
             redragRequiredScopeEpochRef.current = null;
             setNotice('布局已保存');
+          } else if (intent.rederive) {
+            // 显式整理复用同一条提示：用户按了按钮，就必须看到"这次重算真的落盘了"。
+            setNotice('布局已保存');
           }
           if (needsResourceSync) {
             enqueueResourceSyncRef.current(currentScope.epoch);
@@ -1004,6 +1020,48 @@ export function useProjectResourceCanvasLayout({
     [applyLayout, initializationReady, scopeKey],
   );
 
+  /**
+   * 显式「整理画布」：丢掉全部自动坐标、按当前资源与拓扑重算一次；坐标确有变化时写回
+   * sidecar（沿用既有 `changed` 门），画布本身先乐观按重算结果显示。
+   *
+   * 这是整张画布重排的唯一入口——画布不再因为资源协调签名变化自动重派生。走的是与自动
+   * 同步同一条写队列与写回链路，只把策略换成 `rederive`；用户可见反馈仍由既有的
+   * `notice` / `saving` 状态位承担，不另造一套状态。
+   */
+  const rederiveNow = useCallback(() => {
+    const scope = scopeRef.current;
+    if (
+      scope.key !== scopeKey ||
+      !initializationReady ||
+      initializedScopeEpochRef.current !== scope.epoch
+    ) {
+      return;
+    }
+    const queued = writeQueueRef.current.find(
+      (intent): intent is ResourceLayoutWriteIntent =>
+        intent.kind === 'resources' &&
+        intent.scopeEpoch === scope.epoch &&
+        intent.rederive &&
+        intent !== activeWriteIntentRef.current,
+    );
+    if (queued) {
+      queued.resourceSignature = resourceSignatureRef.current;
+      queued.conflictRetries = 0;
+    } else {
+      writeQueueRef.current.push({
+        kind: 'resources',
+        scopeEpoch: scope.epoch,
+        resourceSignature: resourceSignatureRef.current,
+        conflictRetries: 0,
+        rederive: true,
+      });
+    }
+    // 乐观视图：立刻把重算结果显示出来，别让用户以为按钮没反应。
+    rebuildOptimisticLayout(scope.epoch, 'rederive');
+    setSaving(true);
+    pumpWritesRef.current();
+  }, [initializationReady, rebuildOptimisticLayout, scopeKey]);
+
   const scopeMatches =
     initializationReady &&
     scopeRef.current.key === scopeKey &&
@@ -1035,5 +1093,6 @@ export function useProjectResourceCanvasLayout({
     readReport,
     scopeIdentity: scopeKey,
     commitPosition,
+    rederiveNow,
   };
 }
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx
new file mode 100644
index 000000000..40271eea6
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx
@@ -0,0 +1,838 @@
+/** @vitest-environment jsdom */
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type {
+  GameCreationAppAssetManifestEntry,
+  GameCreationAppManifest,
+  ProjectResourceCanvasCategory,
+  ProjectResourceCanvasPosition,
+} from '../../../packages/shared/src/contracts/gameCreationApp';
+import ProjectDevelopmentView from '../src/view/project-development';
+import type { ResourceCanvasItem } from '../src/view/project-development/resourceCanvasLayoutModel';
+import {
+  createResourceSignature,
+  useProjectResourceCanvasLayout,
+} from '../src/view/project-development/useProjectResourceCanvasLayout';
+import {
+  createGameCreationAppManifest,
+  findResourceSelectButton,
+  fireEvent,
+  openResourceFilterPanel,
+  React,
+  render,
+  screen,
+} from './appSurface/harness';
+
+/**
+ * 「AGC 资源画布：新素材不自动重排 + 生成后自动聚焦 + 显式整理画布」的行为级验收。
+ *
+ * 三条口径：
+ * 1. 画布不再因为「资源协调签名变化」重排整张画布——新增一张素材只补它的位置，
+ *    既有自动卡坐标逐值不变；要重排只能由用户按「整理画布」显式发起。
+ * 2. 新素材入库后自动进入视口并被选中；被搜索条件挡住时沿用既有「清除搜索并定位」。
+ * 3. 首次打开项目 / 切项目不触发聚焦跳转。
+ */
+
+const NEW_ASSET_ID = 'asset-newly-generated';
+const NEW_RESOURCE_ID = `asset:${NEW_ASSET_ID}`;
+
+type AssetFixture = GameCreationAppAssetManifestEntry;
+
+function pngAsset(id: string, fileName: string): AssetFixture {
+  return {
+    id,
+    kind: 'character',
+    category: 'character',
+    mediaType: 'image/png',
+    localPath: `assets/${fileName}`,
+    source: { kind: 'generated', resourceId: `${id}-resource` },
+  };
+}
+
+function markdownAsset(id: string, fileName: string): AssetFixture {
+  return {
+    id,
+    kind: 'game-rules',
+    mediaType: 'text/markdown',
+    localPath: `docs/${fileName}`,
+    source: { kind: 'generated', resourceId: `${id}-resource` },
+  };
+}
+
+function manifestFor(
+  projectId: string,
+  assets: AssetFixture[],
+): GameCreationAppManifest {
+  return {
+    ...createGameCreationAppManifest(projectId, `${projectId} 项目`),
+    assets: assets.map((asset) => structuredClone(asset)),
+  };
+}
+
+type LayoutWrite = {
+  projectPath: string;
+  mode: string;
+  positions: ProjectResourceCanvasPosition[];
+};
+
+type FakeTauri = {
+  invoke: ReturnType<typeof vi.fn>;
+  layoutWrites: LayoutWrite[];
+  layoutReads: Array<{ projectPath: string; mode: string }>;
+  unexpectedCommands: string[];
+};
+
+function resourceGraphFor(
+  resources: Array<{ resourceId: string }> | undefined,
+) {
+  const resourceIds = (resources ?? []).map((resource) => resource.resourceId);
+  return {
+    resourceIds,
+    referenceEdges: [],
+    taskFlows: [],
+    connectionIndex: resourceIds.map((resourceId) => ({
+      resourceId,
+      upstreamReferenceResourceIds: [],
+      downstreamReferenceResourceIds: [],
+      referenceEdgeIds: [],
+      taskFlowIds: [],
+    })),
+    producerAssignments: [],
+    dependencyDepths: resourceIds.map((resourceId) => ({
+      resourceId,
+      dependencyDepth: 0,
+    })),
+    unresolvedReferenceResourceIds: [],
+    cyclicResourceIds: [],
+    cyclicTaskIds: [],
+    producerMappingTruncated: false,
+  };
+}
+
+/**
+ * 只铺张画布真正用到的那几个本地命令。
+ *
+ * 未知命令返回 `undefined` 并记账（而不是抛错）：这份用例验的是布局与聚焦链路，
+ * 不该因为画布里别的入口多调一个命令就整体转红；真要漏了关键命令，
+ * 目标链路自己会停在"等待"上，断言照样失败。
+ */
+function installLayoutTauri(
+  options: {
+    projectIdsByPath?: Record<string, string>;
+    layoutByScope?: Record<string, ProjectResourceCanvasPosition[]>;
+  } = {},
+): FakeTauri {
+  const layoutWrites: LayoutWrite[] = [];
+  const layoutReads: Array<{ projectPath: string; mode: string }> = [];
+  const unexpectedCommands: string[] = [];
+  const persisted = new Map<string, ProjectResourceCanvasPosition[]>();
+  const revisions = new Map<string, number>();
+  for (const [key, positions] of Object.entries(options.layoutByScope ?? {})) {
+    persisted.set(key, structuredClone(positions));
+  }
+
+  const invoke = vi.fn(
+    async (command: string, args?: Record<string, unknown>) => {
+      if (command === 'get_local_game_project_revision') {
+        return { revision: 1 };
+      }
+      if (command === 'read_local_project_resource_graph') {
+        return resourceGraphFor(
+          args?.resources as Array<{ resourceId: string }> | undefined,
+        );
+      }
+      if (command === 'read_local_project_resource_canvas_layout') {
+        const projectPath = String(args?.projectPath ?? '');
+        const mode = String(args?.mode ?? '');
+        layoutReads.push({ projectPath, mode });
+        const key = `${projectPath}|${mode}`;
+        return {
+          schemaVersion: 'game-creator-resource-layout.v1',
+          projectId: options.projectIdsByPath?.[projectPath] ?? '',
+          mode,
+          revision: revisions.get(key) ?? 0,
+          positions: structuredClone(persisted.get(key) ?? []),
+          updatedAt: 0,
+        };
+      }
+      if (command === 'update_local_project_resource_canvas_layout') {
+        const projectPath = String(args?.projectPath ?? '');
+        const mode = String(args?.mode ?? '');
+        const key = `${projectPath}|${mode}`;
+        const positions = structuredClone(
+          (args?.positions ?? []) as ProjectResourceCanvasPosition[],
+        );
+        persisted.set(key, positions);
+        revisions.set(key, Number(args?.expectedRevision ?? 0) + 1);
+        layoutWrites.push({ projectPath, mode, positions });
+        return {
+          status: 'updated',
+          layout: {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId: String(args?.expectedProjectId ?? ''),
+            mode,
+            revision: revisions.get(key)!,
+            positions,
+            updatedAt: 1,
+          },
+        };
+      }
+      if (command === 'list_pending_local_project_resource_edits') {
+        return [];
+      }
+      if (command === 'read_local_project_image_preview') {
+        return {
+          path: String(args?.relativePath ?? ''),
+          mediaType: 'image/png',
+          byteLen: 1,
+          dataUrl: 'data:image/png;base64,AA==',
+        };
+      }
+      if (command === 'read_local_project_text_preview') {
+        return {
+          path: String(args?.relativePath ?? ''),
+          mediaType: 'text/markdown',
+          byteLen: 8,
+          content: '# 玩法规则',
+        };
+      }
+      unexpectedCommands.push(command);
+      return undefined;
+    },
+  );
+
+  window.__TAURI__ = { core: { invoke } } as unknown as typeof window.__TAURI__;
+  return { invoke, layoutWrites, layoutReads, unexpectedCommands };
+}
+
+function typeWrites(tauri: FakeTauri) {
+  return tauri.layoutWrites.filter((write) => write.mode === 'type');
+}
+
+function dependencyWrites(tauri: FakeTauri) {
+  return tauri.layoutWrites.filter((write) => write.mode === 'dependency');
+}
+
+function selectedResourceIdsInDom() {
+  return Array.from(
+    document.querySelectorAll<HTMLElement>('[data-resource-id]'),
+  )
+    .filter((element) => element.getAttribute('aria-pressed') === 'true')
+    .map((element) => element.dataset.resourceId);
+}
+
+/**
+ * 把布局读写与聚焦裁决链跑到底再下断言。
+ *
+ * 「不该聚焦」这类否定断言最怕"跑得太早"：断言时链路还没走到聚焦那一步，写什么都会绿。
+ * 这里先把微任务与一个宏任务放完，让链路在该触发的情况下已经触发过。
+ */
+async function settleFocusChain() {
+  await act(async () => {
+    await Promise.resolve();
+    await Promise.resolve();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+type ProjectFixture = {
+  projectId: string;
+  projectPath: string;
+  assets: AssetFixture[];
+};
+
+/**
+ * 把 manifest 交给真实工作台视图持有，并提供两个"外部世界"动作：
+ * 「入库新素材」（等价于生成流程落盘后 `onManifestChange` 收到多一条 asset 的清单）
+ * 与「切换项目」（换 projectPath + projectId + 清单）。
+ */
+function LayoutWorkbench({
+  projects,
+  appendedAsset,
+}: {
+  projects: ProjectFixture[];
+  appendedAsset?: AssetFixture;
+}) {
+  const [activeIndex, setActiveIndex] = React.useState(0);
+  const [manifests, setManifests] = React.useState<
+    Record<string, GameCreationAppManifest>
+  >(() =>
+    Object.fromEntries(
+      projects.map((project) => [
+        project.projectId,
+        manifestFor(project.projectId, project.assets),
+      ]),
+    ),
+  );
+  const active = projects[activeIndex]!;
+  const manifest = manifests[active.projectId]!;
+
+  return (
+    <>
+      {appendedAsset ? (
+        <button
+          type="button"
+          onClick={() =>
+            setManifests((current) => {
+              const base = current[active.projectId]!;
+              return {
+                ...current,
+                [active.projectId]: {
+                  ...base,
+                  assets: [...base.assets, structuredClone(appendedAsset)],
+                },
+              };
+            })
+          }
+        >
+          测试：入库新素材
+        </button>
+      ) : null}
+      {projects.length > 1 ? (
+        <button
+          type="button"
+          onClick={() =>
+            setActiveIndex((current) => (current + 1) % projects.length)
+          }
+        >
+          测试：切换项目
+        </button>
+      ) : null}
+      <ProjectDevelopmentView
+        projectName={manifest.name}
+        projectPath={active.projectPath}
+        manifest={manifest}
+        attachments={[]}
+        recentRunStatus={null}
+        recentRunStopReason={null}
+        supervisor={<div>Supervisor</div>}
+        onHomeOpen={() => undefined}
+        onProjectsOpen={() => undefined}
+        onManifestChange={(_path, nextManifest) =>
+          setManifests((current) => {
+            const projectId = nextManifest.projectId;
+            return { ...current, [projectId]: nextManifest };
+          })
+        }
+      />
+    </>
+  );
+}
+
+afterEach(() => {
+  delete window.__TAURI__;
+  vi.restoreAllMocks();
+});
+
+describe('资源画布手动重排口径', () => {
+  it('hook：rederiveNow 按 rederive 策略重算自动坐标并写回一次', async () => {
+    const projectId = 'manual-rederive-project';
+    const projectPath = '/tmp/manual-rederive-project';
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId,
+            mode: args?.mode,
+            revision: 3,
+            positions: [
+              {
+                resourceId: 'resource-b',
+                section: 'document',
+                x: 600,
+                y: 40,
+                manuallyPlaced: true,
+              },
+              {
+                resourceId: 'resource-a',
+                section: 'document',
+                x: 900,
+                y: 900,
+                manuallyPlaced: false,
+              },
+            ],
+            updatedAt: 300,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          return {
+            status: 'updated',
+            layout: {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId,
+              mode: args?.mode,
+              revision: 4,
+              positions: args?.positions,
+              updatedAt: 400,
+            },
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = {
+      core: { invoke },
+    } as unknown as typeof window.__TAURI__;
+
+    const resources: ResourceCanvasItem[] = ['resource-a', 'resource-b'].map(
+      (id) => ({
+        id,
+        category: 'document' as ProjectResourceCanvasCategory,
+        subtype: 'agent-result',
+        label: id,
+        mediaType: 'text/markdown',
+        dependencyDepth: 0,
+      }),
+    );
+    const { result } = renderHook(() =>
+      useProjectResourceCanvasLayout({
+        projectPath,
+        projectId,
+        mode: 'type',
+        resources,
+        rederiveAutomaticPositions: false,
+      }),
+    );
+
+    await waitFor(() => expect(result.current.ready).toBe(true));
+    // 自动卡还停在落后坐标上：preserve 口径不会自己去纠正它。
+    expect(
+      result.current.layout.positions.find(
+        (position) => position.resourceId === 'resource-a',
+      ),
+    ).toMatchObject({ x: 900, y: 900 });
+
+    await act(async () => {
+      result.current.rederiveNow();
+    });
+
+    await waitFor(() =>
+      expect(
+        invoke.mock.calls.filter(
+          ([command]) =>
+            command === 'update_local_project_resource_canvas_layout',
+        ),
+      ).toHaveLength(1),
+    );
+    const written = invoke.mock.calls.find(
+      ([command]) => command === 'update_local_project_resource_canvas_layout',
+    )?.[1]?.positions as ProjectResourceCanvasPosition[];
+    expect(written).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          resourceId: 'resource-a',
+          x: 0,
+          y: 0,
+          manuallyPlaced: false,
+        }),
+        expect.objectContaining({
+          resourceId: 'resource-b',
+          x: 600,
+          y: 40,
+          manuallyPlaced: true,
+        }),
+      ]),
+    );
+  });
+
+  it('新素材入库后既有自动卡坐标逐值不变，新卡只补在末尾', async () => {
+    const tauri = installLayoutTauri({
+      projectIdsByPath: {
+        '/tmp/manual-layout-project': 'manual-layout-project',
+      },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-layout-project',
+            projectPath: '/tmp/manual-layout-project',
+            assets: [
+              pngAsset('asset-art-b', 'art-b.png'),
+              pngAsset('asset-art-c', 'art-c.png'),
+              pngAsset('asset-art-d', 'art-d.png'),
+            ],
+          },
+        ]}
+        appendedAsset={pngAsset(NEW_ASSET_ID, 'art-a-new.png')}
+      />,
+    );
+
+    await waitFor(() => expect(typeWrites(tauri).length).toBeGreaterThan(0));
+    const before = typeWrites(tauri).at(-1)!;
+    expect(
+      before.positions.map((position) => position.resourceId),
+    ).not.toContain(NEW_RESOURCE_ID);
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '测试：入库新素材' }),
+    );
+
+    await waitFor(() =>
+      expect(
+        typeWrites(tauri).some((write) =>
+          write.positions.some(
+            (position) => position.resourceId === NEW_RESOURCE_ID,
+          ),
+        ),
+      ).toBe(true),
+    );
+    const after = typeWrites(tauri).find((write) =>
+      write.positions.some(
+        (position) => position.resourceId === NEW_RESOURCE_ID,
+      ),
+    )!;
+
+    // 核心判据：除新卡外全部既有坐标逐值不变（顺序、分区、手动标记都不许动）。
+    expect(
+      after.positions.filter(
+        (position) => position.resourceId !== NEW_RESOURCE_ID,
+      ),
+    ).toEqual(
+      before.positions.filter(
+        (position) => position.resourceId !== NEW_RESOURCE_ID,
+      ),
+    );
+  });
+
+  it('依赖画布只在关系图首次就绪时重算一次，之后新增素材不再重排', async () => {
+    const projectPath = '/tmp/manual-dependency-project';
+    const tauri = installLayoutTauri({
+      projectIdsByPath: { [projectPath]: 'manual-dependency-project' },
+      layoutByScope: {
+        [`${projectPath}|dependency`]: [
+          {
+            resourceId: 'asset:asset-art-b',
+            section: 'character',
+            x: 0,
+            y: 0,
+            manuallyPlaced: false,
+          },
+          {
+            resourceId: 'asset:asset-art-a',
+            section: 'character',
+            x: 900,
+            y: 900,
+            manuallyPlaced: false,
+          },
+        ],
+      },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-dependency-project',
+            projectPath,
+            assets: [
+              pngAsset('asset-art-a', 'art-a.png'),
+              pngAsset('asset-art-b', 'art-b.png'),
+            ],
+          },
+        ]}
+        appendedAsset={pngAsset(NEW_ASSET_ID, 'art-a-new.png')}
+      />,
+    );
+
+    // 一次性重派生：关系图首次就绪后按最终拓扑把落后的自动坐标对齐一次。
+    await waitFor(() =>
+      expect(
+        dependencyWrites(tauri).some((write) =>
+          write.positions.some(
+            (position) =>
+              position.resourceId === 'asset:asset-art-a' &&
+              (position.x !== 900 || position.y !== 900),
+          ),
+        ),
+      ).toBe(true),
+    );
+    const before = dependencyWrites(tauri).at(-1)!;
+    expect(
+      before.positions.map((position) => position.resourceId),
+    ).not.toContain(NEW_RESOURCE_ID);
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '测试：入库新素材' }),
+    );
+
+    await waitFor(() =>
+      expect(
+        dependencyWrites(tauri).some((write) =>
+          write.positions.some(
+            (position) => position.resourceId === NEW_RESOURCE_ID,
+          ),
+        ),
+      ).toBe(true),
+    );
+    const after = dependencyWrites(tauri).find((write) =>
+      write.positions.some(
+        (position) => position.resourceId === NEW_RESOURCE_ID,
+      ),
+    )!;
+
+    expect(
+      after.positions.filter(
+        (position) => position.resourceId !== NEW_RESOURCE_ID,
+      ),
+    ).toEqual(
+      before.positions.filter(
+        (position) => position.resourceId !== NEW_RESOURCE_ID,
+      ),
+    );
+  });
+
+  it('新素材入库后自动进入视口并被选中', async () => {
+    const tauri = installLayoutTauri({
+      projectIdsByPath: { '/tmp/manual-focus-project': 'manual-focus-project' },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-focus-project',
+            projectPath: '/tmp/manual-focus-project',
+            assets: [
+              pngAsset('asset-art-b', 'art-b.png'),
+              pngAsset('asset-art-c', 'art-c.png'),
+            ],
+          },
+        ]}
+        appendedAsset={pngAsset(NEW_ASSET_ID, 'art-a-new.png')}
+      />,
+    );
+
+    await waitFor(() => expect(typeWrites(tauri).length).toBeGreaterThan(0));
+    expect(selectedResourceIdsInDom()).toEqual([]);
+
+    fireEvent.click(
+      await screen.findByRole('button', { name: '测试：入库新素材' }),
+    );
+
+    await waitFor(() =>
+      expect(new Set(selectedResourceIdsInDom())).toEqual(
+        new Set([NEW_RESOURCE_ID]),
+      ),
+    );
+  });
+
+  it('新素材被搜索条件挡住时走既有「清除搜索并定位」路径', async () => {
+    const tauri = installLayoutTauri({
+      projectIdsByPath: {
+        '/tmp/manual-focus-hidden-project': 'manual-focus-hidden-project',
+      },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-focus-hidden-project',
+            projectPath: '/tmp/manual-focus-hidden-project',
+            assets: [pngAsset('asset-art-b', 'art-b.png')],
+          },
+        ]}
+        appendedAsset={markdownAsset(NEW_ASSET_ID, 'new-rules.md')}
+      />,
+    );
+
+    await findResourceSelectButton('art-b.png');
+    const search = openResourceFilterPanel();
+    fireEvent.change(search, { target: { value: 'art-b' } });
+    expect(selectedResourceIdsInDom()).toEqual([]);
+
+    fireEvent.click(screen.getByRole('button', { name: '测试：入库新素材' }));
+
+    expect(
+      await screen.findByText('新资源已保存，但被当前搜索条件隐藏'),
+    ).not.toBeNull();
+    // 搜索条件只由显式动作清除，不静默改用户输入。
+    expect(openResourceFilterPanel().value).toBe('art-b');
+    fireEvent.click(screen.getByRole('button', { name: '清除搜索并定位' }));
+
+    await waitFor(() =>
+      expect(new Set(selectedResourceIdsInDom())).toEqual(
+        new Set([NEW_RESOURCE_ID]),
+      ),
+    );
+    expect(tauri.unexpectedCommands).toEqual([]);
+  });
+
+  it('「整理画布」按 rederive 重算自动坐标、保留手动坐标，并给出一次可见反馈', async () => {
+    const projectPath = '/tmp/manual-rederive-button-project';
+    const tauri = installLayoutTauri({
+      projectIdsByPath: {
+        [projectPath]: 'manual-rederive-button-project',
+      },
+      layoutByScope: {
+        [`${projectPath}|type`]: [
+          {
+            resourceId: 'asset:asset-art-a',
+            section: 'character',
+            x: 600,
+            y: 40,
+            manuallyPlaced: true,
+          },
+          {
+            resourceId: 'asset:asset-art-b',
+            section: 'character',
+            x: 800,
+            y: 800,
+            manuallyPlaced: false,
+          },
+        ],
+      },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-rederive-button-project',
+            projectPath,
+            assets: [
+              pngAsset('asset-art-a', 'art-a.png'),
+              pngAsset('asset-art-b', 'art-b.png'),
+            ],
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(
+        document.querySelector('[data-resource-id="asset:asset-art-b"]'),
+      ).not.toBeNull(),
+    );
+    // 切到「类型」视图：两个排序模式各有一份 sidecar，按钮作用于当前生效的那一份。
+    fireEvent.click(screen.getByRole('button', { name: '按类型' }));
+    // 打开项目 / 切排序 tab 这两步都不该重排：自动卡的落后坐标原样保留。
+    expect(typeWrites(tauri)).toEqual([]);
+
+    fireEvent.click(screen.getByRole('button', { name: '整理画布' }));
+
+    await waitFor(() => expect(typeWrites(tauri)).toHaveLength(1));
+    expect(typeWrites(tauri)[0]!.positions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          resourceId: 'asset:asset-art-b',
+          section: 'character',
+          x: 0,
+          y: 0,
+          manuallyPlaced: false,
+        }),
+        expect.objectContaining({
+          resourceId: 'asset:asset-art-a',
+          section: 'character',
+          x: 600,
+          y: 40,
+          manuallyPlaced: true,
+        }),
+      ]),
+    );
+    expect(await screen.findByText('布局已保存')).not.toBeNull();
+
+    // 已经整齐之后再按一次不产生第二次落盘：重算结果与当前坐标一致时不写（既有「截断关系图
+    // 不得持久化自动布局」用例依赖同一条 `changed` 门）。
+    fireEvent.click(screen.getByRole('button', { name: '整理画布' }));
+    await settleFocusChain();
+    expect(typeWrites(tauri)).toHaveLength(1);
+  });
+
+  it('首次打开项目与切项目都不触发新素材聚焦跳转', async () => {
+    const tauri = installLayoutTauri({
+      projectIdsByPath: {
+        '/tmp/manual-open-project-a': 'manual-open-project-a',
+        '/tmp/manual-open-project-b': 'manual-open-project-b',
+      },
+    });
+    render(
+      <LayoutWorkbench
+        projects={[
+          {
+            projectId: 'manual-open-project-a',
+            projectPath: '/tmp/manual-open-project-a',
+            assets: [
+              pngAsset('asset-a1', 'a1.png'),
+              pngAsset('asset-a2', 'a2.png'),
+            ],
+          },
+          {
+            projectId: 'manual-open-project-b',
+            projectPath: '/tmp/manual-open-project-b',
+            assets: [
+              pngAsset('asset-b1', 'b1.png'),
+              pngAsset('asset-b2', 'b2.png'),
+            ],
+          },
+        ]}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(
+        document.querySelector('[data-resource-id="asset:asset-a1"]'),
+      ).not.toBeNull(),
+    );
+    // 布局读写先跑完，再给聚焦裁决链一次"要是会被误触发就已经触发"的机会。
+    await waitFor(() => expect(typeWrites(tauri).length).toBeGreaterThan(0));
+    await settleFocusChain();
+    expect(selectedResourceIdsInDom()).toEqual([]);
+
+    fireEvent.click(screen.getByRole('button', { name: '测试：切换项目' }));
+
+    await waitFor(() =>
+      expect(
+        tauri.layoutReads.some(
+          (read) => read.projectPath === '/tmp/manual-open-project-b',
+        ),
+      ).toBe(true),
+    );
+    await waitFor(() =>
+      expect(
+        document.querySelector('[data-resource-id="asset:asset-b1"]'),
+      ).not.toBeNull(),
+    );
+    await waitFor(() =>
+      expect(
+        typeWrites(tauri).some(
+          (write) => write.projectPath === '/tmp/manual-open-project-b',
+        ),
+      ).toBe(true),
+    );
+    await settleFocusChain();
+    expect(selectedResourceIdsInDom()).toEqual([]);
+  });
+
+  it('资源协调签名仍把新增素材算作变化（重排判据没有被人为掐掉）', () => {
+    const single = createResourceSignature([
+      {
+        id: 'asset:x',
+        category: 'character',
+        subtype: 'character',
+        label: 'x',
+        mediaType: 'image/png',
+        dependencyDepth: 0,
+      },
+    ]);
+    const doubled = createResourceSignature([
+      {
+        id: 'asset:x',
+        category: 'character',
+        subtype: 'character',
+        label: 'x',
+        mediaType: 'image/png',
+        dependencyDepth: 0,
+      },
+      {
+        id: 'asset:y',
+        category: 'character',
+        subtype: 'character',
+        label: 'y',
+        mediaType: 'image/png',
+        dependencyDepth: 0,
+      },
+    ]);
+    expect(single).not.toBe(doubled);
+  });
+});