@djangocfg/ui-tools 2.1.297 → 2.1.299

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

@@ -0,0 +1,171 @@
+import type React from 'react';
+import { defineStory } from '@djangocfg/playground';
+import { MarkdownMessage } from './MarkdownMessage';
+import type { LinkRule } from './types';
+
+export default defineStory({
+  title: 'Components/Markdown Message',
+  component: MarkdownMessage,
+  description:
+    'Chat markdown renderer. Stories cover the declarative `linkRules` API for handling custom URL schemes (e.g. cmdop://) without hand-writing a custom `a` renderer.',
+});
+
+// Canonical mention shape: `[label](cmdop://machine/<uuid>)`. The
+// `@` prefix you sometimes see in composers (`@[label](href)`) is
+// decorative; the chip itself reads as the mention indicator. The
+// rule below strips the leading `@` in `preprocess` so the page
+// doesn't show "@<chip>".
+const CMDOP_CONTENT = `Talk to @[Vps-audi](cmdop://machine/abc-123) about deployment.
+
+Inline reference to [Server-2](cmdop://machine/def-456) inside a sentence.
+
+Plain links survive: [docs](https://example.com).
+Local file: [file](cmdop://local?path=/tmp/x.md).`;
+
+// Chip stand-in. Two variants — `subtle` for chips on neutral cards,
+// `onPrimary` for chips inside a saturated `bg-primary` bubble.
+function MentionChip({
+  id,
+  label,
+  variant = 'subtle',
+}: {
+  id: string;
+  label: string;
+  variant?: 'subtle' | 'onPrimary';
+}) {
+  const onClick = () => {
+    // eslint-disable-next-line no-console
+    console.log('[story] MentionChip clicked', { id, label });
+    if (typeof window !== 'undefined') alert(`Chip clicked: ${label} (${id})`);
+  };
+  const palette =
+    variant === 'onPrimary'
+      ? 'bg-primary-foreground/15 text-primary-foreground hover:bg-primary-foreground/25'
+      : 'bg-primary/10 text-primary hover:bg-primary/20';
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`inline-flex items-center gap-1 rounded-md px-1.5 py-0.5 text-xs font-sans font-medium align-baseline transition-colors ${palette}`}
+    >
+      <span
+        className={
+          variant === 'onPrimary'
+            ? 'h-1.5 w-1.5 rounded-full bg-primary-foreground/70'
+            : 'h-1.5 w-1.5 rounded-full bg-emerald-500'
+        }
+        aria-hidden
+      />
+      <span>{label}</span>
+    </button>
+  );
+}
+
+// Helper used by the chip rule: pull a clean string label from
+// react-markdown's children (string, number, array, or React element).
+function extractLabel(node: React.ReactNode): string {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(extractLabel).join('');
+  return '';
+}
+
+function makeRules(chipVariant: 'subtle' | 'onPrimary'): LinkRule[] {
+  return [
+    {
+      name: 'cmdop-machine-mention',
+      protocols: ['cmdop'],
+      // Strip the decorative leading `@` from `@[label](cmdop://machine/<id>)`
+      // so the chip alone reads as the mention indicator.
+      preprocess: (s) =>
+        s.replace(/(^|[^A-Za-z0-9_])@(\[[^\]]+\]\(cmdop:\/\/machine\/[^)\s]+\))/g, '$1$2'),
+      match: (href) => href.startsWith('cmdop://machine/'),
+      render: ({ href, children }) => {
+        const id = href.slice('cmdop://machine/'.length).trim();
+        const label = extractLabel(children) || id;
+        return <MentionChip id={id} label={label} variant={chipVariant} />;
+      },
+    },
+    {
+      name: 'cmdop-local-file',
+      protocols: ['cmdop'],
+      match: (href) => href.startsWith('cmdop://local'),
+      render: ({ href, children }) => (
+        <a
+          href={href}
+          onClick={(e) => {
+            e.preventDefault();
+            // eslint-disable-next-line no-console
+            console.log('[story] local file click', { href });
+            if (typeof window !== 'undefined') alert(`Local link: ${href}`);
+          }}
+          className={
+            chipVariant === 'onPrimary'
+              ? 'text-primary-foreground/90 underline hover:text-primary-foreground'
+              : 'text-primary underline hover:text-primary/80'
+          }
+        >
+          {children}
+        </a>
+      ),
+    },
+  ];
+}
+
+const subtleRules = makeRules('subtle');
+const onPrimaryRules = makeRules('onPrimary');
+
+export const LinkRules = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Declarative rules — preferred API
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Each rule declares its protocol, an optional preprocess pass,
+        a match predicate, and a render. <code>MarkdownMessage</code>
+        composes them: per-rule sanitize whitelist, custom <code>a</code>
+        renderer, and source rewrites all happen behind one prop.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4 text-card-foreground">
+        <MarkdownMessage
+          content={CMDOP_CONTENT}
+          isUser={false}
+          linkRules={subtleRules}
+        />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Inside a saturated bubble (<code>bg-primary</code>)
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Same content, rules carrying the on-primary palette. Theme
+        tokens (<code>primary-foreground</code>) keep contrast in light
+        and dark themes.
+      </p>
+      <div className="rounded-xl bg-primary p-4 text-primary-foreground">
+        <MarkdownMessage
+          content={CMDOP_CONTENT}
+          isUser
+          linkRules={onPrimaryRules}
+        />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">
+        Without rules (control)
+      </h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        No rules → react-markdown's default urlTransform strips
+        <code> cmdop://</code> hrefs before render. Plain text falls
+        through; cmdop links degrade to label-only anchors.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4 text-card-foreground">
+        <MarkdownMessage content={CMDOP_CONTENT} isUser={false} />
+      </div>
+    </div>
+  </div>
+);

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

@@ -0,0 +1,202 @@
+'use client';
+
+import React from 'react';
+import ReactMarkdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize from 'rehype-sanitize';
+import remarkGfm from 'remark-gfm';
+import type { Components } from 'react-markdown';
+
+import { useCollapsibleContent } from '../useCollapsibleContent';
+import type { MarkdownMessageProps } from './types';
+import { buildSchema, buildUrlTransform } from './sanitize';
+import { hasMarkdownSyntax } from './plainText';
+import { createMarkdownComponents } from './components';
+import { CollapseToggle } from './CollapseToggle';
+import { applyPreprocess, buildLinkRulesComponent, collectProtocols } from './linkRules';
+
+/**
+ * MarkdownMessage — chat-tuned markdown renderer.
+ *
+ * Features:
+ * - GitHub Flavored Markdown (GFM) via remark-gfm
+ * - Syntax-highlighted code blocks with Copy button
+ * - Mermaid diagram rendering (` ```mermaid ` fence)
+ * - Tables, lists, blockquotes scaled for chat density
+ * - User vs assistant styling modes (`isUser`)
+ * - Plain-text fast path: skips ReactMarkdown when content has no
+ *   markdown syntax (cheaper render, preserves newlines via CSS)
+ * - Optional collapsible "Read more..." for long messages
+ *
+ * Custom URL schemes (chat mentions, deep-links, custom file viewers)
+ * are best handled with the declarative `linkRules` prop — see the
+ * type definition in `./types.ts` and the storybook for examples.
+ *
+ * @example
+ * ```tsx
+ * <MarkdownMessage content="# Hello\n\nThis is **bold** text." />
+ *
+ * // User message styling
+ * <MarkdownMessage content="Some content" isUser />
+ *
+ * // Custom URL scheme via linkRules
+ * <MarkdownMessage
+ *   content="Talk to [Vps-audi](cmdop://machine/abc-123)"
+ *   linkRules={[machineMentionRule]}
+ * />
+ * ```
+ */
+export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
+  content,
+  className = '',
+  isUser = false,
+  isCompact = false,
+  customComponents,
+  extraHrefProtocols,
+  linkRules,
+  collapsible = false,
+  maxLength,
+  maxLines,
+  readMoreLabel = 'Read more...',
+  showLessLabel = 'Show less',
+  defaultExpanded = false,
+  onCollapseChange,
+}) => {
+  // Pre-process content through any rules that requested it. Done
+  // before trim so a rule can rewrite multi-line shapes too.
+  const preprocessed = React.useMemo(
+    () => applyPreprocess(content, linkRules),
+    [content, linkRules],
+  );
+
+  // Union of `extraHrefProtocols` and any `protocols` declared by rules.
+  const effectiveProtocols = React.useMemo(
+    () => collectProtocols(extraHrefProtocols, linkRules),
+    [extraHrefProtocols, linkRules],
+  );
+
+  // Effective custom components: merge linkRules' synthesized `a`
+  // renderer with any caller-provided `customComponents`. linkRules
+  // wins when both target the same href (rule is the more specific
+  // declarative claim by design).
+  const effectiveCustomComponents = React.useMemo<Partial<Components> | undefined>(() => {
+    if (!linkRules || linkRules.length === 0) return customComponents;
+    const callerA = customComponents?.a;
+    const aRenderer = buildLinkRulesComponent(linkRules, isUser, callerA);
+    return { ...(customComponents ?? {}), a: aRenderer };
+  }, [customComponents, linkRules, isUser]);
+
+  const trimmedContent = preprocessed.trim();
+
+  // Collapsible content logic — defaults kick in only when enabled.
+  const collapsibleOptions = React.useMemo(() => {
+    if (!collapsible) return {};
+    return {
+      maxLength: maxLength ?? 1000,
+      maxLines: maxLines ?? 10,
+      defaultExpanded,
+    };
+  }, [collapsible, maxLength, maxLines, defaultExpanded]);
+
+  const { isCollapsed, toggleCollapsed, displayContent, shouldCollapse } =
+    useCollapsibleContent(trimmedContent, collapsible ? collapsibleOptions : {});
+
+  React.useEffect(() => {
+    if (collapsible && shouldCollapse && onCollapseChange) {
+      onCollapseChange(isCollapsed);
+    }
+  }, [isCollapsed, collapsible, shouldCollapse, onCollapseChange]);
+
+  const components = React.useMemo(() => {
+    const base = createMarkdownComponents(isUser, isCompact);
+    return effectiveCustomComponents ? { ...base, ...effectiveCustomComponents } : base;
+  }, [isUser, isCompact, effectiveCustomComponents]);
+
+  const schema = React.useMemo(() => buildSchema(effectiveProtocols), [effectiveProtocols]);
+  const urlTransform = React.useMemo(
+    () => buildUrlTransform(effectiveProtocols),
+    [effectiveProtocols],
+  );
+
+  const textSizeClass = isCompact ? 'text-xs' : 'text-sm';
+  const proseClass = isCompact ? 'prose-xs' : 'prose-sm';
+
+  // Plain-text fast path: skip ReactMarkdown when content is pure
+  // prose. Bypassed when the caller wired up custom components or
+  // link rules — those need to fire on plain `[label](custom://…)`
+  // links the fast path would otherwise print verbatim.
+  const isPlainText =
+    !effectiveCustomComponents && !hasMarkdownSyntax(displayContent);
+
+  if (isPlainText) {
+    return (
+      <span
+        className={`${textSizeClass} leading-7 break-words whitespace-pre-line font-light ${className}`}
+      >
+        {displayContent}
+        {collapsible && shouldCollapse && (
+          <>
+            {isCollapsed && '... '}
+            <CollapseToggle
+              isCollapsed={isCollapsed}
+              onClick={toggleCollapsed}
+              readMoreLabel={readMoreLabel}
+              showLessLabel={showLessLabel}
+              isUser={isUser}
+              isCompact={isCompact}
+            />
+          </>
+        )}
+      </span>
+    );
+  }
+
+  return (
+    <div className={className}>
+      <div
+        className={`
+          prose ${proseClass} max-w-none break-words overflow-hidden ${textSizeClass}
+          ${isUser ? 'prose-invert' : 'dark:prose-invert'}
+          [&>*]:leading-7
+        `}
+        style={{
+          // Inherit colors from parent — fixes issues with external
+          // CSS variables overriding prose tokens.
+          '--tw-prose-body': 'inherit',
+          '--tw-prose-headings': 'inherit',
+          '--tw-prose-bold': 'inherit',
+          '--tw-prose-links': 'inherit',
+          color: 'inherit',
+        } as React.CSSProperties}
+      >
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          // 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]]}
+          components={components}
+          // urlTransform runs in remark-rehype before sanitize. Without
+          // overriding it, react-markdown's default strips `href` for
+          // unknown schemes — making our extended sanitize whitelist
+          // moot. Only set when the caller opted into extra protocols.
+          urlTransform={urlTransform}
+        >
+          {displayContent}
+        </ReactMarkdown>
+      </div>
+      {collapsible && shouldCollapse && (
+        <CollapseToggle
+          isCollapsed={isCollapsed}
+          onClick={toggleCollapsed}
+          readMoreLabel={readMoreLabel}
+          showLessLabel={showLessLabel}
+          isUser={isUser}
+          isCompact={isCompact}
+        />
+      )}
+    </div>
+  );
+};
+
+export default MarkdownMessage;

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

@@ -0,0 +1,154 @@
+import React from 'react';
+import type { Components } from 'react-markdown';
+import Mermaid from '../../../tools/Mermaid';
+import { CodeBlock, CodeBlockFallback } from './CodeBlock';
+import { extractTextFromChildren } from './plainText';
+
+/**
+ * Build the chat-tuned markdown component map.
+ *
+ * Base text size: text-sm (14px) for normal, text-xs (12px) for compact.
+ * Heading sizes are scaled down a notch from the prose defaults so
+ * inline-in-chat headings don't dominate.
+ */
+export function createMarkdownComponents(
+  isUser: boolean = false,
+  isCompact: boolean = false,
+): Components {
+  const textSize = isCompact ? 'text-xs' : 'text-sm';
+  const headingBase = isCompact ? 'text-sm' : 'text-base';
+  const headingSm = isCompact ? 'text-xs' : 'text-sm';
+
+  return {
+    h1: ({ children }) => (
+      <h1 className={`${headingBase} font-bold mb-2 mt-3 first:mt-0`}>{children}</h1>
+    ),
+    h2: ({ children }) => (
+      <h2 className={`${headingSm} font-bold mb-2 mt-3 first:mt-0`}>{children}</h2>
+    ),
+    h3: ({ children }) => (
+      <h3 className={`${headingSm} font-semibold mb-1 mt-2 first:mt-0`}>{children}</h3>
+    ),
+    h4: ({ children }) => (
+      <h4 className={`${headingSm} font-semibold mb-1 mt-2 first:mt-0`}>{children}</h4>
+    ),
+    h5: ({ children }) => (
+      <h5 className={`${headingSm} font-medium mb-1 mt-2 first:mt-0`}>{children}</h5>
+    ),
+    h6: ({ children }) => (
+      <h6 className={`${headingSm} font-medium mb-1 mt-2 first:mt-0`}>{children}</h6>
+    ),
+
+    p: ({ children }) => (
+      <p className={`${textSize} mb-4 last:mb-0 leading-7 break-words font-light`}>{children}</p>
+    ),
+
+    ul: ({ children }) => (
+      <ul className={`list-disc list-inside mb-2 space-y-1 ${textSize}`}>{children}</ul>
+    ),
+    ol: ({ children }) => (
+      <ol className={`list-decimal list-inside mb-2 space-y-1 ${textSize}`}>{children}</ol>
+    ),
+    li: ({ children }) => <li className="break-words">{children}</li>,
+
+    a: ({ href, children }) => (
+      <a
+        href={href}
+        className={`${textSize} ${
+          isUser
+            ? 'text-white/90 underline hover:text-white'
+            : 'text-primary underline hover:text-primary/80'
+        } transition-colors break-all`}
+        target={href?.startsWith('http') ? '_blank' : undefined}
+        rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
+      >
+        {children}
+      </a>
+    ),
+
+    pre: ({ children }) => {
+      let codeContent = '';
+      let language = 'plaintext';
+
+      if (React.isValidElement(children)) {
+        const child = children;
+        if (
+          child.type === 'code'
+          || (typeof child.type === 'function' && child.type.name === 'code')
+        ) {
+          const codeProps = child.props as {
+            className?: string;
+            children?: React.ReactNode;
+          };
+          const rawClassName = codeProps.className;
+          language = rawClassName?.replace(/language-/, '').trim() || 'plaintext';
+          codeContent = extractTextFromChildren(codeProps.children).trim();
+        } else {
+          codeContent = extractTextFromChildren(children).trim();
+        }
+      } else {
+        codeContent = extractTextFromChildren(children).trim();
+      }
+
+      if (!codeContent) {
+        return (
+          <div className="my-3 p-3 bg-muted rounded text-sm text-muted-foreground">
+            No content available
+          </div>
+        );
+      }
+
+      if (language === 'mermaid') {
+        return (
+          <div className="my-3 max-w-full overflow-x-auto">
+            <Mermaid chart={codeContent} className="max-w-[600px] mx-auto" isCompact={isCompact} />
+          </div>
+        );
+      }
+
+      try {
+        return <CodeBlock code={codeContent} language={language} isUser={isUser} isCompact={isCompact} />;
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('CodeBlock failed, using fallback:', error);
+        return <CodeBlockFallback code={codeContent} language={language} isUser={isUser} isCompact={isCompact} />;
+      }
+    },
+
+    code: ({ children, className }) => {
+      // Inside <pre>: let pre handle styling.
+      if (className?.includes('language-')) {
+        return <code className={className}>{children}</code>;
+      }
+      return (
+        <code className="px-1.5 py-0.5 rounded text-xs font-mono bg-muted text-foreground break-all">
+          {extractTextFromChildren(children)}
+        </code>
+      );
+    },
+
+    blockquote: ({ children }) => (
+      <blockquote className={`${textSize} border-l-2 border-border pl-3 my-2 italic text-muted-foreground break-words`}>
+        {children}
+      </blockquote>
+    ),
+
+    table: ({ children }) => (
+      <div className="overflow-x-auto my-3">
+        <table className={`min-w-full ${textSize} border-collapse`}>{children}</table>
+      </div>
+    ),
+    thead: ({ children }) => <thead className="bg-muted/50">{children}</thead>,
+    tbody: ({ children }) => <tbody>{children}</tbody>,
+    tr: ({ children }) => <tr className="border-b border-border/50">{children}</tr>,
+    th: ({ children }) => (
+      <th className="px-2 py-1 text-left font-medium break-words">{children}</th>
+    ),
+    td: ({ children }) => <td className="px-2 py-1 break-words">{children}</td>,
+
+    hr: () => <hr className="my-3 border-0 h-px bg-border" />,
+
+    strong: ({ children }) => <strong className="font-semibold">{children}</strong>,
+    em: ({ children }) => <em className="italic">{children}</em>,
+  };
+}

package/src/components/markdown/MarkdownMessage/index.ts

@@ -0,0 +1,13 @@
+/**
+ * MarkdownMessage — chat-tuned markdown renderer.
+ *
+ * Public API:
+ *   - `MarkdownMessage` (default + named) — the React component.
+ *   - `MarkdownMessageProps` — its full prop shape.
+ *   - `LinkRule` — the declarative link-handling primitive.
+ *   - `extractTextFromChildren` — utility for callers that build their
+ *     own custom `a` renderers and need a string label.
+ */
+export { MarkdownMessage, default } from './MarkdownMessage';
+export type { MarkdownMessageProps, LinkRule } from './types';
+export { extractTextFromChildren } from './plainText';

package/src/components/markdown/MarkdownMessage/linkRules.ts

@@ -0,0 +1,83 @@
+import React from 'react';
+import type { ComponentProps, ComponentType } from 'react';
+import type { Components } from 'react-markdown';
+import type { LinkRule } from './types';
+
+// react-markdown's `Components['a']` is `keyof IntrinsicElements | ComponentType<…>`,
+// so it isn't necessarily a function we can directly call. This is the
+// component-shaped variant — what callers practically pass when they
+// override `a`.
+type AComponent = ComponentType<ComponentProps<'a'>>;
+
+/** Run every rule's `preprocess` hook in order. Errors in a single
+ *  rule are logged and skipped — the other rules still run. */
+export function applyPreprocess(
+  source: string,
+  rules: readonly LinkRule[] | undefined,
+): string {
+  if (!rules || rules.length === 0) return source;
+  let s = source;
+  for (const rule of rules) {
+    if (!rule.preprocess) continue;
+    try {
+      s = rule.preprocess(s);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[MarkdownMessage] linkRule "${rule.name ?? '(anonymous)'}" preprocess threw; skipping`,
+        err,
+      );
+    }
+  }
+  return s;
+}
+
+/** Union of `extraHrefProtocols` and any `protocols` declared by rules. */
+export function collectProtocols(
+  extraHrefProtocols: readonly string[] | undefined,
+  rules: readonly LinkRule[] | undefined,
+): readonly string[] | undefined {
+  const set = new Set<string>();
+  if (extraHrefProtocols) for (const p of extraHrefProtocols) set.add(p);
+  if (rules) {
+    for (const r of rules) {
+      if (r.protocols) for (const p of r.protocols) set.add(p);
+    }
+  }
+  return set.size === 0 ? undefined : Array.from(set);
+}
+
+/** Build a custom `a` renderer that dispatches to the first matching
+ *  rule, falling through to `callerA` (or the built-in chat anchor)
+ *  for anything no rule claims. */
+export function buildLinkRulesComponent(
+  rules: readonly LinkRule[],
+  isUser: boolean,
+  callerA: NonNullable<Components['a']> | undefined,
+): NonNullable<Components['a']> {
+  const Renderer: AComponent = (props) => {
+    const { href, children } = props;
+    if (typeof href === 'string') {
+      for (const rule of rules) {
+        if (rule.match(href)) {
+          return React.createElement(
+            React.Fragment,
+            null,
+            rule.render({ href, children, isUser }),
+          );
+        }
+      }
+    }
+    // Defer to the caller's `a` override if any. We only call it when
+    // it's a function/component — string-form intrinsic overrides
+    // (`'a' | 'span' | …`) aren't a thing react-markdown supports for
+    // tag overrides, but the type still admits the union, so guard.
+    if (callerA && typeof callerA === 'function') {
+      const Caller = callerA as AComponent;
+      return React.createElement(Caller, props);
+    }
+    // Fall through to the built-in anchor by rendering a plain `<a>`.
+    return React.createElement('a', props, children);
+  };
+  return Renderer as NonNullable<Components['a']>;
+}

package/src/components/markdown/MarkdownMessage/plainText.ts

@@ -0,0 +1,50 @@
+import React from 'react';
+
+/** Recursively concatenate the text content of a React.ReactNode tree.
+ *  Used by the markdown renderers (e.g. `<pre>` extracting code) and
+ *  by consumers that need a plain-string label out of link children. */
+export function extractTextFromChildren(children: React.ReactNode): string {
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  if (React.isValidElement(children)) {
+    const props = children.props as { children?: React.ReactNode };
+    return extractTextFromChildren(props.children);
+  }
+  if (Array.isArray(children)) {
+    return children.map(extractTextFromChildren).join('');
+  }
+  return '';
+}
+
+/** Affordance test: does this string look like markdown? Used to skip
+ *  the (heavier) ReactMarkdown pipeline when the content is pure
+ *  prose. NOT a validator — false negatives are fine; false positives
+ *  cost a render but render correctly. */
+export function hasMarkdownSyntax(text: string): boolean {
+  // Newlines after trim → render as markdown so paragraphs work.
+  if (text.trim().includes('\n')) return true;
+
+  // Inline HTML tags (`<br>`, `<b>`, `<code>`, …) — common in OpenAPI
+  // descriptions. Without this branch the fast path would escape them
+  // and the user sees literal angle brackets.
+  if (/<\/?[a-zA-Z][a-zA-Z0-9-]*(\s[^>]*)?\/?>/.test(text)) return true;
+
+  const patterns = [
+    /^#{1,6}\s/m,           // Headers
+    /\*\*[^*]+\*\*/,        // Bold
+    /\*[^*]+\*/,            // Italic
+    /__[^_]+__/,            // Bold (underscore)
+    /_[^_]+_/,              // Italic (underscore)
+    /\[.+\]\(.+\)/,         // Links
+    /!\[.*\]\(.+\)/,        // Images
+    /```[\s\S]*```/,        // Code blocks
+    /`[^`]+`/,              // Inline code
+    /^\s*[-*+]\s/m,         // Unordered lists
+    /^\s*\d+\.\s/m,         // Ordered lists
+    /^\s*>/m,               // Blockquotes
+    /\|.+\|/,               // Tables
+    /^---+$/m,              // Horizontal rules
+    /~~[^~]+~~/,            // Strikethrough
+  ];
+  return patterns.some((p) => p.test(text));
+}