cinny/docs/handoff/features/forum/HANDOFF.md

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 card UI vs forum feed routing
• sub-rooms HANDOFF
• embed-filters HANDOFF

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