From 6fc6c54fac342f17e24b2c839f0e28bb603644be Mon Sep 17 00:00:00 2001
From: draedful <aschetinin@yandex-team.ru>
Date: Mon, 2 Mar 2026 19:53:58 +0300
Subject: [PATCH 1/2] ...

---
 src/components/canvas/blocks/Block.ts         | 56 ++++++++++++++++++-
 .../canvas/connections/BaseConnection.ts      | 11 ++++
 src/components/canvas/groups/index.ts         |  2 +
 src/react-components/Block.tsx                |  8 ++-
 src/store/block/Block.ts                      | 26 ++++++++-
 src/store/connection/ConnectionState.ts       |  8 +++
 src/store/group/Group.ts                      |  4 ++
 src/utils/utils/schedule.ts                   |  2 +-
 8 files changed, 109 insertions(+), 8 deletions(-)

diff --git a/src/components/canvas/blocks/Block.ts b/src/components/canvas/blocks/Block.ts
index f3a7875f..e3f1f351 100644
--- a/src/components/canvas/blocks/Block.ts
+++ b/src/components/canvas/blocks/Block.ts
@@ -118,6 +118,17 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
 
   protected hidden: boolean;
 
+  /**
+   * True when an external component (e.g. GraphBlock / React layer) has taken
+   * over rendering of this block.  Only canvas rendering is suppressed —
+   * the hit box and port positions are left intact so the rest of the canvas
+   * system (connections, selection, drag) keeps working correctly.
+   *
+   * This is intentionally separate from `hidden`, which is used for group
+   * collapse and also removes the hit box + delegates connection ports.
+   */
+  private renderDelegated = false;
+
   protected currentState(): T {
     return this.connectedState.$state.value;
   }
@@ -197,7 +208,9 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
           anchors: this.connectedState.$anchors.value,
         });
         this.updateHitBox(this.connectedState.$geometry.value);
-        this.updatePortPositions();
+        if (!this.hidden) {
+          this.updatePortPositions();
+        }
       }),
     ];
   }
@@ -250,6 +263,9 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
   }
 
   protected updatePortPositions(): void {
+    if (this.hidden) {
+      return;
+    }
     // Update input port position
     const inputPoint = this.getConnectionPoint("in");
     this.getInputPort().setPoint(inputPoint.x, inputPoint.y);
@@ -443,6 +459,16 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
     });
   }
 
+  /**
+   * Override isVisible so that willIterate() (in GraphComponent) keeps
+   * shouldRender = false while the block is hidden, even if the block's
+   * bounding rect happens to be within the camera viewport.
+   */
+  protected override isVisible(): boolean {
+    if (this.hidden || this.renderDelegated) return false;
+    return super.isVisible();
+  }
+
   protected willRender() {
     super.willRender();
 
@@ -511,10 +537,34 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
     }
   }
 
-  public setHiddenBlock(hidden: boolean) {
+  public setHiddenBlock(hidden: boolean): void {
     if (this.hidden !== hidden) {
       this.hidden = hidden;
       this.shouldRender = !hidden;
+      if (hidden) {
+        this.removeHitBox();
+      } else {
+        this.updateHitBox(this.connectedState.$geometry.value);
+        // Restore port positions to their correct values now that the block
+        // is visible again (delegatePorts() moved them while it was hidden).
+        this.updatePortPositions();
+      }
+      this.performRender();
+    }
+  }
+
+  /**
+   * Notify the canvas block that an external component (React / HTML layer) is
+   * now rendering it.  Only the canvas draw pass is suppressed — the hit box,
+   * ports, and all store state remain untouched so connections, drag, and
+   * selection keep working as usual.
+   *
+   * Use this instead of `setHiddenBlock` when the block is NOT logically
+   * hidden — it is simply displayed through a different render path.
+   */
+  public setRenderDelegated(delegated: boolean): void {
+    if (this.renderDelegated !== delegated) {
+      this.renderDelegated = delegated;
       this.performRender();
     }
   }
@@ -525,7 +575,7 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
   }
 
   protected render() {
-    if (this.hidden) {
+    if (this.hidden || this.renderDelegated) {
       return;
     }
 
diff --git a/src/components/canvas/connections/BaseConnection.ts b/src/components/canvas/connections/BaseConnection.ts
index aa728e7c..7daec9bb 100644
--- a/src/components/canvas/connections/BaseConnection.ts
+++ b/src/components/canvas/connections/BaseConnection.ts
@@ -159,10 +159,21 @@ export class BaseConnection<
       this.updatePoints();
     });
 
+    // When both endpoints are hidden (e.g. both blocks inside a collapsed group)
+    // schedule a re-render so willIterate() picks up the new isVisible() result.
+    this.subscribeSignal(this.connectedState.$hidden, () => {
+      this.performRender();
+    });
+
     // Enable hover interaction
     this.listenEvents(["mouseenter", "mouseleave"]);
   }
 
+  protected override isVisible(): boolean {
+    if (this.connectedState.$hidden.value) return false;
+    return super.isVisible();
+  }
+
   protected override handleEvent(event: MouseEvent) {
     event.stopPropagation();
     super.handleEvent(event);
diff --git a/src/components/canvas/groups/index.ts b/src/components/canvas/groups/index.ts
index 586ccbce..2cc0c861 100644
--- a/src/components/canvas/groups/index.ts
+++ b/src/components/canvas/groups/index.ts
@@ -8,6 +8,8 @@ import { Group } from "./Group";
 
 // Export components
 export { BlockGroups, Group, BlockGroupsTransferLayer };
+export { CollapsibleGroup } from "./CollapsibleGroup";
+export type { TCollapsibleGroup, TCollapseAnchorX, TCollapseAnchorY } from "./CollapsibleGroup";
 
 // Export types from BlockGroups
 export type { BlockGroupsProps, BlockGroupsContext, BlockGroupsState } from "./BlockGroups";
diff --git a/src/react-components/Block.tsx b/src/react-components/Block.tsx
index 9fad4ea8..2fdc088a 100644
--- a/src/react-components/Block.tsx
+++ b/src/react-components/Block.tsx
@@ -109,12 +109,14 @@ export const GraphBlock = <T extends TBlock>({
   useEffect(() => {
     if (!autoHideCanvas) {
       if (canvasVisible !== undefined) {
-        viewState?.setHiddenBlock(Boolean(canvasVisible));
+        // Manual control: delegate canvas rendering when canvasVisible=false
+        viewState?.setRenderDelegated(!canvasVisible);
       }
     } else {
-      viewState?.setHiddenBlock(true);
+      // Auto: suppress canvas rendering once React has mounted the block
+      viewState?.setRenderDelegated(true);
     }
-    return () => viewState?.setHiddenBlock(false);
+    return () => viewState?.setRenderDelegated(false);
   }, [viewState, canvasVisible]);
 
   /**
diff --git a/src/store/block/Block.ts b/src/store/block/Block.ts
index f4e46f84..13faafe9 100644
--- a/src/store/block/Block.ts
+++ b/src/store/block/Block.ts
@@ -140,6 +140,11 @@ export class BlockState<T extends TBlock = TBlock> {
 
   private blockView: Block;
 
+  private pendingHidden?: boolean;
+
+  /** Reactive flag that mirrors the canvas component's hidden state. */
+  public readonly $hidden = signal<boolean>(false);
+
   constructor(
     public readonly store: BlockListStore,
     block: T,
@@ -172,8 +177,27 @@ export class BlockState<T extends TBlock = TBlock> {
     }
   }
 
-  public setViewComponent(blockComponent: Block) {
+  public setViewComponent(blockComponent: Block): void {
     this.blockView = blockComponent;
+    if (this.pendingHidden !== undefined) {
+      blockComponent.setHiddenBlock(this.pendingHidden);
+      this.pendingHidden = undefined;
+    }
+  }
+
+  /**
+   * Request to hide or show this block's canvas component.
+   * Safe to call before the canvas component is mounted — the request is
+   * deferred and applied automatically in setViewComponent().
+   */
+  public requestHidden(hidden: boolean): void {
+    this.$hidden.value = hidden;
+    const canvasBlock = this.getViewComponent();
+    if (canvasBlock) {
+      canvasBlock.setHiddenBlock(hidden);
+    } else {
+      this.pendingHidden = hidden;
+    }
   }
 
   public getViewComponent() {
diff --git a/src/store/connection/ConnectionState.ts b/src/store/connection/ConnectionState.ts
index 00d4d7ae..5c4c02c5 100644
--- a/src/store/connection/ConnectionState.ts
+++ b/src/store/connection/ConnectionState.ts
@@ -147,6 +147,14 @@ export class ConnectionState<T extends TConnection = TConnection> {
     return undefined;
   });
 
+  /**
+   * True when both source and target blocks are hidden (e.g. both inside a
+   * collapsed group). When true the connection should not be rendered.
+   */
+  public readonly $hidden = computed(() => {
+    return (this.$sourceBlock.value?.$hidden.value ?? false) && (this.$targetBlock.value?.$hidden.value ?? false);
+  });
+
   public $geometry = computed(() => {
     if (!this.$sourcePort.value.lookup && !this.$targetPort.value.lookup) {
       return [this.$sourcePort.value, this.$targetPort.value];
diff --git a/src/store/group/Group.ts b/src/store/group/Group.ts
index 3941992a..64be1442 100644
--- a/src/store/group/Group.ts
+++ b/src/store/group/Group.ts
@@ -12,6 +12,10 @@ export interface TGroup {
   rect: TRect;
   selected?: boolean;
   component?: typeof Group;
+  /** Whether this group is currently collapsed */
+  collapsed?: boolean;
+  /** The rect dimensions used when collapsed, stored for expand reversal */
+  collapsedRect?: TRect;
 }
 
 export class GroupState {
diff --git a/src/utils/utils/schedule.ts b/src/utils/utils/schedule.ts
index f949aa40..7fc4e277 100644
--- a/src/utils/utils/schedule.ts
+++ b/src/utils/utils/schedule.ts
@@ -85,7 +85,7 @@ export const debounce = <T extends (...args: unknown[]) => void>(
         removeScheduler = null;
         const args = latestArgs;
         latestArgs = undefined;
-        fn(...args);
+        fn(...(args ?? []));
         if (currentRemoveScheduler) {
           currentRemoveScheduler();
         }

From dae8a23820f6b0d6f9d64b97022a6bd6c1eeacf3 Mon Sep 17 00:00:00 2001
From: draedful <aschetinin@yandex-team.ru>
Date: Mon, 2 Mar 2026 19:54:08 +0300
Subject: [PATCH 2/2] ...

---
 .claude/collapse_group.md                     |  29 ++
 e2e/tests/groups/collapsible-group.spec.ts    | 301 ++++++++++++++++
 .../canvas/groups/CollapsibleGroup.ts         | 320 ++++++++++++++++++
 .../canvas/groups/collapsible.stories.tsx     | 238 +++++++++++++
 4 files changed, 888 insertions(+)
 create mode 100644 .claude/collapse_group.md
 create mode 100644 e2e/tests/groups/collapsible-group.spec.ts
 create mode 100644 src/components/canvas/groups/CollapsibleGroup.ts
 create mode 100644 src/stories/canvas/groups/collapsible.stories.tsx

diff --git a/.claude/collapse_group.md b/.claude/collapse_group.md
new file mode 100644
index 00000000..6885c133
--- /dev/null
+++ b/.claude/collapse_group.md
@@ -0,0 +1,29 @@
+### Collapse Group
+
+Нужно научить группы блоков схлапываться и расхлапываться. 
+При схлапывании, блоки не должны удаляться, а должны лишь скрываться
+Скрытый Block не должен рисоваться на любом уровне(minimistic/schematic/detailed)
+Порты скрытых портов должны делегироваться группе
+После схлапывания, все блоки должны хлопнуть пространство по формуле
+
+``` 
+// Всевдокод
+cosnt initial = GroupGeometry(x, y, width, height);
+
+const target = GroupGeometry(x,y,width,height);
+
+const diffX = (initial.x + initial.width) - (target.x + target.width);
+const diffY = (initial.y + initial.height) - (target.y + target.height);
+
+function apply(block, diffX, diffY) {
+ block.setGeometry({x: x - diffX, y: y - diffY});
+}
+```
+
+При расхлопывании группы, пространство должно, наоборот расхлопнуться. 
+
+Группа должна схлопываться в верхний левых угол(т.е изменять только width/height)
+
+View для схлопнутой и расхлопнутой view будет различаться.
+
+Реализация должны быть в виде кастомного компонента Group который является расширением обычной компоненты группы @src/components/canvas/group/Group.ts
\ No newline at end of file
diff --git a/e2e/tests/groups/collapsible-group.spec.ts b/e2e/tests/groups/collapsible-group.spec.ts
new file mode 100644
index 00000000..26190ea9
--- /dev/null
+++ b/e2e/tests/groups/collapsible-group.spec.ts
@@ -0,0 +1,301 @@
+import { test, expect } from "@playwright/test";
+
+import { GraphPageObject } from "../../page-objects/GraphPageObject";
+
+/**
+ * Layout used across all tests:
+ *
+ *   [block-1  300x100]  [block-outer 200x100]
+ *   x=100,y=100          x=450,y=100
+ *
+ *   [block-2  300x100]
+ *   x=100,y=250
+ *
+ * Group "group-1" contains block-1 and block-2.
+ * Group rect (bounding box): { x:100, y:100, w:300, h:250 }
+ *   → right edge: 400, bottom edge: 350
+ *
+ * Collapsed rect: { x:100, y:100, w:200, h:48 }
+ *   → diffX = 400-300 = 100  (block-outer x=450 >= 400, shifts to 350)
+ *   → diffY = 350-148 = 202  (block-outer y=100 < 350, no vertical shift)
+ *
+ * Group hitbox center (expanded):  x=250, y=225  (includes padding=20 on each side)
+ * Group hitbox center (collapsed): x=200, y=124
+ *
+ * Connection: block-1 → block-outer  (tests port delegation)
+ */
+
+const BLOCKS = [
+  {
+    id: "block-1",
+    is: "Block",
+    x: 100,
+    y: 100,
+    width: 300,
+    height: 100,
+    name: "Block 1",
+    anchors: [],
+    selected: false,
+    group: "group-1",
+  },
+  {
+    id: "block-2",
+    is: "Block",
+    x: 100,
+    y: 250,
+    width: 300,
+    height: 100,
+    name: "Block 2",
+    anchors: [],
+    selected: false,
+    group: "group-1",
+  },
+  {
+    id: "block-outer",
+    is: "Block",
+    x: 450,
+    y: 100,
+    width: 200,
+    height: 100,
+    name: "Outer Block",
+    anchors: [],
+    selected: false,
+  },
+];
+
+const CONNECTIONS = [
+  {
+    id: "conn-1",
+    sourceBlockId: "block-1",
+    targetBlockId: "block-outer",
+  },
+];
+
+// World coordinates for double-clicking the group
+const GROUP_CENTER_EXPANDED = { x: 250, y: 225 };
+const GROUP_CENTER_COLLAPSED = { x: 200, y: 124 };
+
+test.describe("CollapsibleGroup", () => {
+  let graphPO: GraphPageObject;
+
+  test.beforeEach(async ({ page }) => {
+    graphPO = new GraphPageObject(page);
+
+    await graphPO.initialize({
+      blocks: BLOCKS,
+      connections: CONNECTIONS,
+    });
+
+    // Add BlockGroups layer and register group-1 with CollapsibleGroup component
+    await graphPO.page.evaluate(() => {
+      const { CollapsibleGroup, BlockGroups } = (window as any).GraphModule;
+      const graph = window.graph;
+
+      graph.addLayer(BlockGroups, { draggable: false });
+
+      graph.rootStore.groupsList.setGroups([
+        {
+          id: "group-1",
+          rect: { x: 100, y: 100, width: 300, height: 250 },
+          component: CollapsibleGroup,
+          collapsed: false,
+        },
+      ]);
+    });
+
+    await graphPO.waitForFrames(5);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Collapse
+  // ---------------------------------------------------------------------------
+
+  test("collapses group on double-click", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const collapsed = await graphPO.page.evaluate(() => {
+      return window.graph.rootStore.groupsList.getGroupState("group-1")?.$state.value.collapsed;
+    });
+
+    expect(collapsed).toBe(true);
+  });
+
+  test("group rect shrinks to collapsed size after collapse", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const rect = await graphPO.page.evaluate(() => {
+      return window.graph.rootStore.groupsList.getGroupState("group-1")?.$state.value.rect;
+    });
+
+    expect(rect.x).toBe(100);
+    expect(rect.y).toBe(100);
+    expect(rect.width).toBe(200); // DEFAULT_COLLAPSED_WIDTH
+    expect(rect.height).toBe(48); // DEFAULT_COLLAPSED_HEIGHT
+  });
+
+  test("hides group blocks on canvas after collapse", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const { b1Rendered, b2Rendered } = await graphPO.page.evaluate(() => {
+      const store = window.graph.rootStore;
+      const b1 = store.blocksList.$blocksMap.value.get("block-1");
+      const b2 = store.blocksList.$blocksMap.value.get("block-2");
+      return {
+        b1Rendered: b1?.getViewComponent()?.isRendered() ?? true,
+        b2Rendered: b2?.getViewComponent()?.isRendered() ?? true,
+      };
+    });
+
+    expect(b1Rendered).toBe(false);
+    expect(b2Rendered).toBe(false);
+  });
+
+  test("outer block (to the right) shifts inward after collapse", async () => {
+    const before = await graphPO.page.evaluate(() => {
+      const block = window.graph.rootStore.blocksList.$blocksMap.value.get("block-outer");
+      return { x: block?.$geometry.value.x, y: block?.$geometry.value.y };
+    });
+
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const after = await graphPO.page.evaluate(() => {
+      const block = window.graph.rootStore.blocksList.$blocksMap.value.get("block-outer");
+      return { x: block?.$geometry.value.x, y: block?.$geometry.value.y };
+    });
+
+    // diffX = (100+300)-(100+200) = 100; block-outer.x=450 >= 400 → shifts to 350
+    expect(after.x).toBe(before.x - 100);
+    // block-outer.y=100 < group_bottom(350) → no vertical shift
+    expect(after.y).toBe(before.y);
+  });
+
+  test("delegates hidden block ports to group center after collapse", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const result = await graphPO.page.evaluate(() => {
+      const store = window.graph.rootStore;
+      const b1 = store.blocksList.$blocksMap.value.get("block-1");
+      const canvasBlock = b1?.getViewComponent();
+      const outputPort = canvasBlock?.getOutputPort();
+      const groupRect = store.groupsList.getGroupState("group-1")?.$state.value.rect;
+
+      return {
+        portX: outputPort?.x,
+        portY: outputPort?.y,
+        groupCenterX: groupRect ? groupRect.x + groupRect.width / 2 : null,
+        groupCenterY: groupRect ? groupRect.y + groupRect.height / 2 : null,
+      };
+    });
+
+    expect(result.portX).toBe(result.groupCenterX);
+    expect(result.portY).toBe(result.groupCenterY);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Expand
+  // ---------------------------------------------------------------------------
+
+  test("expands group on double-click when collapsed", async () => {
+    // Collapse first
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    // Expand by double-clicking the collapsed group center
+    await graphPO.doubleClick(GROUP_CENTER_COLLAPSED.x, GROUP_CENTER_COLLAPSED.y, {
+      waitFrames: 5,
+    });
+
+    const collapsed = await graphPO.page.evaluate(() => {
+      return window.graph.rootStore.groupsList.getGroupState("group-1")?.$state.value.collapsed;
+    });
+
+    expect(collapsed).toBe(false);
+  });
+
+  test("group blocks are visible again after expand", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+    await graphPO.doubleClick(GROUP_CENTER_COLLAPSED.x, GROUP_CENTER_COLLAPSED.y, {
+      waitFrames: 5,
+    });
+
+    const { b1Rendered, b2Rendered } = await graphPO.page.evaluate(() => {
+      const store = window.graph.rootStore;
+      const b1 = store.blocksList.$blocksMap.value.get("block-1");
+      const b2 = store.blocksList.$blocksMap.value.get("block-2");
+      return {
+        b1Rendered: b1?.getViewComponent()?.isRendered() ?? false,
+        b2Rendered: b2?.getViewComponent()?.isRendered() ?? false,
+      };
+    });
+
+    expect(b1Rendered).toBe(true);
+    expect(b2Rendered).toBe(true);
+  });
+
+  test("outer block returns to original position after expand", async () => {
+    const initial = await graphPO.page.evaluate(() => {
+      const block = window.graph.rootStore.blocksList.$blocksMap.value.get("block-outer");
+      return { x: block?.$geometry.value.x, y: block?.$geometry.value.y };
+    });
+
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+    await graphPO.doubleClick(GROUP_CENTER_COLLAPSED.x, GROUP_CENTER_COLLAPSED.y, {
+      waitFrames: 5,
+    });
+
+    const final = await graphPO.page.evaluate(() => {
+      const block = window.graph.rootStore.blocksList.$blocksMap.value.get("block-outer");
+      return { x: block?.$geometry.value.x, y: block?.$geometry.value.y };
+    });
+
+    expect(final.x).toBe(initial.x);
+    expect(final.y).toBe(initial.y);
+  });
+
+  test("group rect is restored to full size after expand", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+    await graphPO.doubleClick(GROUP_CENTER_COLLAPSED.x, GROUP_CENTER_COLLAPSED.y, {
+      waitFrames: 5,
+    });
+
+    const rect = await graphPO.page.evaluate(() => {
+      return window.graph.rootStore.groupsList.getGroupState("group-1")?.$state.value.rect;
+    });
+
+    // Full bounding box of block-1 + block-2
+    expect(rect.x).toBe(100);
+    expect(rect.y).toBe(100);
+    expect(rect.width).toBe(300);
+    expect(rect.height).toBe(250);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Connection integrity
+  // ---------------------------------------------------------------------------
+
+  test("connection still exists between group block and outer block", async () => {
+    await graphPO.doubleClick(GROUP_CENTER_EXPANDED.x, GROUP_CENTER_EXPANDED.y, {
+      waitFrames: 5,
+    });
+
+    const exists = await graphPO.hasConnectionBetween("block-1", "block-outer");
+    expect(exists).toBe(true);
+  });
+});
diff --git a/src/components/canvas/groups/CollapsibleGroup.ts b/src/components/canvas/groups/CollapsibleGroup.ts
new file mode 100644
index 00000000..9d81c8ae
--- /dev/null
+++ b/src/components/canvas/groups/CollapsibleGroup.ts
@@ -0,0 +1,320 @@
+import { batch } from "@preact/signals-core";
+
+import { EAnchorType } from "../../../store/anchor/Anchor";
+import { BlockState } from "../../../store/block/Block";
+import { TGroup } from "../../../store/group/Group";
+import { getBlocksRect } from "../../../utils/functions";
+import { TRect } from "../../../utils/types/shapes";
+
+import { BlockGroups } from "./BlockGroups";
+import { Group, TGroupProps } from "./Group";
+
+/** Horizontal anchor: which X-axis point of the full rect stays fixed during collapse. */
+export type TCollapseAnchorX = "left" | "center" | "right";
+
+/** Vertical anchor: which Y-axis point of the full rect stays fixed during collapse. */
+export type TCollapseAnchorY = "top" | "center" | "bottom";
+
+export interface TCollapsibleGroup extends TGroup {
+  /** Whether this group is currently collapsed */
+  collapsed?: boolean;
+  /**
+   * The rect used when collapsed, stored so expand() can compute the reverse
+   * shift even after a page reload with collapsed: true.
+   */
+  collapsedRect?: TRect;
+  /**
+   * The full rect before collapsing (including any padding around blocks).
+   * Stored on collapse so expand() can restore the exact original rect rather
+   * than recomputing a tight bounding box from block positions.
+   */
+  expandedRect?: TRect;
+  /**
+   * Horizontal anchor point for collapse (default: "left").
+   * "left"   → top-left corner is pinned (freed space is to the right)
+   * "center" → group shrinks symmetrically from both sides
+   * "right"  → top-right corner is pinned (freed space is to the left)
+   */
+  collapseAnchorX?: TCollapseAnchorX;
+  /**
+   * Vertical anchor point for collapse (default: "top").
+   * "top"    → top edge is pinned (freed space is below)
+   * "center" → group shrinks symmetrically from both sides
+   * "bottom" → bottom edge is pinned (freed space is above)
+   */
+  collapseAnchorY?: TCollapseAnchorY;
+}
+
+const DEFAULT_COLLAPSED_WIDTH = 200;
+const DEFAULT_COLLAPSED_HEIGHT = 48;
+
+const ANCHOR_X_FACTOR: Record<TCollapseAnchorX, number> = { left: 0, center: 0.5, right: 1 };
+const ANCHOR_Y_FACTOR: Record<TCollapseAnchorY, number> = { top: 0, center: 0.5, bottom: 1 };
+
+/**
+ * A Group component that supports collapsing and expanding.
+ *
+ * When collapsed:
+ * - All blocks in the group are hidden (not deleted from the store)
+ * - Connection ports of hidden blocks are redirected to the group edges
+ * - The group rect shrinks to a compact header, pinned at the configured anchor
+ * - Surrounding blocks shift inward to fill the freed space
+ *
+ * When expanded, all of the above is reversed.
+ *
+ * Toggle collapse/expand by double-clicking the group.
+ *
+ * ### Collapse anchor
+ *
+ * Set `collapseAnchorX` / `collapseAnchorY` on the TCollapsibleGroup data to
+ * control where the shrunken header appears:
+ *
+ * ```
+ *  collapseAnchorX: "left"   → header at left edge   (freed space on the right)
+ *  collapseAnchorX: "center" → header at center       (freed space on both sides)
+ *  collapseAnchorX: "right"  → header at right edge   (freed space on the left)
+ *  collapseAnchorY: "top"    → header at top edge     (freed space below)
+ *  collapseAnchorY: "center" → header at center       (freed space above & below)
+ *  collapseAnchorY: "bottom" → header at bottom edge  (freed space above)
+ * ```
+ *
+ * Default: `"left"` / `"top"` — same as the original behaviour.
+ *
+ * ### Usage
+ * ```typescript
+ * const group: TCollapsibleGroup = {
+ *   id: "my-group",
+ *   rect: { x: 0, y: 0, width: 0, height: 0 }, // auto-computed from blocks
+ *   component: CollapsibleGroup,
+ *   collapsed: false,
+ *   collapseAnchorX: "left",
+ *   collapseAnchorY: "top",
+ * };
+ * ```
+ * Blocks must carry `group: "my-group"` in their TBlock data.
+ */
+export class CollapsibleGroup<T extends TCollapsibleGroup = TCollapsibleGroup> extends Group<T> {
+  constructor(props: TGroupProps, parent: BlockGroups) {
+    super(props, parent);
+
+    this.addEventListener("dblclick", (event: MouseEvent) => {
+      event.stopPropagation();
+      this.toggleCollapsed();
+    });
+  }
+
+  /**
+   * Extend base subscription to also react to collapsed state on init.
+   * subscribeSignal fires immediately with the current value, so a group
+   * that starts with collapsed: true will hide its blocks on mount.
+   */
+  protected override subscribeToGroup(): ReturnType<Group["subscribeToGroup"]> {
+    const unsub = super.subscribeToGroup();
+
+    this.subscribeSignal(this.groupState.$state, (group: T) => {
+      if (group.collapsed) {
+        this.applyBlockVisibility(true);
+        this.delegatePorts();
+      }
+    });
+
+    return unsub;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  private getGroupBlocks(): BlockState[] {
+    return this.context.graph.rootStore.groupsList.$blockGroups.value[this.props.id] ?? [];
+  }
+
+  private toggleCollapsed(): void {
+    const collapsed = (this.groupState.$state.value as T).collapsed ?? false;
+    if (collapsed) {
+      this.expand();
+    } else {
+      this.collapse();
+    }
+  }
+
+  /**
+   * Compute the collapsed rect for a given full rect, respecting the configured
+   * collapseAnchorX / collapseAnchorY values.
+   *
+   * The anchor point in the full rect is mapped to the same anchor point in
+   * the collapsed rect, so the "pinned" corner/edge does not move.
+   */
+  private computeCollapsedRect(fullRect: TRect): TRect {
+    const state = this.groupState.$state.value as T;
+    const ax = ANCHOR_X_FACTOR[state.collapseAnchorX ?? "left"];
+    const ay = ANCHOR_Y_FACTOR[state.collapseAnchorY ?? "top"];
+    return {
+      x: fullRect.x + ax * (fullRect.width - DEFAULT_COLLAPSED_WIDTH),
+      y: fullRect.y + ay * (fullRect.height - DEFAULT_COLLAPSED_HEIGHT),
+      width: DEFAULT_COLLAPSED_WIDTH,
+      height: DEFAULT_COLLAPSED_HEIGHT,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Collapse
+  // ---------------------------------------------------------------------------
+
+  public collapse(): void {
+    const groupBlocks = this.getGroupBlocks();
+    if (groupBlocks.length === 0) return;
+
+    const fullRect = this.groupState.$state.value.rect;
+    const collapsedRect = this.computeCollapsedRect(fullRect);
+
+    // Prevent withBlockGrouping auto-rect from overriding the collapsed rect
+    this.groupState.lockSize();
+
+    batch(() => {
+      // 1. Hide all blocks inside the group
+      this.applyBlockVisibility(true);
+
+      // 2. Redirect their ports to the collapsed group edges
+      this.delegatePorts(collapsedRect);
+
+      // 3. Shrink group rect and persist state.
+      //    expandedRect stores the full rect (with any padding) so expand()
+      //    can restore it exactly instead of recomputing from block positions.
+      this.groupState.updateGroup({
+        rect: collapsedRect,
+        collapsed: true,
+        collapsedRect: collapsedRect,
+        expandedRect: fullRect,
+      } as Partial<T>);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Expand
+  // ---------------------------------------------------------------------------
+
+  public expand(): void {
+    const state = this.groupState.$state.value as T;
+    const groupBlocks = this.getGroupBlocks();
+
+    // Prefer the stored full rect (preserves original padding around blocks).
+    // Fall back to recomputing from block positions only if the group was
+    // created with collapsed: true (no expandedRect persisted yet).
+    const fullRect =
+      state.expandedRect ?? getBlocksRect(groupBlocks.map((b) => b.asTBlock()));
+
+    // Re-enable withBlockGrouping auto-rect now that blocks will be visible again
+    this.groupState.unlockSize();
+
+    batch(() => {
+      // 1. Restore block visibility (they resume managing their own ports)
+      this.applyBlockVisibility(false);
+
+      // 2. Restore group rect and clear collapsed state
+      this.groupState.updateGroup({
+        rect: fullRect,
+        collapsed: false,
+        collapsedRect: undefined,
+        expandedRect: undefined,
+      } as Partial<T>);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Block shifting (reserved for future implementation)
+  // ---------------------------------------------------------------------------
+
+  // TODO: implement shiftOuterBlocks — shift surrounding blocks and groups
+  // inward on collapse and outward on expand.
+
+  // ---------------------------------------------------------------------------
+  // Block visibility
+  // ---------------------------------------------------------------------------
+
+  private applyBlockVisibility(hidden: boolean): void {
+    this.getGroupBlocks().forEach((blockState) => {
+      blockState.requestHidden(hidden);
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Port delegation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Redirect all ports of group blocks to the edges of targetRect (or the
+   * current group rect when no rect is provided).
+   *
+   * - Input port  → left-center edge  (rect.x,           rect.y + height/2)
+   * - Output port → right-center edge (rect.x + width,   rect.y + height/2)
+   * - IN anchors  → left-center edge
+   * - OUT anchors → right-center edge
+   */
+  private delegatePorts(targetRect?: TRect): void {
+    const rect = targetRect ?? this.groupState.$state.value.rect;
+    const leftX = rect.x;
+    const rightX = rect.x + rect.width;
+    const midY = rect.y + rect.height / 2;
+
+    this.getGroupBlocks().forEach((blockState) => {
+      const canvasBlock = blockState.getViewComponent();
+      if (!canvasBlock) return;
+
+      canvasBlock.getInputPort()?.setPoint(leftX, midY);
+      canvasBlock.getOutputPort()?.setPoint(rightX, midY);
+
+      blockState.$anchors.value.forEach((anchor) => {
+        const x = anchor.type === EAnchorType.OUT ? rightX : leftX;
+        canvasBlock.getAnchorPort(anchor.id)?.setPoint(x, midY);
+      });
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Rendering
+  // ---------------------------------------------------------------------------
+
+  protected override render(): void {
+    const collapsed = (this.state as T).collapsed ?? false;
+    if (collapsed) {
+      this.renderCollapsedView(this.context.ctx);
+    } else {
+      super.render();
+    }
+  }
+
+  /**
+   * Render the compact header shown when the group is collapsed.
+   * Override this method to customise the collapsed appearance.
+   */
+  protected renderCollapsedView(ctx: CanvasRenderingContext2D): void {
+    const rect = this.getRect();
+
+    if (this.isHighlighted()) {
+      ctx.strokeStyle = this.style.highlightedBorder;
+      ctx.fillStyle = this.style.highlightedBackground;
+    } else if (this.state.selected) {
+      ctx.strokeStyle = this.style.selectedBorder;
+      ctx.fillStyle = this.style.selectedBackground;
+    } else {
+      ctx.strokeStyle = this.style.border;
+      ctx.fillStyle = this.style.background;
+    }
+
+    ctx.lineWidth = this.style.borderWidth;
+
+    ctx.beginPath();
+    ctx.roundRect(rect.x, rect.y, rect.width, rect.height, 8);
+    ctx.fill();
+    ctx.stroke();
+
+    // Label with collapse indicator
+    const label = `[−] ${String(this.props.id)}`;
+    ctx.fillStyle = "#ffffff";
+    ctx.font = "bold 12px sans-serif";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, rect.x + rect.width / 2, rect.y + rect.height / 2, rect.width - 16);
+  }
+}
diff --git a/src/stories/canvas/groups/collapsible.stories.tsx b/src/stories/canvas/groups/collapsible.stories.tsx
new file mode 100644
index 00000000..36c6396b
--- /dev/null
+++ b/src/stories/canvas/groups/collapsible.stories.tsx
@@ -0,0 +1,238 @@
+import React, { useEffect } from "react";
+
+import type { Meta, StoryFn } from "@storybook/react-webpack5";
+
+import { BlockGroups, CollapsibleGroup } from "../../../components/canvas/groups";
+import type { BlockGroupsProps, BlockState } from "../../../components/canvas/groups";
+import type { TCollapsibleGroup } from "../../../components/canvas/groups/CollapsibleGroup";
+import { Graph, GraphState, TBlock, TConnection } from "../../../index";
+import { GraphCanvas, useGraph, useGraphEvent } from "../../../react-components";
+import { useFn } from "../../../react-components/utils/hooks/useFn";
+import { BlockStory } from "../../main/Block";
+
+// ---------------------------------------------------------------------------
+// Wide-group layout
+//
+//  [L-A] ──────────────────────────────────────────── [R-A]
+//          ┌──────────────────────────────────────┐
+//          │  GROUP A   [A1]   [A2]   [A3]       │
+//          └──────────────────────────────────────┘
+//
+//               ┌──────────────────────────────────────┐
+//               │  GROUP B   [B1]   [B2]   [B3]       │
+//               └──────────────────────────────────────┘
+//  [L-B] ──────────────────────────────────────────────── [R-B]
+//
+// Group rects are auto-computed via withBlockGrouping: whenever blocks inside
+// a group move, the group border follows automatically. On collapse, the size
+// is locked so the compact header stays; on expand, the lock is released and
+// the rect snaps back to the block bounding box.
+//
+// Double-click any group to collapse it.  Surrounding blocks shift inward.
+// Double-click the collapsed header to expand.
+// ---------------------------------------------------------------------------
+
+const BLOCK_W = 200;
+const BLOCK_H = 100;
+const GROUP_PAD = 60;
+const COL_GAP = 80;
+const ROW_GAP = 200;
+const OUTER_GAP = 80;
+
+// ---------------------------------------------------------------------------
+// Group A inner blocks  (row y = 0)
+// ---------------------------------------------------------------------------
+const GA_COUNT = 3;
+const GA_Y = 0;
+const GA_X0 = 600;
+
+const GA_BLOCKS: TBlock[] = Array.from({ length: GA_COUNT }, (_, i) => ({
+  id: `ga-${i + 1}`,
+  is: "Block" as const,
+  name: `A${i + 1}`,
+  selected: false,
+  x: GA_X0 + i * (BLOCK_W + COL_GAP),
+  y: GA_Y,
+  width: BLOCK_W,
+  height: BLOCK_H,
+  anchors: [],
+  group: "group-a",
+}));
+
+// ---------------------------------------------------------------------------
+// Group B inner blocks  (row y = ROW_GAP + BLOCK_H, shifted right)
+// ---------------------------------------------------------------------------
+const GB_COUNT = 3;
+const GB_Y = GA_Y + BLOCK_H + ROW_GAP;
+const GB_X0 = GA_X0 + BLOCK_W + COL_GAP; // one column to the right
+
+const GB_BLOCKS: TBlock[] = Array.from({ length: GB_COUNT }, (_, i) => ({
+  id: `gb-${i + 1}`,
+  is: "Block" as const,
+  name: `B${i + 1}`,
+  selected: false,
+  x: GB_X0 + i * (BLOCK_W + COL_GAP),
+  y: GB_Y,
+  width: BLOCK_W,
+  height: BLOCK_H,
+  anchors: [],
+  group: "group-b",
+}));
+
+// ---------------------------------------------------------------------------
+// Bounding boxes for the two groups (used to position outer blocks)
+// ---------------------------------------------------------------------------
+const GA_RIGHT = GA_X0 + GA_COUNT * (BLOCK_W + COL_GAP) - COL_GAP; // right edge of last A block
+const GB_RIGHT = GB_X0 + GB_COUNT * (BLOCK_W + COL_GAP) - COL_GAP;
+
+// ---------------------------------------------------------------------------
+// Outer "chain" blocks – one on each side of each group row
+// ---------------------------------------------------------------------------
+const OUTER_BLOCKS: TBlock[] = [
+  {
+    id: "outer-l-a",
+    is: "Block" as const,
+    name: "L-A",
+    selected: false,
+    x: GA_X0 - GROUP_PAD - OUTER_GAP - BLOCK_W,
+    y: GA_Y,
+    width: BLOCK_W,
+    height: BLOCK_H,
+    anchors: [],
+  },
+  {
+    id: "outer-r-a",
+    is: "Block" as const,
+    name: "R-A",
+    selected: false,
+    x: GA_RIGHT + GROUP_PAD + OUTER_GAP,
+    y: GA_Y,
+    width: BLOCK_W,
+    height: BLOCK_H,
+    anchors: [],
+  },
+  {
+    id: "outer-l-b",
+    is: "Block" as const,
+    name: "L-B",
+    selected: false,
+    x: GB_X0 - GROUP_PAD - OUTER_GAP - BLOCK_W,
+    y: GB_Y,
+    width: BLOCK_W,
+    height: BLOCK_H,
+    anchors: [],
+  },
+  {
+    id: "outer-r-b",
+    is: "Block" as const,
+    name: "R-B",
+    selected: false,
+    x: GB_RIGHT + GROUP_PAD + OUTER_GAP,
+    y: GB_Y,
+    width: BLOCK_W,
+    height: BLOCK_H,
+    anchors: [],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Connections
+// ---------------------------------------------------------------------------
+const CONNECTIONS: TConnection[] = [
+  { id: "c-la-a1", sourceBlockId: "outer-l-a", targetBlockId: "ga-1" },
+  { id: "c-a3-ra", sourceBlockId: `ga-${GA_COUNT}`, targetBlockId: "outer-r-a" },
+  { id: "c-lb-b1", sourceBlockId: "outer-l-b", targetBlockId: "gb-1" },
+  { id: "c-b3-rb", sourceBlockId: `gb-${GB_COUNT}`, targetBlockId: "outer-r-b" },
+  // Cross-connection to see port delegation when collapsed
+  { id: "c-a2-b2", sourceBlockId: "ga-2", targetBlockId: "gb-2" },
+];
+
+const ALL_BLOCKS: TBlock[] = [...GA_BLOCKS, ...GB_BLOCKS, ...OUTER_BLOCKS];
+
+// ---------------------------------------------------------------------------
+// Auto-grouping class — groups are derived from block.group field, rect is
+// recomputed automatically as blocks move (with GROUP_PAD padding).
+// On collapse, CollapsibleGroup calls groupState.lockSize() so this computed
+// rect doesn't override the compact header; on expand, lockSize() is released.
+// ---------------------------------------------------------------------------
+const CollapsibleBlockGroups = BlockGroups.withBlockGrouping<BlockGroupsProps, BlockGroups>({
+  groupingFn: (blocks: BlockState[]): Record<string, BlockState[]> => {
+    const result: Record<string, BlockState[]> = {};
+    blocks.forEach((block) => {
+      const groupId = block.$state.value.group;
+      if (groupId) {
+        if (!result[groupId]) result[groupId] = [];
+        result[groupId].push(block);
+      }
+    });
+    return result;
+  },
+  mapToGroups: (_key, { rect }): TCollapsibleGroup => ({
+    id: _key,
+    rect: {
+      x: rect.x - GROUP_PAD,
+      y: rect.y - GROUP_PAD,
+      width: rect.width + GROUP_PAD * 2,
+      height: rect.height + GROUP_PAD * 2,
+    },
+    component: CollapsibleGroup,
+    collapseAnchorX: "left",
+    collapseAnchorY: "top",
+    // `collapsed` is intentionally omitted: existing state is preserved by
+    // updateGroup()'s spread, and newly created groups default to false.
+  }),
+});
+
+// ---------------------------------------------------------------------------
+// Story component
+// ---------------------------------------------------------------------------
+
+const CollapsibleGroupsApp = () => {
+  const { graph, setEntities, start } = useGraph({});
+
+  useEffect(() => {
+    const blockGroups = graph.addLayer(CollapsibleBlockGroups, {});
+    return () => {
+      blockGroups.detachLayer();
+    };
+  }, [graph]);
+
+  useGraphEvent(graph, "state-change", ({ state }) => {
+    if (state === GraphState.ATTACHED) {
+      setEntities({ blocks: ALL_BLOCKS, connections: CONNECTIONS });
+      start();
+      graph.zoomTo("center", { padding: 150 });
+    }
+  });
+
+  const renderBlockFn = useFn((graphObject: Graph, block: TBlock) => (
+    <BlockStory graph={graphObject} block={block} />
+  ));
+
+  return <GraphCanvas className="graph" graph={graph} renderBlock={renderBlockFn} />;
+};
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: "Canvas/Groups",
+  component: CollapsibleGroupsApp,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Two wide `CollapsibleGroup` instances with outer blocks on both sides. " +
+          "Group rects are auto-computed from block positions via `withBlockGrouping`. " +
+          "**Double-click** a group to collapse it: blocks hide, connections redirect " +
+          "to group edges, outer blocks shift inward. Double-click the header to expand.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const CollapsibleGroups: StoryFn = () => <CollapsibleGroupsApp />;
+CollapsibleGroups.storyName = "Collapsible Groups";