feat: upgrade toolchain and soften sync recovery after network blips

Bump Vite 8, matrix-js-sdk, and related deps; fix immer/vanilla-extract imports for new majors. Replace blocking sync error dialog with background recovery on wake/offline, and disable Vite auto-open in dev. Add feature handoff documentation index.
2026-07-09 01:55:09 +10:00
parent f67f08f1db
commit e058165830
61 changed files with 8456 additions and 5547 deletions
--- a/docs/handoff/features/forum/HANDOFF.md
+++ b/docs/handoff/features/forum/HANDOFF.md
@@ -0,0 +1,105 @@
+# 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