cinny/docs/handoff/features/sub-rooms/HANDOFF.md

Sub-rooms — handoff

Summary

Sub-rooms let a parent room own an ordered list of child rooms, displayed nested in the home channel list and manageable in room settings. Hierarchy is stored in Matrix room state (im.paarrot.sub_rooms), not only m.space.child, so channels can nest under a room without full space semantics.

User-facing behavior

• Nested channels under a room in Home sidebar (indented tree)
• Add Sub-Room from room nav context menu (requires power level on im.paarrot.sub_rooms)
• Room settings → Sub-rooms to reorder/remove children
• Creating a sub-room from parent updates parent's children array
• Unjoined sub-rooms show as UnjoinedSubRoomItem with join affordance

Architecture

Room state: im.paarrot.sub_rooms { children: string[] }
  → useRoomSubRooms hook
    → Home.tsx flatten tree (addRoomAndSubRooms)
    → RoomNavItem "Add Sub-Room" → CreateRoomModal
    → SubRooms.tsx settings editor
    → SpaceHierarchy.tsx (lobby) reads same state

Key files

Path	Role
cinny/src/app/hooks/useRoomSubRooms.ts	Hook + PaarrotSubRoomsContent type
cinny/src/types/matrix/room.ts	StateEvent.PaarrotSubRooms
cinny/src/app/pages/client/home/Home.tsx	Renders nested list
cinny/src/app/features/room-nav/RoomNavItem.tsx	Add sub-room action
cinny/src/app/features/room-nav/UnjoinedSubRoomItem.tsx	Unjoined child UI
cinny/src/app/features/room-settings/sub-rooms/SubRooms.tsx	Settings page
cinny/src/app/features/create-room/CreateRoomModal.tsx	Appends new room to parent state
cinny/src/app/features/lobby/SpaceHierarchy.tsx	Lobby hierarchy integration

Data model

Event	State key	Content
im.paarrot.sub_rooms	"" (empty)	{ children: string[] } — room IDs in display order

Power levels: treat like other state events; editors need state_default or explicit level for im.paarrot.sub_rooms.

Dependencies

• matrix-js-sdk state events
• Parent room must exist and user must have permission to send state

Integration points

• Home navigation: primary consumer of tree flattening
• Lobby/forums: SpaceHierarchy reads sub-rooms for display
• Create room flow: auto-updates parent on sub-room create
• Distinct from m.space.child space hierarchy (may coexist)

Testing

Manual

1. In a room where you have admin, add sub-room from nav menu.
2. Verify child appears indented under parent in Home.
3. Reorder in Room settings → Sub-rooms.
4. Leave child room; verify unjoined state UI.
5. Check lobby view shows hierarchy when applicable.

Automated

• None

Known issues & gotchas

• Only joined sub-rooms appear in home tree; unjoined listed separately
• Top-level filter: rooms that appear in any parent's children are excluded from root list
• Creating sub-room sends state event on parent — failure leaves orphan room
• StateEvent.PaarrotSubRooms as any casts in sendStateEvent — typing debt

Future work

• Sync with m.space.child for federation-friendly hierarchy
• Drag-and-drop reorder in nav (DnD exists in lobby, not necessarily sub-rooms settings)
• Depth limits / circular reference guards

Related docs

• lobby-forums HANDOFF

Add your extra things here

• Interface: PaarrotSubRoomsContent { children: string[] } in useRoomSubRooms.ts
• Permission check pattern: permissions.stateEvent(StateEvent.PaarrotSubRooms, userId)