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.