fix(workbench): stabilize investigation presentation rendering

Keep investigation graphs stable during updates, defer expensive chart rendering, and prevent stale results when switching tasks. Adopt reference annotations and consolidate frontend documentation.

tests/browser/investigation-refresh-motion.e2e.ts

@@ -20,13 +20,19 @@ test("调查图加载与尺寸变化保持阅读位置，刷新后仍可缩放
     const renderer = investigationDiagramPlugins.mermaid.getMermaid.bind(investigationDiagramPlugins.mermaid);
     let release: (() => void) | undefined;
     let renderPending = false;
+    let holdRender = true;
+    let completedRenders = 0;
     investigationDiagramPlugins.mermaid.getMermaid = (config: unknown) => {
       const instance = renderer(config);
       return { ...instance, async render(id: string, source: string) {
-        renderPending = true;
-        await new Promise<void>((resolve) => { release = resolve; });
-        renderPending = false;
-        return instance.render(id, source);
+        if (holdRender) {
+          renderPending = true;
+          await new Promise<void>((resolve) => { release = resolve; });
+          renderPending = false;
+        }
+        const result = await instance.render(id, source);
+        completedRenders++;
+        return result;
       } };
     };
     const root = createRoot(document.getElementById("reader"));
@@ -45,6 +51,8 @@ test("调查图加载与尺寸变化保持阅读位置，刷新后仍可缩放
     ));
     Object.assign(window, { investigationFixture: {
       release: () => release?.(), pending: () => renderPending,
+      hold: (value: boolean) => { holdRender = value; },
+      completed: () => completedRenders,
       update: (next: string) => { source = next; render(); }
     }, documentHeights });
     render();
@@ -82,6 +90,22 @@ test("调查图加载与尺寸变化保持阅读位置，刷新后仍可缩放
   await diagram.getByRole("button", { name: "Zoom in", exact: true }).click();
   await expect(diagram.locator('[role="application"]')).toHaveCSS("transform", "matrix(1.1, 0, 0, 1.1, 0, 0)");
   await diagram.getByRole("button", { name: "Reset zoom and pan", exact: true }).click();
+  // A pending layout must not overwrite a newer source restored from cache.
+  await page.evaluate(() => {
+    const api = (window as unknown as { investigationFixture: { update: (source: string) => void } }).investigationFixture;
+    api.update("flowchart LR\nA[读取工单] --> B[核对监测] --> C[迟到的排版]");
+  });
+  await expect.poll(() => fixture("pending")).toBe(true);
+  await page.evaluate(() => {
+    const api = (window as unknown as { investigationFixture: { hold: (value: boolean) => void; update: (source: string) => void } }).investigationFixture;
+    api.hold(false);
+    api.update("flowchart LR\nA[读取工单] --> B[核对监测]");
+  });
+  await expect.poll(() => page.evaluate(() => (window as unknown as { investigationFixture: { completed: () => number } }).investigationFixture.completed())).toBe(3);
+  await fixture("release");
+  await expect.poll(() => page.evaluate(() => (window as unknown as { investigationFixture: { completed: () => number } }).investigationFixture.completed())).toBe(4);
+  await page.evaluate(() => new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))));
+  await expect(diagram.locator("svg .node")).toHaveCount(2);
   const checkCollapse = async (keyboard: boolean) => {
     const before = await page.locator("#reading-anchor").evaluate((element) => element.getBoundingClientRect().top);
     await diagram.getByRole("button", { name: "放大查看", exact: true }).click();