@djangocfg/ui-tools 2.1.302 → 2.1.304

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.302",
+  "version": "2.1.304",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -91,8 +91,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.302",
-    "@djangocfg/ui-core": "^2.1.302",
+    "@djangocfg/i18n": "^2.1.304",
+    "@djangocfg/ui-core": "^2.1.304",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -129,9 +129,13 @@
     "react-map-gl": "^8.1.0",
     "react-markdown": "10.1.0",
     "react-zoom-pan-pinch": "^3.7.0",
+    "rehype-external-links": "^3.0.0",
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-emoji": "^5.0.2",
     "remark-gfm": "4.0.1",
+    "remark-smartypants": "^3.0.2",
     "vidstack": "next",
     "wavesurfer.js": "^7.12.1"
   },
@@ -140,10 +144,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.302",
+    "@djangocfg/i18n": "^2.1.304",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.302",
-    "@djangocfg/ui-core": "^2.1.302",
+    "@djangocfg/typescript-config": "^2.1.304",
+    "@djangocfg/ui-core": "^2.1.304",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/components/markdown/MarkdownMessage/CodeBlock.tsx

@@ -19,18 +19,34 @@ interface CodeBlockProps {
  * branch below still ships its own button because the plain <pre>
  * has no toolbar of its own.
  */
-export const CodeBlock: React.FC<CodeBlockProps> = ({ code, language, isUser, isCompact = false }) => {
+export const CodeBlock: React.FC<CodeBlockProps> = ({ code, language, isCompact = false }) => {
   const theme = useResolvedTheme();
 
+  // Hoist derived values out of JSX (COMPONENTS.md
+  // "Data Preparation Before Render"):
+  //   `textSizeClass` — chat-density font tier, so the JSX line
+  //                     stays a one-liner.
+  // The `--code` token (ui-core/styles/theme/tokens.css) handles the
+  // palette in both themes / both bubble roles; we don't branch on
+  // `isUser` here on purpose.
+  const textSizeClass = isCompact ? 'text-xs' : 'text-sm';
+
   return (
     <div className="my-3">
       <PrettyCode
         data={code}
         language={language}
-        className={isCompact ? 'text-xs' : 'text-sm'}
-        customBg={isUser ? 'bg-white/10' : 'bg-muted dark:bg-muted'}
+        className={textSizeClass}
+        customBg="bg-code"
         mode={theme}
         isCompact={isCompact}
+        // Disable click-to-scroll-isolation in chat markdown: code
+        // fences here are part of an assistant reply, not a docs
+        // viewer. Forcing the user to click into a small block to
+        // scroll past it interrupts the reading flow. The standalone
+        // PrettyCode use cases (docs, diff viewers, long code panes)
+        // keep the default `true`.
+        scrollIsolation={false}
       />
     </div>
   );
@@ -38,26 +54,27 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({ code, language, isUser, is
 
 /** Simple `<pre>` fallback used when CodeBlock throws (lazy module
  *  failure, missing PrettyCode peer, etc). */
-export const CodeBlockFallback: React.FC<CodeBlockProps> = ({ code, isUser }) => (
-  <div className="relative group my-3">
-    <CopyButton
-      value={code}
-      variant="ghost"
-      className={`
-        absolute top-2 right-2 z-10 opacity-0 group-hover:opacity-100 transition-opacity
-        h-8 w-8
-        ${isUser
-          ? 'hover:bg-white/20 text-white'
-          : 'hover:bg-muted-foreground/20 text-muted-foreground hover:text-foreground'
-        }
-      `}
-      title="Copy code"
-    />
-    <pre className={`
-      p-3 rounded text-xs font-mono overflow-x-auto
-      ${isUser ? 'bg-white/10 text-white' : 'bg-muted text-foreground'}
-    `}>
-      <code>{code}</code>
-    </pre>
-  </div>
-);
+export const CodeBlockFallback: React.FC<CodeBlockProps> = ({ code, isUser }) => {
+  // See CodeBlock above for the spirit of this layout — palette
+  // pre-computed before render.
+  const copyHoverClass = isUser
+    ? 'hover:bg-white/20 text-white'
+    : 'hover:bg-muted-foreground/20 text-muted-foreground hover:text-foreground';
+  const copyButtonClass =
+    `absolute top-2 right-2 z-10 opacity-0 group-hover:opacity-100 transition-opacity ` +
+    `h-8 w-8 ${copyHoverClass}`;
+
+  return (
+    <div className="relative group my-3">
+      <CopyButton
+        value={code}
+        variant="ghost"
+        className={copyButtonClass}
+        title="Copy code"
+      />
+      <pre className="p-3 rounded text-xs font-mono overflow-x-auto bg-code text-code-foreground border border-code-border">
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+};

package/src/components/markdown/MarkdownMessage/MarkdownMessage.story.tsx

@@ -213,6 +213,117 @@ curl -sSL cmdop.com/install.sh | bash
 
 Если что-то не работает — скажи.`;
 
+// Mermaid payload — exercises the `mermaid` fence branch in
+// components.tsx (lines 101–106). MarkdownMessage hands the code body
+// to <Mermaid> instead of PrettyCode when the fence language is
+// `mermaid`. We pick a small flowchart + a sequence diagram so the
+// story reflects what an LLM typically emits.
+const MERMAID_CONTENT = `Here's the chat session lifecycle:
+
+\`\`\`mermaid
+flowchart LR
+  A[User types] --> B[ChatProvider]
+  B --> C{streaming?}
+  C -->|yes| D[CancelMessage]
+  C -->|no| E[SendMessage]
+  D --> E
+  E --> F[Agent stream]
+  F --> G[Tokens arrive]
+  G --> H[Reducer dispatch]
+  H --> I[Bubble re-renders]
+\`\`\`
+
+And the cancel flow as a sequence:
+
+\`\`\`mermaid
+sequenceDiagram
+  participant U as User
+  participant C as ChatInput
+  participant P as ChatProvider
+  participant S as ChatService
+  U->>C: Press Enter (mid-stream)
+  C->>P: sendMessage(text)
+  P->>S: CancelMessage
+  S-->>P: STREAM_CANCELLED
+  P->>S: SendMessage(text)
+  S-->>P: STREAM_START
+\`\`\`
+
+The renderer routes \`mermaid\` fences to the diagram component;
+non-mermaid fences (above) keep going through PrettyCode.`;
+
+// Kitchen-sink: every block element the renderer can produce, in one
+// payload, so any spacing regression is visible at a glance. Pairs
+// neighbouring elements that are easy to break — `p → hr → p`,
+// `code → list`, `list → table → list`, blockquote-with-paragraphs.
+const KITCHEN_SINK = `# Top-level heading
+
+Short intro paragraph that sits right under the heading. The next
+paragraph should have a clear gap from this one, not be glued to it.
+
+Second paragraph — verifies \`p + p\` spacing.
+
+---
+
+After the divider, the next paragraph should still breathe. The
+divider itself is a soft hairline, not a heavy 1px gray bar.
+
+## Subheading h2
+
+Plain *italic*, **bold**, and \`inline code\` mid-sentence. Inline
+code should sit on the line, not push it taller.
+
+### Subheading h3
+
+A short list:
+
+- Bullet one with a [link](https://example.com)
+- Bullet two with \`inline code\`
+- Bullet three — short
+
+A numbered list:
+
+1. First step
+2. Second step with **bold** inside
+3. Third step
+
+A loose list (paragraph-wrapped \`<li>\`):
+
+- First item
+
+  with a follow-up paragraph that should NOT explode the list.
+
+- Second item, also loose.
+
+#### Heading h4
+
+> Blockquote without italic, with a left border. Lighter colour for
+> de-emphasis. Multi-line quotes wrap cleanly.
+>
+> Second paragraph inside the same blockquote.
+
+A code fence:
+
+\`\`\`go
+func add(a, b int) int {
+    // verifies code block spacing, rounded corners, dark bg
+    return a + b
+}
+\`\`\`
+
+A table — wraps inside a horizontally scrollable container:
+
+| Field | Type | Notes |
+|---|---|---|
+| id | string | UUID |
+| name | string | display name |
+| online | bool | last-heartbeat ≤ 60s |
+
+---
+
+Closing paragraph after a second divider, to verify spacing holds at
+the very end too.`;
+
 function ChatBubble({
   role,
   content,
@@ -383,3 +494,203 @@ export const ChatBubbles = () => (
     </div>
   </div>
 );
+
+// Kitchen-sink: stress-test every element the renderer can emit in a
+// single bubble. If something regresses (e.g. paragraphs collapse, hr
+// shows a heavy gray bar, table loses borders, list items glue to
+// each other), it's visible at a glance.
+//
+// Numbers in MarkdownMessage.tsx come from research on ChatGPT /
+// Claude.ai / Cursor 2025 — see KitchenSink output as the visual
+// contract. Don't tune values by feel; pair-check against this view.
+export const KitchenSink = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Every block element in one bubble
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Visual contract for the renderer. Heading sizes downscaled
+        chat-style (h1 ≈ body), <code>p</code>/<code>ul</code>/
+        <code>ol</code>/<code>pre</code>/<code>blockquote</code>/
+        <code>hr</code>/<code>table</code> all share a coherent
+        rhythm. Loose lists keep their density — no exploded gap on
+        paragraph-wrapped <code>&lt;li&gt;</code>.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble
+          role="assistant"
+          content={KITCHEN_SINK}
+          rules={subtleRules}
+        />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Same payload on the user-side palette
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Verifies that <code>prose-invert</code> doesn't break any of
+        the new rules — saturated bubbles need the same spacing.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble
+          role="user"
+          content={KITCHEN_SINK}
+          rules={onPrimaryRules}
+        />
+      </div>
+    </div>
+  </div>
+);
+
+// Soft line breaks — `remark-breaks` enabled. LLMs (Claude / GPT) and
+// chat users routinely write "joke punchline / poem stanza / dialogue"
+// blocks separated by a single `\n` rather than a blank line. CommonMark
+// would collapse those into one run-on paragraph; the chat convention
+// (ChatGPT, Slack, Discord, Linear) preserves them as `<br>`. This
+// story is the regression case for that.
+const SOFT_BREAK_JOKE = `Приходит программист к врачу:
+— Доктор, я со всеми общаюсь только через мессенджер. Даже с женой.
+— И что жена говорит?
+— Подождите, сейчас напишу и спрошу… 😄`;
+
+const SOFT_BREAK_POEM = `Roses are red,
+Violets are blue,
+This line is short,
+And so are you.`;
+
+const SOFT_BREAK_DIALOGUE = `Customer: Why is my code not working?
+Support: Have you tried turning it off and on again?
+Customer: I'm a software engineer.
+Support: Have you tried turning it off and on again?`;
+
+export const SoftLineBreaks = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Joke (assistant bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Single <code>\n</code> between lines should render as line
+        breaks, not collapse onto one row. This was the user-reported
+        regression — LLM punchlines surfaced as a wall of text.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={SOFT_BREAK_JOKE} rules={subtleRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Poem (user bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Same payload on the saturated user palette. Each line stays on
+        its own row.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="user" content={SOFT_BREAK_POEM} rules={onPrimaryRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Dialogue (assistant bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Speaker turns separated by single newlines.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={SOFT_BREAK_DIALOGUE} rules={subtleRules} />
+      </div>
+    </div>
+  </div>
+);
+
+// Plugin sampler — emoji shortcodes, smart typography, external link
+// hardening. Verifies the three "lightweight chat" plugins added next
+// to remark-breaks: remark-emoji, remark-smartypants, rehype-
+// external-links. Each plugin contributes one transform; this story
+// makes them visible in isolation.
+const PLUGIN_SAMPLER = `### Plugin sampler
+
+Emoji shortcodes work inline: :rocket: :tada: :+1: — alongside Unicode 🎉.
+
+Smart typography: "double quotes", 'single quotes', em-dash --, ellipsis...
+
+External link should open in a new tab: [Anthropic](https://anthropic.com).
+Internal-style link stays in place: [#section](#section).
+
+A line above —
+soft break here — should still wrap (one \\n only).
+And then a normal paragraph below.`;
+
+export const ChatPlugins = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Assistant bubble</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Three plugins firing at once: <code>remark-emoji</code>,
+        <code>remark-smartypants</code>, <code>rehype-external-links</code>.
+        Hover the Anthropic link — it should carry <code>target=_blank</code>
+        and <code>rel=noopener noreferrer</code> automatically.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={PLUGIN_SAMPLER} rules={subtleRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">User bubble</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Same payload on the saturated palette.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="user" content={PLUGIN_SAMPLER} rules={onPrimaryRules} />
+      </div>
+    </div>
+  </div>
+);
+
+// Mermaid diagrams. Live-renders the fence body via the <Mermaid>
+// tool (lazy-loaded). Useful as a manual smoke test for: (1) the
+// `language === 'mermaid'` branch in components.tsx, (2) the SVG
+// scaling inside a chat-density bubble, (3) interaction with the
+// surrounding markdown spacing rules (paragraph above/below the
+// diagram should keep the same rhythm as around a code fence).
+export const MermaidDiagrams = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Mermaid in an assistant bubble
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Two diagrams (flowchart + sequence) wrapped in surrounding
+        prose. Verifies that <code>```mermaid</code> fences route to{' '}
+        <code>&lt;Mermaid&gt;</code> and that the SVG fits the
+        bubble's max-width without breaking the layout.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble
+          role="assistant"
+          content={MERMAID_CONTENT}
+          rules={subtleRules}
+        />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Same payload on the user-side palette
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        On a saturated <code>bg-primary</code> bubble the diagram
+        keeps its own surface — Mermaid renders SVG with its own
+        background, independent of the bubble palette.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble
+          role="user"
+          content={MERMAID_CONTENT}
+          rules={onPrimaryRules}
+        />
+      </div>
+    </div>
+  </div>
+);

package/src/components/markdown/MarkdownMessage/MarkdownMessage.tsx

@@ -2,9 +2,13 @@
 
 import React from 'react';
 import ReactMarkdown from 'react-markdown';
+import rehypeExternalLinks from 'rehype-external-links';
 import rehypeRaw from 'rehype-raw';
 import rehypeSanitize from 'rehype-sanitize';
+import remarkBreaks from 'remark-breaks';
+import remarkEmoji from 'remark-emoji';
 import remarkGfm from 'remark-gfm';
+import remarkSmartypants from 'remark-smartypants';
 import type { Components } from 'react-markdown';
 
 import { useCollapsibleContent } from '../useCollapsibleContent';
@@ -177,9 +181,14 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
           ${isUser ? 'prose-invert' : 'dark:prose-invert'}
           [&>*]:leading-relaxed
           [&>*:first-child]:mt-0 [&>*:last-child]:mb-0
-          [&_p]:my-0 [&_p+p]:mt-2
-          [&_ul]:my-2 [&_ol]:my-2 [&_pre]:my-2 [&_blockquote]:my-2
-          [&_h1]:mt-3 [&_h1]:mb-1 [&_h2]:mt-3 [&_h2]:mb-1 [&_h3]:mt-2 [&_h3]:mb-1
+          [&_p]:my-2
+          [&_ul]:my-2 [&_ol]:my-2 [&_ul]:pl-5 [&_ol]:pl-5
+          [&_li]:my-1 [&_li>p]:my-0
+          [&_pre]:my-3
+          [&_h1]:mt-4 [&_h1]:mb-2 [&_h1]:text-base [&_h1]:font-semibold
+          [&_h2]:mt-3.5 [&_h2]:mb-1.5 [&_h2]:text-[15px] [&_h2]:font-semibold
+          [&_h3]:mt-3 [&_h3]:mb-1 [&_h3]:text-sm [&_h3]:font-medium
+          [&_h4]:mt-3 [&_h4]:mb-1 [&_h4]:text-sm [&_h4]:font-medium
         `}
         style={{
           // Inherit colors from parent — fixes issues with external
@@ -192,11 +201,32 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
         } as React.CSSProperties}
       >
         <ReactMarkdown
-          remarkPlugins={[remarkGfm]}
+          // Remark plugin order is load-bearing:
+          //   1. `remark-gfm` — tables, strikethrough, autolinks, task lists.
+          //   2. `remark-breaks` — chat convention: single `\n` → `<br>`
+          //      (ChatGPT / Slack / Discord / Linear). CommonMark's
+          //      default would collapse those into one paragraph and
+          //      LLM punchlines / poems / dialogue would render as a
+          //      run-on line. Goes BEFORE smartypants so quotes that
+          //      land at line breaks still get the curly treatment.
+          //   3. `remark-smartypants` — typographic substitutions:
+          //      "..." → …, -- → —, "x" → "x". Cheap "humanized"
+          //      polish à la Medium / Substack.
+          //   4. `remark-emoji` — `:smile:` → 😄 (GitHub / Linear
+          //      shortcode style). Leaves Unicode emoji untouched.
+          remarkPlugins={[remarkGfm, remarkBreaks, remarkSmartypants, remarkEmoji]}
           // rehype-raw parses inline HTML in the source; rehype-sanitize
           // (with our extended schema) runs after to keep XSS guards
           // (no scripts, no on* handlers, no javascript: urls).
-          rehypePlugins={[rehypeRaw, [rehypeSanitize, schema]]}
+          // rehype-external-links runs LAST so it tags every <a> that
+          // sanitize let through — externals get target=_blank +
+          // rel=noopener noreferrer in one pass, instead of every
+          // custom `a` renderer reimplementing the rule.
+          rehypePlugins={[
+            rehypeRaw,
+            [rehypeSanitize, schema],
+            [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
+          ]}
           components={components}
           // urlTransform runs in remark-rehype before sanitize. Without
           // overriding it, react-markdown's default strips `href` for

package/src/components/markdown/MarkdownMessage/README.md

@@ -0,0 +1,111 @@
+# MarkdownMessage
+
+Chat-tuned, read-only markdown renderer. Drop-in for any chat bubble — assistant or user.
+
+```tsx
+import { MarkdownMessage } from '@djangocfg/ui-tools';
+
+<MarkdownMessage content={text} isUser={false} />
+```
+
+## What it gives you
+
+| Feature | Source |
+|---|---|
+| GitHub Flavored Markdown — tables, strikethrough, autolinks, task lists | `remark-gfm` |
+| Single `\n` becomes a hard line break (chat convention) | `remark-breaks` |
+| Smart typography — `"…"` → `"…"`, `--` → `—`, `...` → `…` | `remark-smartypants` |
+| Emoji shortcodes — `:rocket:` → 🚀 | `remark-emoji` |
+| External links auto-tagged with `target="_blank" rel="noopener noreferrer"` | `rehype-external-links` |
+| Inline HTML, parsed and sanitized (XSS-safe) | `rehype-raw` + `rehype-sanitize` |
+| Syntax-highlighted code fences with copy button | `<PrettyCode>` |
+| Mermaid diagrams (` ```mermaid ` fence) with click-to-fullscreen | `<Mermaid>` |
+| Custom URL schemes via declarative `linkRules` | `./linkRules.ts` |
+| Plain-text fast path — short messages skip the markdown pipeline | `./plainText.ts` |
+| Optional collapsible "Read more" for long replies | `useCollapsibleContent` |
+| User vs assistant palette via `isUser` flag | semantic theme tokens |
+
+## Why these plugins
+
+Chat bubbles aren't documents. We picked plugins that fix the gap between CommonMark
+and how people actually type in chats:
+
+- **`remark-breaks`** — CommonMark collapses single newlines into spaces. LLMs and
+  users routinely write joke punchlines, poems, and dialogue separated by single
+  newlines. Without this, "— Доктор, я общаюсь только через мессенджер.\n— Что жена
+  говорит?" renders as one run-on line. ChatGPT, Slack, Discord, Linear all do this.
+- **`remark-smartypants`** — Cheap "humanized" polish: ASCII quotes become typographic
+  quotes, double-dash becomes em-dash, three dots become an ellipsis. Same rule as
+  Medium / Substack. Applied before emoji so quotes around shortcodes still curl.
+- **`remark-emoji`** — Shortcode → Unicode (`:tada:` → 🎉). Already-Unicode emoji
+  pass through untouched.
+- **`rehype-external-links`** — One pass at the end tags every `<a>` that survived
+  sanitize. Replaces ad-hoc `target=_blank` checks in the `a` renderer; works for
+  custom `linkRules`-supplied anchors too.
+
+Plugin order in `MarkdownMessage.tsx` is load-bearing — see the inline comment.
+
+## Plain-text fast path
+
+`MarkdownMessage` looks at the content and decides:
+
+- **Short, single-paragraph, no markdown markers** → render as flat
+  `<div whitespace-pre-wrap>`. Cheaper, preserves newlines verbatim, doesn't
+  parse `*stars*` or `#hash` that the user happened to type.
+- **Anything else** → full ReactMarkdown pipeline.
+
+Override with `plainText={true | false}` if you know better than the heuristic
+(common case: user-typed bubbles always pass `plainText` so their `*` stays as `*`).
+
+## Custom URL schemes (`linkRules`)
+
+`linkRules` is the supported way to plug in app-specific URL handlers (`cmdop://`,
+`obsidian://`, custom file links, mention chips). Each rule:
+
+- declares its `protocols` (whitelisted into the sanitizer);
+- optionally `preprocess`es the source string;
+- `match`es an href and `render`s a custom node.
+
+```tsx
+const rules: LinkRule[] = [
+  {
+    name: 'cmdop-machine-mention',
+    protocols: ['cmdop'],
+    match: (href) => href.startsWith('cmdop://machine/'),
+    render: ({ href, children }) => <MentionChip id={href} label={children} />,
+  },
+];
+
+<MarkdownMessage content="Talk to [Server-A](cmdop://machine/abc-123)" linkRules={rules} />
+```
+
+The plain `a` renderer keeps its palette and typography; `linkRules` only fires
+when both the `protocols` and the `match` predicate accept the href. See
+`linkRules.ts` for the sanitize-extension logic.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `MarkdownMessage.tsx` | Main component — composes plugins, runs heuristic, renders |
+| `components.tsx` | The `Components` map — typography, lists, table, code, blockquote, hr |
+| `CodeBlock.tsx` | Code-fence renderer (`PrettyCode`) + plain `<pre>` fallback |
+| `linkRules.ts` | Declarative custom-URL primitive — schema & helpers |
+| `plainText.ts` | `looksLikePlainProse` heuristic + `extractTextFromChildren` utility |
+| `sanitize.ts` | Extended rehype-sanitize schema + `urlTransform` builder |
+| `CollapseToggle.tsx` | "Read more / Show less" affordance for long replies |
+| `MarkdownMessage.story.tsx` | Storybook — kitchen sink, link rules, mermaid, soft breaks, plugin sampler |
+
+## Stories
+
+Open the storybook and look at:
+
+- `Markdown Message / Link Rules` — declarative `linkRules` API in three modes.
+- `Markdown Message / Chat Bubbles` — plain-text fast path vs heuristic vs long reply.
+- `Markdown Message / Soft Line Breaks` — the `remark-breaks` regression case (joke,
+  poem, dialogue).
+- `Markdown Message / Chat Plugins` — emoji shortcodes, smart typography, external
+  link tagging, in one bubble.
+- `Markdown Message / Kitchen Sink` — every block element together, used to spot
+  spacing regressions at a glance.
+- `Markdown Message / Mermaid Diagrams` — flowchart + sequence diagram in a bubble.