---
id: TASK-44
title: 'Implement Semantic Grouping: named shape clusters with templates'
status: To Do
assignee: []
created_date: '2026-02-18 20:06'
labels:
  - feature
  - phase-3
  - ecosystem
milestone: m-1
dependencies:
  - TASK-41
references:
  - rspace-online/lib/DOMRectTransform.ts
  - rspace-online/lib/community-sync.ts
  - rspace-online/server/community-store.ts
priority: medium
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Add the ability to group shapes into named clusters that can be collapsed, moved together, and saved as reusable templates.

New file lib/group-manager.ts:
- GroupManager class: createGroup(), dissolveGroup(), addToGroup(), removeFromGroup()
- collapseGroup() / expandGroup() — hide members, show summary card
- moveGroup(groupId, dx, dy) — moves all members by delta
- saveAsTemplate() / instantiateTemplate() — serialize group as reusable JSON template

Automerge schema additions:
- doc.groups: { [groupId]: GroupData } — top-level CRDT entity
- GroupData: id, name, color, icon, memberShapeIds[], collapsed, x, y, width, height
- shapes[id].groupId: string — which group a shape belongs to

Visual rendering:
- folk-group-frame — lightweight overlay element (NOT a FolkShape), dashed border + header bar
- Recalculates bounds from member shapes on each animation frame
- Uses existing DOMRectTransform.ts for rotated shape bounding boxes
- Collapse button, group name, color indicator

Canvas.html additions:
- Rubber-band or shift-click multi-select → right-click "Group"
- Group context menu (rename, change color, collapse, save as template, dissolve)
- Template library panel for saved templates
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 GroupManager creates/dissolves groups stored in Automerge
- [ ] #2 Moving group header moves all member shapes together
- [ ] #3 Collapse hides members and shows summary card
- [ ] #4 Expand restores all members to original positions
- [ ] #5 Groups sync to remote users via Automerge
- [ ] #6 Save as template serializes group + internal arrows as JSON
- [ ] #7 Instantiate template creates new shapes from template
<!-- AC:END -->