# ChatGPT-like Assistant Markdown Design

**Date:** 2026-08-10  
**Repository:** `corp-ui`  
**Status:** approved for implementation planning

## Goal

Render model responses with the readable, continuous-document presentation used
by ChatGPT while preserving the existing chat layout, streaming transport,
message persistence, retry behavior, and full-response copy action.

The first version is deliberately limited to safe presentation. It does not
execute model-produced content or introduce interactive previews.

## User experience

Only assistant messages use rich formatting. User messages remain plain text in
their existing bubbles so user-entered Markdown cannot unexpectedly change the
composer or transcript presentation.

Assistant responses render as an unboxed document in the conversation flow:

- headings establish hierarchy without oversized page-title typography;
- paragraphs use comfortable ChatGPT-like vertical rhythm and line height;
- ordered and unordered lists have clear indentation and item spacing;
- task lists, strikethrough, autolinks, and tables follow GitHub Flavored
  Markdown behavior;
- blockquotes and horizontal rules remain visually subordinate to the answer;
- inline code uses a muted compact surface;
- fenced code uses a dark code surface with a language label, syntax
  highlighting, horizontal scrolling, and a dedicated copy action;
- wide tables and code blocks scroll within the message instead of widening the
  chat column;
- the existing full-answer copy action continues to copy the original Markdown
  source, not the rendered text.

The empty streaming placeholder remains unchanged. As soon as the first text
fragment arrives, the assistant content is rendered as streaming Markdown.

## Rendering architecture

Introduce a focused client component named `AssistantMarkdown`. `ChatMessage`
delegates non-empty assistant content to it and continues to own message status,
retry, attachment, and full-response actions.

`AssistantMarkdown` uses:

- `streamdown` as the streaming-aware Markdown renderer;
- `@streamdown/code` as the only optional Streamdown plugin;
- the repository's existing shadcn color tokens and light/dark theme variables;
- scoped `.assistant-markdown` product styles for typography, tables, quotes,
  inline code, and overflow containment.

Streamdown is selected over a direct `react-markdown` composition because the
assistant content arrives incrementally. It handles incomplete and unterminated
Markdown during streaming and avoids the avoidable paragraph/code-block flicker
of a renderer designed only for completed documents. The upstream project also
provides GFM support, hardened link handling, memoized streaming updates, and an
optional Shiki-backed code plugin:
<https://github.com/vercel/streamdown>.

No backend or database change is required. Message content remains the exact
Markdown string produced by the model. Reloading a conversation renders the
same persisted string through the same component.

## Streaming behavior

`AssistantMarkdown` receives whether the message is currently streaming.
Streaming mode must:

- render partial paragraphs immediately;
- tolerate an unfinished emphasis marker, list item, table, link, or fenced
  code block without throwing;
- preserve the user's current auto-scroll behavior;
- settle into the same semantic output as a completed message once the final
  fragment arrives;
- avoid animation for users who prefer reduced motion.

The renderer must not introduce a second transport buffer or change the plain
text stream produced by `/api/chat`.

## Security boundary

Model output is untrusted content. The renderer must fail closed:

- raw HTML is never executed;
- `script`, `style`, iframe, object, embed, event attributes, and equivalent
  active content are not rendered;
- JavaScript, data, file, blob, and other non-approved link schemes are removed;
- external links use a new browsing context plus `noopener noreferrer`;
- remote images are not rendered in this version, preventing tracking requests
  and unreviewed external media loads;
- Mermaid, HTML/React preview, LaTeX, executable Python, and other active or
  plugin-driven renderers are not installed;
- code is always inert text even when its language is HTML, SVG, JavaScript, or
  shell;
- code-copy and full-answer-copy actions copy text only.

Allowed links are limited to absolute `http:` and `https:` URLs and ordinary
same-document anchors if Streamdown emits them for Markdown structure. Invalid
or unsupported links remain readable text without navigation.

## Styling

The approved direction is the visual option **ChatGPT-like**:

- no card or border around the whole assistant response;
- assistant avatar and action row remain as they are;
- readable width continues to come from `--chat-readable-width`;
- body text remains visually close to the current 14px chat scale with a
  relaxed line height;
- headings use the existing sans-serif font and restrained weight/size;
- code uses the existing mono font token;
- colors derive from shadcn variables so both light and dark themes remain
  coherent;
- focus indicators, selectable text, and minimum control targets remain
  accessible;
- the formatting does not create horizontal page scrolling at mobile widths.

## Components and ownership

### `AssistantMarkdown`

Owns Markdown parsing configuration, safe element overrides, streaming mode,
code-block rendering, code-copy state, and scoped class names.

### `ChatMessage`

Keeps ownership of user bubbles, attachments, status labels, retry, the empty
streaming placeholder, and full-response copy. It passes assistant content and
streaming status to `AssistantMarkdown`.

### Global product styles

`app/globals.css` owns the scoped `.assistant-markdown` presentation and the
minimal Streamdown Tailwind source declaration required by the package. No
generic `p`, `pre`, `table`, or heading selector may leak outside the assistant
renderer.

## Error handling

Malformed or incomplete Markdown must never replace the message with an error
surface. It remains visible as the safest text representation Streamdown can
produce. A clipboard rejection leaves the code block intact and does not expose
internal errors. Existing message-level error and retry handling remains
unchanged.

## Testing strategy

Component tests must cover real rendered behavior rather than implementation
details:

1. headings, emphasis, paragraphs, lists, quotes, separators, inline code,
   GFM task lists, and tables render with semantic elements;
2. fenced code shows an inert code block, language presentation, highlighting,
   and a code-specific copy action that copies only the source code;
3. the existing message copy action still copies the original Markdown string;
4. incomplete streaming Markdown renders without throwing and converges to the
   completed semantic result;
5. raw HTML, scripts, event attributes, dangerous URL schemes, and remote
   images cannot create active DOM or network-triggering elements;
6. approved HTTP(S) links have safe target and relationship attributes;
7. user messages continue to display Markdown characters literally;
8. the empty streaming placeholder, stopped state, retry action, attachments,
   and download error behavior remain unchanged;
9. wide code and table content is contained by horizontal scrolling classes;
10. light/dark token usage and reduced-motion behavior remain covered by static
    class/style assertions where browser layout is unavailable.

After focused component tests, the full corp-ui test suite, lint, TypeScript
check, production build, and a real minikube browser smoke must pass.

## Deployment and verification

The corp-ui image is rebuilt and rolled out without changing the Gateway,
FinOPS, Model Registry, or database schemas. The deployed smoke uses a model
response containing all supported constructs and verifies:

- progressive rendering while the response streams;
- final Markdown structure;
- code and full-response copy actions;
- safe links;
- no remote image request;
- no horizontal viewport overflow on desktop and mobile widths;
- existing retry and response-placeholder behavior.

## Out of scope

- Markdown formatting for user messages;
- model-controlled HTML;
- remote or data-URL images;
- Mermaid diagrams;
- LaTeX/math rendering;
- executable or editable code blocks;
- HTML, React, SVG, chart, or document previews;
- writing blocks, Canvas-like editing, and full-screen artifacts;
- server-side Markdown conversion or storing rendered HTML.

These can be designed separately after the safe renderer is proven in the live
chat.