# Chat Markdown Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Render a deliberately small Markdown subset in every participant message without changing the composer or transcript data.
**Architecture:** Add one `MessageMarkdown` view beside the transcript and keep `MessageBody` responsible only for message controls and streaming state. `react-markdown` parses standard Markdown with an explicit element allowlist; a colocated stylesheet gives those elements compact rail typography.
**Tech Stack:** React 19, `react-markdown`, Tailwind theme tokens, Playwright
---
## File map
- Create `apps/web/src/chat/markdown.tsx`: safe Markdown-to-React boundary and supported-element policy.
- Create `apps/web/src/chat/markdown.css`: compact message typography using existing colour, radius and font tokens.
- Modify `apps/web/src/chat/transcript.tsx`: render member and Planner message text through `MessageMarkdown`.
- Modify `apps/web/package.json` and `bun.lock`: declare and lock `react-markdown`.
- Modify `e2e/smoke.e2e.ts`: prove both participant kinds render the chosen semantics and unsafe content stays inert.
### Task 1: Lock down the message contract
**Files:**
- Test: `e2e/smoke.e2e.ts`
- [ ] **Step 1: Add a failing browser test after the existing chat transcript tests**
````ts
test("chat renders participant Markdown without admitting document features", async ({ join, page }) => {
await injectChatHistory(page, frame => ({
...frame,
entries: [
{
id: "m1",
author: { kind: "member", handle: "maggie" },
text: [
"**Bold** and *italic* with [the docs](https://example.com).",
"",
"- first",
"- second",
"",
"1. one",
"2. two",
"",
"> quoted",
"",
"Use `bun test`.",
"",
"```ts",
"let answer = 42;",
"```",
"",
"# Ordinary message text",
"",
"",
'
',
].join("\n"),
ts: 1_700_000_000,
},
{
id: "a1",
author: { kind: "agent" },
text: "Planner wrote **strongly**.",
ts: 1_700_000_001,
},
],
}));
await join("ana");
let chat = page.locator("#pane-chat");
let member = chat.locator("[data-chat-entry]").filter({ hasText: "Bold and italic" });
let planner = chat.locator("[data-chat-entry]").filter({ hasText: "Planner wrote strongly" });
await expect(member.locator("strong")).toHaveText("Bold");
await expect(member.locator("em")).toHaveText("italic");
await expect(member.locator("ul")).toContainText("first");
await expect(member.locator("ol")).toContainText("one");
await expect(member.locator("blockquote")).toHaveText("quoted");
await expect(member.getByRole("link", { name: "the docs" })).toHaveAttribute("target", "_blank");
await expect(member.locator("p code")).toHaveText("bun test");
await expect(member.locator("pre code")).toContainText("let answer = 42;");
await expect(member.getByRole("heading", { name: "Ordinary message text" })).toHaveCount(0);
await expect(member).toContainText("Ordinary message text");
await expect(member.locator('img[src*="example.invalid"]')).toHaveCount(0);
await expect(planner.locator("strong")).toHaveText("strongly");
});
````
- [ ] **Step 2: Run the focused test and verify it fails**
Run:
```bash
bun run e2e -- --grep "chat renders participant Markdown"
```
Expected: FAIL because `strong`, `em`, lists, blockquotes, links and code elements do not yet exist in the transcript.
### Task 2: Add the safe Markdown renderer
**Files:**
- Create: `apps/web/src/chat/markdown.tsx`
- Create: `apps/web/src/chat/markdown.css`
- Modify: `apps/web/src/chat/transcript.tsx`
- Modify: `apps/web/package.json`
- Modify: `bun.lock`
- Test: `e2e/smoke.e2e.ts`
- [ ] **Step 1: Add the renderer dependency to the web workspace**
Run:
```bash
bun add react-markdown --cwd apps/web
```
Expected: `react-markdown` appears in `apps/web/package.json`; `bun.lock` records it and its parser dependencies.
- [ ] **Step 2: Create the rendering boundary**
Create `apps/web/src/chat/markdown.tsx`:
```tsx
import ReactMarkdown from "react-markdown";
import "./markdown.css";
import type { Components } from "react-markdown";
const ELEMENTS = [
"a",
"blockquote",
"br",
"code",
"em",
"h1",
"h2",
"h3",
"h4",
"h5",
"h6",
"li",
"ol",
"p",
"pre",
"strong",
"ul",
];
let paragraph: Components["p"] = ({ children }) =>
{children}
; const COMPONENTS: Components = { a: ({ children, href }) => ( {children} ), h1: paragraph, h2: paragraph, h3: paragraph, h4: paragraph, h5: paragraph, h6: paragraph, }; export function MessageMarkdown({ source }: { source: string }) { return (