suaveplan/openspec/changes/enterprise-react-social/tasks.md

Tasks: enterprise-react-social

Change ID: enterprise-react-social Package: @suaveplan/react-social Target path: react/social/react-social Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/events, @suaveplan/logger, @suaveplan/react-translate, @suaveplan/react-ui, @suaveplan/react-rich-text, @suaveplan/react-infinite-scroll, @suaveplan/react-image, @suaveplan/data-masking

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree. Write package.json at 0.1.0, tsconfig.json, vitest.config.ts, scripts.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/events workspace:^, @suaveplan/logger workspace:^, @suaveplan/react-translate workspace:^, @suaveplan/react-ui workspace:^, @suaveplan/react-rich-text workspace:^, @suaveplan/react-infinite-scroll workspace:^, @suaveplan/react-image workspace:^, @suaveplan/data-masking workspace:^, @opentelemetry/api catalog:observability, zod catalog:forms, tslib catalog:build.

---

2. Error codes and types

• Define SocialError; codes: SOCIAL_CONNECTION_FAILED, SOCIAL_POST_FAILED, SOCIAL_SEND_FAILED.
• Define all types: SocialPost, SocialComment, SocialReaction, MentionItem, FeedOptions, PostOptions, ChatMessage, ConversationSummary, SocialProviderProps.

---

3. Services

• ConnectionManager — WebSocket relay adapter with typing indicators, online status, read receipts. Throws SocialError(SOCIAL_CONNECTION_FAILED).
• FeedManager — CRUD feed posts; pluggable ranker (chronological/algorithmic).
• PostManager — create/update/delete posts, reactions, comments, mentions.
• ConversationManager — conversation list with unread counts.
• MessageManager — DM send/receive with optimistic updates and rollback.
• SocialClient — top-level orchestrator wiring all managers to ConnectionManager.
• Write services.test.ts (≤500 lines): connection lifecycle, feed CRUD, post reactions, DM round-trip, presence events. { timeout: 10000 }.
• Write .md for each service.

---

4. Plugins

• BasePlugin — abstract plugin with name, install(manager), uninstall().
• PluginManager — registry with register/unregister/emit.
• ChatPlugin — extends BasePlugin; hooks into MessageManager for chat-specific events.
• ModerationPlugin — block-list, report, profanity filter via @suaveplan/data-masking.
• Write plugins.test.ts (≤500 lines): install/uninstall, emit propagation, moderation filter. { timeout: 5000 }.
• Write .md for each plugin.

---

5. Context

SocialProvider

• Provides SocialClient, ConnectionManager, plugin registry via React context. Accepts transport, plugins[], userId.
• useSocial() hook to consume context; throws SocialError if used outside provider.
• Write test + md.

---

6. Hooks

useFeed

• Loads feed via FeedManager; returns { posts, loading, error, refresh, loadMore }. OTel social.feed.load span.
• Write test + md.

usePost

• CRUD hook; returns { create, update, delete, react, comment }. OTel spans per action.
• Write test + md.

useChat

• useChat(conversationId) — sends/receives messages, manages MessageManager. OTel social.message.send span.
• Write test + md.

useConversations

• Lists conversations with unread counts; returns { conversations, loading, markRead }.
• Write test + md.

useMessages

• Loads messages for a conversation with pagination; returns { messages, loading, sendMessage }.
• Write test + md.

---

7. Components

Feed

• <Feed userId onPostCreate onPostClick /> — infinite-scroll feed via @suaveplan/react-infinite-scroll. useTranslation for empty state.
• Write test, stories (default, loading, empty, with-posts, playground), md.

CreatePost

• Rich-text composer via @suaveplan/react-rich-text. File attachments, mentions via @mention, post submit.
• Write test, stories (default, with-attachment, playground), md.

ChatWindow

• Full chat pane with MessageList, MessageInput, typing indicator, online status badge.
• Write test, stories (default, with-messages, typing, playground), md.

ConversationList

• Infinite-scroll list of conversations with unread badge, avatar, last-message preview.
• Write test, stories (default, with-unread, empty, playground), md.

MessageInput

• Text + emoji input with @mention support. Sends on Enter.
• Write test, stories (default, with-emoji, playground), md.

MessageList

• Virtualized message list with date separators, read receipts, reaction pills.
• Write test, stories (default, with-reactions, read-receipts, playground), md.

---

8. E2E

• e2e/social.spec.ts — Playwright:
  • Create a post; verify it appears in the feed.
  • Add a comment; verify nested comment thread renders.
  • Open DM conversation; send a message; verify delivery + read receipt.
  • Verify typing indicator appears while composing.

---

9. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-social — green.
• bunx turbo test:coverage --filter=@suaveplan/react-social — 100%.
• bun scripts/publish.ts --package @suaveplan/react-social.
• Archive change folder.