# OpenSpec Change: enterprise-react-rich-text

- **Change ID**: enterprise-react-rich-text
- **Package**: `@suaveplan/react-rich-text`
- **Category**: react
- **Target path**: `react/media/react-rich-text`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-rich-text.md`

---

## Summary

Deliver `@suaveplan/react-rich-text` on genesis from scratch at enterprise quality. Tiptap-based rich-text WYSIWYG: `RichTextEditor` (composite), `EditorEngine`, `Toolbar`, `EditorContent`, `SlashCommandMenu`, `MentionList`, `BubbleMenu`, hooks (`useRichText`, `useMentions`, `useSlashCommands`), markdown round-trip, slash-command registry, and typed state. Genesis adds the missing `BubbleMenu` story, extends test coverage to 100%, and adds Playwright E2E.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `RichTextError` |
| `@suaveplan/react-translate` (`workspace:^`) | i18n for toolbar/placeholder |
| `zod` (`catalog:forms`) | Config schemas |
| `@opentelemetry/api` (`catalog:observability`) | `rich_text.submit` span |

External: `@tiptap/core catalog:editor`, `@tiptap/react catalog:editor`, `@tiptap/starter-kit catalog:editor`, `@tiptap/extension-mention catalog:editor`, `@tiptap/extension-placeholder catalog:editor`, `@tiptap/extension-link catalog:editor`, `@tiptap/pm catalog:editor`, `@tiptap/suggestion catalog:editor`, `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
RichTextEditor, EditorContent, Toolbar, BubbleMenu, SlashCommandMenu, MentionList
useRichText, useMentions, useSlashCommands
htmlToMarkdown, markdownToHtml
filterSlashCommands, groupCommandsByCategory, executeSlashCommand

// Types
FormatState, FormatMark, BlockType, HeadingLevel, MarkdownShortcutRule,
MentionItem, SlashCommand, SlashCommandCategory
```

---

## New additions for genesis

1. **`RichTextError`** — codes: `RICH_TEXT_INIT_FAILED`, `RICH_TEXT_PARSE_FAILED`.
2. **`BubbleMenu` story** — default, formatting, playground.
3. **100% test coverage** — all branches in `editor-engine` and all hooks.
4. **Playwright E2E** — type text, apply bold, verify output; type `/` → slash menu; type `@` → mention list.

---

## File layout

```text
react/media/react-rich-text/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    editor-engine/ (ts + types + md + test + index)
    editor-content/ (tsx + types + md + test + stories + index)
    toolbar/ (tsx + types + md + test + stories + index)
    bubble-menu/ (tsx + types + md + test + stories + index)
    slash-command-menu/ (tsx + types + md + test + stories + index)
    mention-list/ (tsx + types + md + test + stories + index)
    rich-text-editor/ (tsx + types + md + test + stories + index)
    hooks/
      use-rich-text/ use-mentions/ use-slash-commands/
    types/
  e2e/
    rich-text.spec.ts
```