apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx

@@ -473,6 +473,8 @@ export const ResourceDependencyOverlay = forwardRef<
 ) {
   const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
   const overlayRef = useRef<SVGSVGElement>(null);
+  const canvasViewportRef = useRef(canvasViewport);
+  const scheduleViewportMeasureRef = useRef<() => void>(() => undefined);
   const [logicalViewport, setLogicalViewport] = useState<Rect | null>(null);
   const [dragPreview, setDragPreview] = useState<
     (Point & { resourceId: string }) | null
@@ -507,7 +509,7 @@ export const ResourceDependencyOverlay = forwardRef<
       const transformedViewport = plane.closest(
         '.game-resource-canvas--dependency',
       )
-        ? canvasViewport
+        ? canvasViewportRef.current
         : undefined;
       const scale = transformedViewport?.scale ?? legacyScale;
       const viewportRect = viewport.getBoundingClientRect();
@@ -536,6 +538,7 @@ export const ResourceDependencyOverlay = forwardRef<
       }
       frameId = window.requestAnimationFrame(measure);
     };
+    scheduleViewportMeasureRef.current = scheduleMeasure;
     measure();
     const ResizeObserverClass = window.ResizeObserver;
     const observer = ResizeObserverClass
@@ -552,7 +555,13 @@ export const ResourceDependencyOverlay = forwardRef<
       observer?.disconnect();
       viewport.removeEventListener('scroll', scheduleMeasure);
       window.removeEventListener('resize', scheduleMeasure);
+      scheduleViewportMeasureRef.current = () => undefined;
     };
+  }, []);
+
+  useLayoutEffect(() => {
+    canvasViewportRef.current = canvasViewport;
+    scheduleViewportMeasureRef.current();
   }, [canvasViewport, geometryRevision]);
 
   const rectByResourceId = useMemo(() => {

apps/ai-game-creator-shell/src/view/project-development/index.tsx

@@ -26,6 +26,7 @@ import {
   memo,
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
+  startTransition,
   useCallback,
   useEffect,
   useId,
@@ -850,6 +851,9 @@ export default function ProjectDevelopmentView({
   const [searchText, setSearchText] = useState('');
   const [resourceCanvasViewports, setResourceCanvasViewports] =
     useState<ResourceCanvasViewportBySortMode>(defaultResourceCanvasViewports);
+  const resourceCanvasViewportTargetsRef = useRef(
+    defaultResourceCanvasViewports(),
+  );
   const [activeResourceCategory, setActiveResourceCategory] =
     useState<ResourceCategory | null>(null);
   const [unreadResourceCategoryState, setUnreadResourceCategoryState] =
@@ -942,8 +946,10 @@ export default function ProjectDevelopmentView({
     pendingStepCount: 0,
     pendingTimerId: null,
   });
+  const renderedResourceCategoryRef = useRef<ResourceCategory | null>(null);
   const resourceCanvasPanRef = useRef<{
     pointerId: number;
+    category: ResourceCategory;
     startClientX: number;
     startClientY: number;
     startViewport: CanvasViewport;
@@ -1499,7 +1505,6 @@ export default function ProjectDevelopmentView({
     unreadResourceCategoryState.scopeKey === resourceCategoryScopeKey
       ? unreadResourceCategoryState.categories
       : new Set<ResourceCategory>();
-  resourceCanvasPageWheelRef.current.activeCategory = activePageCategory;
   const nextPageCategory =
     activePageCategory && resourcePageCategories.length > 1
       ? resourcePageCategories[
@@ -1608,36 +1613,74 @@ export default function ProjectDevelopmentView({
       resourcePositionsByCategory,
     ],
   );
-  const activeResourceCanvasViewport = activePageCategory
-    ? resourceCanvasViewports[sortMode][activePageCategory]
-    : { x: 48, y: 48, scale: 1 };
+  const activeResourceCanvasViewport = useMemo(
+    () =>
+      activePageCategory
+        ? resourceCanvasViewports[sortMode][activePageCategory]
+        : { x: 48, y: 48, scale: 1 },
+    [activePageCategory, resourceCanvasViewports, sortMode],
+  );
   const setResourceCanvasViewport = useCallback(
-    (candidate: CanvasViewport) => {
-      const activeCategory = resourceCanvasPageWheelRef.current.activeCategory;
-      if (!activeCategory) {
+    (
+      category: ResourceCategory,
+      candidate: CanvasViewport,
+      deferRender = false,
+    ) => {
+      if (!resourcePageCategories.includes(category)) {
         return;
       }
       const next = normalizeInfiniteResourceCanvasViewport(candidate);
       resourceCanvasViewportRef.current = next;
-      setResourceCanvasViewports((current) => {
-        const currentSortViewports = current[sortMode];
-        return resourceCanvasViewportsEqual(
-          currentSortViewports[activeCategory],
-          next,
-        )
-          ? current
-          : {
-              ...current,
-              [sortMode]: {
-                ...currentSortViewports,
-                [activeCategory]: next,
-              },
-            };
-      });
+      resourceCanvasViewportTargetsRef.current = {
+        ...resourceCanvasViewportTargetsRef.current,
+        [sortMode]: {
+          ...resourceCanvasViewportTargetsRef.current[sortMode],
+          [category]: next,
+        },
+      };
+      const commitViewport = () => {
+        setResourceCanvasViewports((current) => {
+          const currentSortViewports = current[sortMode];
+          if (
+            !resourceCanvasViewportsEqual(
+              resourceCanvasViewportTargetsRef.current[sortMode][category],
+              next,
+            )
+          ) {
+            return current;
+          }
+          return resourceCanvasViewportsEqual(
+            currentSortViewports[category],
+            next,
+          )
+            ? current
+            : {
+                ...current,
+                [sortMode]: {
+                  ...currentSortViewports,
+                  [category]: next,
+                },
+              };
+        });
+      };
+      if (deferRender) {
+        startTransition(commitViewport);
+      } else {
+        commitViewport();
+      }
     },
-    [sortMode],
+    [resourcePageCategories, sortMode],
   );
-  resourceCanvasViewportRef.current = activeResourceCanvasViewport;
+  useLayoutEffect(() => {
+    const pageWheelState = resourceCanvasPageWheelRef.current;
+    renderedResourceCategoryRef.current = activePageCategory;
+    if (pageWheelState.activeCategory === null) {
+      pageWheelState.activeCategory = activePageCategory;
+    }
+    if (pageWheelState.activeCategory === activePageCategory) {
+      resourceCanvasViewportRef.current = activeResourceCanvasViewport;
+    }
+  }, [activePageCategory, activeResourceCanvasViewport]);
   const selectedResource =
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
   const focusedResource =
@@ -1852,6 +1895,7 @@ export default function ProjectDevelopmentView({
     state.lastSwitchAt = 0;
     state.pendingStepCount = 0;
     state.pendingTimerId = null;
+    state.activeCategory = renderedResourceCategoryRef.current;
   }, []);
 
   const cancelResourceCanvasPan = useCallback(() => {
@@ -1919,7 +1963,13 @@ export default function ProjectDevelopmentView({
       cancelResourceCardDrag();
       cancelResourceCanvasPan();
       resourceCanvasPageWheelRef.current.activeCategory = nextCategory;
-      setActiveResourceCategory(nextCategory);
+      startTransition(() => {
+        setActiveResourceCategory((currentCategory) =>
+          resourceCanvasPageWheelRef.current.activeCategory === nextCategory
+            ? nextCategory
+            : currentCategory,
+        );
+      });
     },
     [cancelResourceCanvasPan, cancelResourceCardDrag, resourcePageCategories],
   );
@@ -1948,10 +1998,15 @@ export default function ProjectDevelopmentView({
       const waitMs = pageWheelSwitchIntervalMs - (now - state.lastSwitchAt);
       if (waitMs > 0) {
         if (state.pendingTimerId === null) {
-          state.pendingTimerId = window.setTimeout(() => {
-            resourceCanvasPageWheelRef.current.pendingTimerId = null;
+          const timerId = window.setTimeout(() => {
+            const latestState = resourceCanvasPageWheelRef.current;
+            if (latestState.pendingTimerId !== timerId) {
+              return;
+            }
+            latestState.pendingTimerId = null;
             flushPageWheel();
           }, waitMs);
+          state.pendingTimerId = timerId;
         }
         return;
       }
@@ -1974,8 +2029,15 @@ export default function ProjectDevelopmentView({
       if (resourcePageCategories.length > 0) {
         event.preventDefault();
         if (event.ctrlKey || event.metaKey) {
-          const rect =
-            resourceCanvasViewportElement(canvas)!.getBoundingClientRect();
+          cancelQueuedResourceCanvasPageWheel();
+          const viewport = resolveViewport(event);
+          const category = viewport?.dataset.resourceSectionScroll as
+            | ResourceCategory
+            | undefined;
+          if (!viewport || !category) {
+            return;
+          }
+          const rect = viewport.getBoundingClientRect();
           const result = resolveViewportFromWheel({
             viewport: resourceCanvasViewportRef.current,
             deltaX: event.deltaX,
@@ -1988,7 +2050,7 @@ export default function ProjectDevelopmentView({
               y: event.clientY - rect.top,
             },
           });
-          setResourceCanvasViewport(result.viewport);
+          setResourceCanvasViewport(category, result.viewport, true);
           return;
         }
         if (!Number.isFinite(event.deltaY) || event.deltaY === 0) {
@@ -2064,6 +2126,7 @@ export default function ProjectDevelopmentView({
     };
     const gestureStart = (rawEvent: Event) => {
       const event = rawEvent as WebKitGestureEvent;
+      cancelQueuedResourceCanvasPageWheel();
       const viewport = resolveViewport(event);
       const category = viewport?.dataset.resourceSectionScroll as
         | ResourceCategory
@@ -2148,6 +2211,7 @@ export default function ProjectDevelopmentView({
   }, [
     advanceResourceCanvasPage,
     applyAnchoredResourceSectionZoom,
+    cancelQueuedResourceCanvasPageWheel,
     mode,
     queueResourceSectionZoomScroll,
     resourcePageCategories.length,
@@ -2175,6 +2239,7 @@ export default function ProjectDevelopmentView({
         if (measuredWidth > 0 && measuredHeight > 0) {
           resourceCanvasFitKeysRef.current.add(fitKey);
           setResourceCanvasViewport(
+            activePageCategory,
             fitResourceCanvasViewportToContent({
               bounds: resourceCanvasFitBounds,
               canvasSize: { width: measuredWidth, height: measuredHeight },
@@ -2186,7 +2251,10 @@ export default function ProjectDevelopmentView({
       }
       // Resource extents can change after an image finishes measuring or a
       // card is manually moved. Keep the user's infinite pan/zoom unchanged.
-      setResourceCanvasViewport(resourceCanvasViewportRef.current);
+      setResourceCanvasViewport(
+        activePageCategory,
+        resourceCanvasViewportRef.current,
+      );
     };
     fitInitialViewportOrPreserve();
     const observer = window.ResizeObserver
@@ -2346,6 +2414,7 @@ export default function ProjectDevelopmentView({
     restoreResourceListScrollRef.current = false;
     setActiveResourceCategory(null);
     const defaultViewports = defaultResourceCanvasViewports();
+    resourceCanvasViewportTargetsRef.current = defaultViewports;
     setResourceCanvasViewports(defaultViewports);
     resourceCanvasFitKeysRef.current.clear();
     resourceCanvasViewportRef.current = defaultViewports.dependency.document;
@@ -2769,15 +2838,19 @@ export default function ProjectDevelopmentView({
   );
 
   const resetResourceCanvasViewport = useCallback(() => {
+    if (!activePageCategory) {
+      return;
+    }
     const canvasSize = resourceCanvasElementSize(resourceCanvasRef.current);
     setResourceCanvasViewport(
+      activePageCategory,
       fitResourceCanvasViewportToContent({
         bounds: resourceCanvasFitBounds,
         canvasSize,
         padding: RESOURCE_CANVAS_FIT_PADDING,
       }),
     );
-  }, [resourceCanvasFitBounds, setResourceCanvasViewport]);
+  }, [activePageCategory, resourceCanvasFitBounds, setResourceCanvasViewport]);
 
   const handleResourceCardPointerDown = useCallback(
     (
@@ -2931,6 +3004,7 @@ export default function ProjectDevelopmentView({
       event.currentTarget.setPointerCapture(event.pointerId);
       resourceCanvasPanRef.current = {
         pointerId: event.pointerId,
+        category: activePageCategory,
         startClientX: event.clientX,
         startClientY: event.clientY,
         startViewport: resourceCanvasViewportRef.current,
@@ -2945,11 +3019,15 @@ export default function ProjectDevelopmentView({
       if (!pan || pan.pointerId !== event.pointerId) {
         return;
       }
-      setResourceCanvasViewport({
-        ...pan.startViewport,
-        x: pan.startViewport.x + event.clientX - pan.startClientX,
-        y: pan.startViewport.y + event.clientY - pan.startClientY,
-      });
+      setResourceCanvasViewport(
+        pan.category,
+        {
+          ...pan.startViewport,
+          x: pan.startViewport.x + event.clientX - pan.startClientX,
+          y: pan.startViewport.y + event.clientY - pan.startClientY,
+        },
+        true,
+      );
     },
     [setResourceCanvasViewport],
   );
@@ -2973,6 +3051,7 @@ export default function ProjectDevelopmentView({
     advanceFocusGeneration();
     cancelResourceCardDrag();
     cancelResourceCanvasPan();
+    cancelQueuedResourceCanvasPageWheel();
     captureResourceListScrollPosition();
     captureResourceSectionScrollPositions();
     setSortMode(nextMode);

apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts

@@ -986,8 +986,11 @@ describe('ResourceDependencyOverlay', () => {
   it('disconnects layout observers when the SVG layer is destroyed', () => {
     const observe = vi.fn();
     const disconnect = vi.fn();
+    const construct = vi.fn();
     class TestResizeObserver {
-      constructor(_callback: ResizeObserverCallback) {}
+      constructor(_callback: ResizeObserverCallback) {
+        construct();
+      }
 
       observe = observe;
       unobserve = vi.fn();
@@ -1004,6 +1007,7 @@ describe('ResourceDependencyOverlay', () => {
         overlayView(graph, positions, new Set(graph.resourceIds), overlayRef),
       );
 
+      expect(construct).toHaveBeenCalledTimes(1);
       expect(observe).toHaveBeenCalledTimes(2);
       act(() =>
         overlayRef.current?.updateDragPreview({
@@ -1012,6 +1016,10 @@ describe('ResourceDependencyOverlay', () => {
           y: 24,
         }),
       );
+      view.rerender(
+        overlayView(graph, positions, new Set(graph.resourceIds), overlayRef),
+      );
+      expect(construct).toHaveBeenCalledTimes(1);
       expect(observe).toHaveBeenCalledTimes(2);
       view.unmount();
       expect(disconnect).toHaveBeenCalledTimes(1);

apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts

@@ -643,6 +643,56 @@ export function registerProjectWorkbenchFoundationTests() {
     fireEvent.click(screen.getByRole('button', { name: '收起资源' }));
     fireEvent.click(within(outline).getByRole('button', { name: /设计文档/ }));
 
+    dispatchPageWheel(dependencyCanvas);
+    expect(
+      screen.getByRole('region', { name: '美术资源资源画布' }),
+    ).not.toBeNull();
+    dispatchPageWheel(dependencyCanvas);
+    const zoomWhilePageWheelQueued = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      ctrlKey: true,
+      deltaX: 0,
+      deltaY: -120,
+      clientX: 80,
+      clientY: 60,
+    });
+    act(() => {
+      expect(
+        screen
+          .getByRole('button', { name: '复位资源画布' })
+          .dispatchEvent(zoomWhilePageWheelQueued),
+      ).toBe(false);
+    });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 220));
+    });
+    expect(
+      screen.getByRole('region', { name: '美术资源资源画布' }),
+    ).not.toBeNull();
+    dispatchPageWheel(dependencyCanvas);
+    expect(
+      screen.getByRole('region', { name: '音乐音效资源画布' }),
+    ).not.toBeNull();
+    fireEvent.click(within(outline).getByRole('button', { name: /设计文档/ }));
+    act(() => {
+      dependencyCanvas.dispatchEvent(
+        new WheelEvent('wheel', {
+          bubbles: true,
+          cancelable: true,
+          deltaX: 0,
+          deltaY: 160,
+        }),
+      );
+      within(outline)
+        .getByRole('button', { name: /^项目版本/ })
+        .click();
+    });
+    expect(
+      screen.getByRole('region', { name: '项目版本资源画布' }),
+    ).not.toBeNull();
+    fireEvent.click(within(outline).getByRole('button', { name: /设计文档/ }));
+
     const dragCard = screen
       .getByRole('button', {
         name: /打开资源详情：设计文档 section\.md/,

docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md

@@ -83,14 +83,14 @@
 ## 操作边界
 
 - 栏目顺序固定为 `设计文档 -> 美术资源 -> 音乐音效 -> 游戏代码 -> 项目版本`。完全空项目显示全部栏目的分区展览；任一栏目出现资源后，分页大纲以左侧垂直居中的悬浮 Dock 展示全部栏目。常态缩小、降低不透明度并移除容器与选中项背景，只露出栏目文字；悬停或键盘聚焦时平滑恢复完整尺寸，显示栏目图标、Dock 背景和选中态视觉强调。默认停留在该顺序中的第一个非空栏目，空栏目仍可打开空画布。
-- 普通滚轮向下切到下一栏目、向上切到上一栏目并循环；持续滚动时将离散切页意图加入有界队列，浏览器合并形成的单个大幅滚轮事件也要按输入强度拆分为多个切页意图。同一节流窗口内的待处理步数必须合并为一次目标栏目切换，不能逐页挂载并加载中间栏目的资源，以免资源渲染阻塞后续滚轮输入；同时限制切页频率和最长排队距离，避免触控板惯性长时间自动翻页。点击大纲、底部“下一页”标题或自动定位资源属于显式切页，必须先取消尚未执行的滚轮队列，不能在显式切页后继续跳转；开始拖动画布或资源卡时也必须取消待处理切页，切页前必须终止旧栏目的画布拖动和 pointer capture，避免旧 viewport 写入新栏目。
+- 普通滚轮向下切到下一栏目、向上切到上一栏目并循环；持续滚动时将离散切页意图加入有界队列，浏览器合并形成的单个大幅滚轮事件也要按输入强度拆分为多个切页意图。同一节流窗口内的待处理步数必须合并为一次目标栏目切换，不能逐页挂载并加载中间栏目的资源，以免资源渲染阻塞后续滚轮输入；逻辑目标栏目在事件处理中同步推进，可见栏目和 viewport 通过 React transition 异步提交，渲染尚未完成时到达的新滚轮仍基于最新逻辑目标继续计算，渲染过程不得把目标栏目回写成旧页面。同时限制切页频率和最长排队距离，避免触控板惯性长时间自动翻页。点击大纲、底部“下一页”标题或自动定位资源属于显式切页，必须先取消尚未执行的滚轮队列，不能在显式切页后继续跳转；Ctrl/Meta 缩放、触控板缩放手势、排序切换和开始拖动画布或资源卡也必须取消待处理切页，缩放后的下一次普通滚轮应立即建立新的翻页意图。切页前必须终止旧栏目的画布拖动和 pointer capture，避免旧 viewport 写入新栏目。
 - 每种排序模式下的每个栏目画布都保留独立 viewport；首次进入该“排序模式 + 栏目”组合时按当前内容适配视口，离开后再返回则恢复该组合上次的平移和缩放。空白处拖拽平移画布，资源卡拖拽移动卡片并更新依赖线，Ctrl/Meta 缩放只作用于当前组合，不能牵动其它排序模式或栏目。
 - 依赖画布复用 `@genarrative/image-canvas-core` 的 viewport 计算，并复用现有资源卡片、布局和依赖连线模型。
 - 非空状态不使用资源分区滚动条、分区缩放或分区高度操作作为主要导航；栏目通过大纲、底部下一页标题和滚轮切换。
 - 当前栏目画布背景是无限的：用户可以将 viewport 沿 x/y 任意方向平移，画布不以资源 extent 作为导航边界，也不显示可见画布边缘。资源卡片的持久化布局坐标允许落在 `-1_000_000..=1_000_000`，用于支撑元素位于世界原点左上方；超出该范围仍拒绝写入，避免持久化非法布局。这与 viewport 能否继续平移是两层独立语义。搜索、详情卡和临时隐藏不得改变 viewport。
 - 普通滚轮切换栏目，指针拖动空白平移画布，Ctrl/Meta 缩放、复位以及容器 resize 后都必须保持同一套 viewport 数据流。只有“排序模式 + 栏目”组合首次获得可测量容器尺寸或用户显式复位时才重新适配内容；返回已访问组合、图片尺寸测量、布局拖动或资源 extent 变化只归一化并保留该组合的当前 viewport，不得意外重置用户已经完成的平移和缩放。普通平移不夹取 x/y；缩放仍受共享画布的最小/最大比例限制。初次 fit 与显式复位只使用资源卡真实包围盒，不把导航最小尺寸、原点空区或额外布局 gap 算入，并以 `16px` 紧凑留白在共享缩放上限内尽量铺满视口。
 - 资源卡拖动使用 `5px` 阈值区分点击与移动；移动期间按当前 scale 乐观换算世界坐标、显示拖动态并同步依赖线，释放时提交一次 `manuallyPlaced=true` 布局 CAS，取消则回滚预览且不提交。拖动后的释放点击不打开详情。
-- 依赖模式只在当前栏目画布内显示两端都属于该栏目的合法精确引用；装饰 SVG 与视觉隐藏的关系说明消费同一组可见边，搜索隐藏任一端点时两者同步移除。任务流仍只参与同类型布局聚类，不绘线也不进入关系说明。
+- 依赖模式只在当前栏目画布内显示两端都属于该栏目的合法精确引用；装饰 SVG 与视觉隐藏的关系说明消费同一组可见边，搜索隐藏任一端点时两者同步移除。依赖线的 viewport 测量按动画帧合并，平移和缩放只更新已挂载观察器消费的最新 viewport，不得在每次输入时重建 ResizeObserver、scroll 或 resize 监听。任务流仍只参与同类型布局聚类，不绘线也不进入关系说明。
 - 资源详情卡包含元数据、媒体预览和“编辑资源”操作，但不使用全屏 backdrop、不声明 `aria-modal=true`、不把 `focusedResource` 作为背景工具栏渲染条件。角色资源同时显示“生成动画”时，两个业务操作按钮必须使用一致样式，不能依赖 DOM 中的首按钮位置。桌面端允许继续操作背景画板；窄屏可以使用有边界的贴边卡，但背景组件必须保持挂载。
 - 完全空项目继续使用可纵向滚动的五分区展览，不挂载分页画布或依赖画布的 `overflow: hidden` 交互壳；低高度窗口在两种排序模式下都能滚动到“项目版本”。
 - 在“按依赖 / 按类型”之间切换或离开资源管理进入运行视图后返回时，恢复对应“排序模式 + 栏目”的现有 viewport，不自动触发“复位资源画布”，也不得用另一排序模式的 viewport 覆盖用户已经完成的平移和缩放。首次 fit 与用户显式复位仍使用同一套真实资源包围盒算法。