# Forum spaces — handoff

## Summary

Forum spaces provide a board-style UI for `m.forum` rooms and `forum_space` room kinds: topic sections, post feeds, thread detail, rich replies, filters, and dedicated composers. This is a large Paarrot-specific feature area separate from the card-based **Lobby** view.

## User-facing behavior

- Forum spaces open to a **feed** of posts (not the lobby card grid)
- Sections group topics (child rooms / subspaces)
- Create posts with title + rich body; threaded replies
- Board detail view, thread detail, topic search/filter bar
- Distinct composers: new post, reply, chat-style

## Architecture

```
ForumAwareSpaceLayout / ForumSpaceLayout
  → ForumFeedPage (feed sidebar + post list)
  → ForumBoardDetail / ForumThreadDetail
  → forumFeed.ts (aggregate posts from topic rooms)
  → forumTopicHelpers, forumRichText, topicSearch
Hooks: useForumBoard, useForumRoomLiveUpdates, useForumMessageReactions
```

Routing: `getSpaceDefaultPath` + `shouldShowForumLobby` in path utils / room utils.

## Key files

| Path | Role |
|------|------|
| `cinny/src/app/features/forum/ForumFeedPage.tsx` | Main feed page |
| `cinny/src/app/features/forum/ForumSpaceLayout.tsx` | Layout shell |
| `cinny/src/app/features/forum/ForumAwareSpaceLayout.tsx` | Forum vs non-forum switch |
| `cinny/src/app/features/forum/forumFeed.ts` | Post aggregation, root detection |
| `cinny/src/app/features/forum/types.ts` | ForumTopic, ForumPost, etc. |
| `cinny/src/app/features/forum/ForumBoardView.tsx` | Board listing |
| `cinny/src/app/features/forum/ForumThreadDetail.tsx` | Thread view |
| `cinny/src/app/features/forum/ForumNewPostModal.tsx` | Create post |
| `cinny/src/app/features/forum/ForumReplyComposer.tsx` | Replies |
| `cinny/src/app/features/forum/useForumBoard.ts` | Board data hook |
| `cinny/src/app/features/forum/useForumRoomLiveUpdates.ts` | Live timeline sync |
| `cinny/src/app/pages/pathUtils.ts` | Forum routing |

## Data model

| Signal | Purpose |
|--------|---------|
| `m.room.create` `type: m.forum` | Matrix forum room type |
| `im.paarrot.room.kind: forum_space` | Paarrot forum classification |
| `com.matrixsso.title` on messages | Forum post title (legacy/custom) |
| `formatted_body` with `<h1>` | Root post detection |
| `m.relates_to` threads | Replies and edits |
| `im.paarrot.sub_rooms` | Topic room hierarchy (see sub-rooms) |

## Dependencies

- `matrix-js-sdk` relations, threads, space hierarchy
- Rich text / Slate editor integration for composers
- Embed filters via `useForumMessageRenderOptions.ts`

## Integration points

- **lobby-forums**: routing chooses forum feed vs lobby
- **sub-rooms**: topic rooms may be sub-rooms
- **embed-filters**: forum message render options
- **local-api**: `isSpaceLikeRoom` treats forum as space-like

## Testing

### Manual

1. Open a `m.forum` space; verify feed UI loads.
2. Create post with title; verify appears in feed and topic room.
3. Reply in thread; verify counts and detail view.
4. Filter/search topics; verify results.
5. Compare behavior with `forum_space` room kind.

### Automated

- None

## Known issues & gotchas

- Root post detection uses **two** heuristics: `com.matrixsso.title` and `<h1>` in formatted_body
- Large `forumFeed.ts` — main complexity hotspot
- Forum vs lobby split scattered across path utils and layout components
- Edit/replace relations need careful handling (`isAnnotationRoomMessage`)

## Future work

- Standardize on one title field (MSC alignment)
- Unit tests for `isForumRootContent` and feed aggregation
- Performance for large spaces (pagination)

## Related docs

- [lobby-forums HANDOFF](../lobby-forums/HANDOFF.md) — lobby card UI vs forum feed routing
- [sub-rooms HANDOFF](../sub-rooms/HANDOFF.md)
- [embed-filters HANDOFF](../embed-filters/HANDOFF.md)

## Add your extra things here

- ~40 files under `features/forum/` — start with `forumFeed.ts` and `ForumFeedPage.tsx` when onboarding
- `annotatePostsWithRoomScope` in `forumTopicHelpers.ts` for cross-topic feed display