feat: improve grouping perf in edgeless (#14442)

fix #14433 

#### PR Dependency Tree


* **PR #14442** 👈

This tree was auto-generated by
[Charcoal](https://github.com/danerwilliams/charcoal)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
  * Level-of-detail thumbnails for large images.
  * Adaptive pacing for snapping, distribution and other alignment work.
  * RAF coalescer utility to batch high-frequency updates.
  * Operation timing utility to measure synchronous work.

* **Improvements**
* Batch group/ungroup reparenting that preserves element order and
selection.
  * Coalesced panning and drag updates to reduce jitter.
* Connector/group indexing for more reliable updates, deletions and
sync.
  * Throttled viewport refresh behavior.

* **Documentation**
  * Docs added for RAF coalescer and measureOperation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

blocksuite/framework/std/src/__tests__/gfx/surface.unit.spec.ts

@@ -356,3 +356,63 @@ describe('convert decorator', () => {
     expect(elementModel.shapeType).toBe('rect');
   });
 });
+
+describe('surface group index cache', () => {
+  test('syncGroupChildrenIndex should replace outdated parent mappings', () => {
+    const { surfaceModel } = commonSetup();
+    const model = surfaceModel as any;
+
+    model._syncGroupChildrenIndex('group-1', ['a', 'b'], []);
+    expect(model._parentGroupMap.get('a')).toBe('group-1');
+    expect(model._parentGroupMap.get('b')).toBe('group-1');
+
+    model._syncGroupChildrenIndex('group-1', ['b', 'c']);
+    expect(model._parentGroupMap.has('a')).toBe(false);
+    expect(model._parentGroupMap.get('b')).toBe('group-1');
+    expect(model._parentGroupMap.get('c')).toBe('group-1');
+  });
+
+  test('removeGroupFromChildrenIndex should clear both child snapshot and reverse lookup', () => {
+    const { surfaceModel } = commonSetup();
+    const model = surfaceModel as any;
+
+    model._syncGroupChildrenIndex('group-2', ['x', 'y'], []);
+    model._removeGroupFromChildrenIndex('group-2');
+
+    expect(model._groupChildIdsMap.has('group-2')).toBe(false);
+    expect(model._parentGroupMap.has('x')).toBe(false);
+    expect(model._parentGroupMap.has('y')).toBe(false);
+  });
+
+  test('getGroup should recover from stale cache and update reverse lookup', () => {
+    const { surfaceModel } = commonSetup();
+    const model = surfaceModel as any;
+
+    const shapeId = surfaceModel.addElement({
+      type: 'testShape',
+    });
+    const shape = surfaceModel.getElementById(shapeId)!;
+
+    const fakeGroup = {
+      id: 'group-fallback',
+      hasChild: (element: { id: string }) => element.id === shapeId,
+    };
+
+    model._groupLikeModels.set(fakeGroup.id, fakeGroup);
+    model._parentGroupMap.set(shapeId, 'stale-group-id');
+
+    expect(surfaceModel.getGroup(shapeId)).toBe(fakeGroup);
+    expect(model._parentGroupMap.get(shapeId)).toBe(fakeGroup.id);
+    expect(model._parentGroupMap.has('stale-group-id')).toBe(false);
+
+    const otherShapeId = surfaceModel.addElement({
+      type: 'testShape',
+    });
+    model._parentGroupMap.set(otherShapeId, 'another-missing-group');
+    expect(surfaceModel.getGroup(otherShapeId)).toBeNull();
+    expect(model._parentGroupMap.has(otherShapeId)).toBe(false);
+
+    // keep one explicit check on element-based lookup path
+    expect(surfaceModel.getGroup(shape as any)).toBe(fakeGroup);
+  });
+});

blocksuite/framework/std/src/__tests__/gfx/tree.unit.spec.ts

@@ -0,0 +1,165 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import {
+  type GfxGroupCompatibleInterface,
+  gfxGroupCompatibleSymbol,
+} from '../../gfx/model/base.js';
+import type { GfxModel } from '../../gfx/model/model.js';
+import {
+  batchAddChildren,
+  batchRemoveChildren,
+  canSafeAddToContainer,
+  descendantElementsImpl,
+  getTopElements,
+} from '../../utils/tree.js';
+
+type TestElement = {
+  id: string;
+  group: TestGroup | null;
+  groups: TestGroup[];
+};
+
+type TestGroup = TestElement & {
+  [gfxGroupCompatibleSymbol]: true;
+  childIds: string[];
+  childElements: GfxModel[];
+  addChild: (element: GfxModel) => void;
+  removeChild: (element: GfxModel) => void;
+  hasChild: (element: GfxModel) => boolean;
+  hasDescendant: (element: GfxModel) => boolean;
+};
+
+const createElement = (id: string): TestElement => ({
+  id,
+  group: null,
+  groups: [],
+});
+
+const createGroup = (id: string): TestGroup => {
+  const group: TestGroup = {
+    id,
+    [gfxGroupCompatibleSymbol]: true,
+    group: null,
+    groups: [],
+    childIds: [],
+    childElements: [],
+    addChild(element: GfxModel) {
+      const child = element as unknown as TestElement;
+      if (this.childElements.includes(element)) {
+        return;
+      }
+      this.childElements.push(element);
+      this.childIds.push(child.id);
+      child.group = this;
+      child.groups = [...this.groups, this];
+    },
+    removeChild(element: GfxModel) {
+      const child = element as unknown as TestElement;
+      this.childElements = this.childElements.filter(item => item !== element);
+      this.childIds = this.childIds.filter(id => id !== child.id);
+      if (child.group === this) {
+        child.group = null;
+        child.groups = [];
+      }
+    },
+    hasChild(element: GfxModel) {
+      return this.childElements.includes(element);
+    },
+    hasDescendant(element: GfxModel) {
+      return descendantElementsImpl(
+        this as unknown as GfxGroupCompatibleInterface
+      ).includes(element);
+    },
+  };
+
+  return group;
+};
+
+describe('tree utils', () => {
+  test('batchAddChildren prefers container.addChildren and deduplicates', () => {
+    const a = createElement('a') as unknown as GfxModel;
+    const b = createElement('b') as unknown as GfxModel;
+    const container = {
+      addChildren: vi.fn(),
+      addChild: vi.fn(),
+    };
+
+    batchAddChildren(container as any, [a, a, b]);
+
+    expect(container.addChildren).toHaveBeenCalledTimes(1);
+    expect(container.addChildren).toHaveBeenCalledWith([a, b]);
+    expect(container.addChild).not.toHaveBeenCalled();
+  });
+
+  test('batchRemoveChildren falls back to container.removeChild and deduplicates', () => {
+    const a = createElement('a') as unknown as GfxModel;
+    const b = createElement('b') as unknown as GfxModel;
+    const container = {
+      removeChild: vi.fn(),
+    };
+
+    batchRemoveChildren(container as any, [a, a, b]);
+
+    expect(container.removeChild).toHaveBeenCalledTimes(2);
+    expect(container.removeChild).toHaveBeenNthCalledWith(1, a);
+    expect(container.removeChild).toHaveBeenNthCalledWith(2, b);
+  });
+
+  test('getTopElements removes descendants when ancestors are selected', () => {
+    const root = createGroup('root');
+    const nested = createGroup('nested');
+    const leafA = createElement('leaf-a');
+    const leafB = createElement('leaf-b');
+    const leafC = createElement('leaf-c');
+
+    root.addChild(leafA as unknown as GfxModel);
+    root.addChild(nested as unknown as GfxModel);
+    nested.addChild(leafB as unknown as GfxModel);
+
+    const result = getTopElements([
+      root as unknown as GfxModel,
+      nested as unknown as GfxModel,
+      leafA as unknown as GfxModel,
+      leafB as unknown as GfxModel,
+      leafC as unknown as GfxModel,
+    ]);
+
+    expect(result).toEqual([
+      root as unknown as GfxModel,
+      leafC as unknown as GfxModel,
+    ]);
+  });
+
+  test('descendantElementsImpl stops on cyclic graph', () => {
+    const groupA = createGroup('group-a');
+    const groupB = createGroup('group-b');
+    groupA.addChild(groupB as unknown as GfxModel);
+    groupB.addChild(groupA as unknown as GfxModel);
+
+    const descendants = descendantElementsImpl(groupA as unknown as any);
+
+    expect(descendants).toHaveLength(2);
+    expect(new Set(descendants).size).toBe(2);
+  });
+
+  test('canSafeAddToContainer blocks self and circular descendants', () => {
+    const parent = createGroup('parent');
+    const child = createGroup('child');
+    const unrelated = createElement('plain');
+
+    parent.addChild(child as unknown as GfxModel);
+
+    expect(
+      canSafeAddToContainer(parent as unknown as any, parent as unknown as any)
+    ).toBe(false);
+    expect(
+      canSafeAddToContainer(child as unknown as any, parent as unknown as any)
+    ).toBe(false);
+    expect(
+      canSafeAddToContainer(
+        parent as unknown as any,
+        unrelated as unknown as any
+      )
+    ).toBe(true);
+  });
+});