feat(docs): mermaid diagrams + long-doc table of contents (ADR-0046) (#1730)

Render ```mermaid fenced blocks as diagrams in @object-ui/plugin-markdown
(lazy-loaded, securityLevel:'strict', drawn post-sanitize by a trusted
component, soft-degrades to source). Add extractToc() with rehype-slug-
compatible slugs and a sticky h2–h3 TOC rail in DocPage for long docs.
help.onThisPage i18n key (en/zh).

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/docs-mermaid-toc.md

@@ -0,0 +1,11 @@
+---
+"@object-ui/plugin-markdown": minor
+"@object-ui/console": minor
+"@object-ui/i18n": patch
+---
+
+Docs: mermaid diagrams + long-doc table of contents (ADR-0046).
+
+- **plugin-markdown** renders ```mermaid fenced blocks as diagrams (`<Mermaid>`: lazy-loaded mermaid, `securityLevel: 'strict'`, rendered post-`rehype-sanitize` by a trusted component, degrades to the raw source on error). Mermaid is text → SVG, so it stays within the v1 image/binary ban. Adds `extractToc(markdown)` — a TOC builder whose slugs are generated with the same `github-slugger` `rehype-slug` uses, so `#id` links resolve to the rendered heading anchors.
+- **console** `DocPage` shows a sticky right-rail table of contents (h2–h3) for docs with ≥3 headings, plus an app-independent `/apps/:packageId/docs` index already added earlier.
+- **i18n** adds `help.onThisPage` (en/zh; other locales fall back).

apps/console/src/pages/DocPage.tsx

@@ -6,11 +6,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { AlertCircle, FileQuestion, Loader2 } from 'lucide-react';
 import { useAdapter } from '@object-ui/app-shell';
-import { MarkdownRenderer } from '@object-ui/plugin-markdown';
+import { MarkdownRenderer, extractToc } from '@object-ui/plugin-markdown';
+import { useObjectTranslation } from '@object-ui/i18n';
 import { rewriteDocLinks } from './doc-links';
 import { DocShell } from './DocShell';
 
@@ -39,6 +40,7 @@ export default function DocPage() {
   const { name, appName } = useParams<{ name: string; appName?: string }>();
   const navigate = useNavigate();
   const adapter = useAdapter();
+  const { t } = useObjectTranslation();
   const [doc, setDoc] = useState<DocItem | null>(null);
   const [state, setState] = useState<'loading' | 'ready' | 'missing' | 'error'>('loading');
   const [errorMessage, setErrorMessage] = useState<string>('');
@@ -96,6 +98,12 @@ export default function DocPage() {
     [navigate],
   );
 
+  // Long-doc table of contents (h2–h3). Slugs match rehype-slug so a #id
+  // link resolves to the rendered heading's anchor. Shown only past a few
+  // headings so short docs stay clean.
+  const toc = useMemo(() => extractToc(doc?.content ?? ''), [doc?.content]);
+  const tocLabel = t('help.onThisPage', { defaultValue: 'On this page' });
+
   if (state === 'loading') {
     return (
       <div className="flex h-full items-center justify-center p-10 text-muted-foreground">
@@ -133,10 +141,36 @@ export default function DocPage() {
 
   return (
     <DocShell breadcrumb={doc?.label ?? name}>
-      <div className="mx-auto max-w-3xl p-4 sm:p-6" onClick={onContentClick}>
-        <MarkdownRenderer
-          schema={{ type: 'markdown', content: rewriteDocLinks(doc?.content ?? '') }}
-        />
+      <div className="mx-auto flex max-w-5xl gap-8 p-4 sm:p-6">
+        <article
+          className="min-w-0 max-w-3xl flex-1 [&_h1]:scroll-mt-24 [&_h2]:scroll-mt-24 [&_h3]:scroll-mt-24"
+          onClick={onContentClick}
+        >
+          <MarkdownRenderer
+            schema={{ type: 'markdown', content: rewriteDocLinks(doc?.content ?? '') }}
+          />
+        </article>
+        {toc.length >= 3 ? (
+          <aside className="hidden xl:block w-56 shrink-0">
+            <nav aria-label={tocLabel} className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto">
+              <div className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                {tocLabel}
+              </div>
+              <ul className="border-l border-border text-sm">
+                {toc.map((item) => (
+                  <li key={item.id} style={{ paddingLeft: (item.depth - 2) * 12 }}>
+                    <a
+                      href={`#${item.id}`}
+                      className="-ml-px block border-l border-transparent py-0.5 pl-3 text-muted-foreground hover:border-primary hover:text-foreground"
+                    >
+                      {item.text}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          </aside>
+        ) : null}
       </div>
     </DocShell>
   );

packages/i18n/src/locales/en.ts

@@ -1471,6 +1471,7 @@ const en = {
     settings: 'Workspace settings',
   },
   help: {
+    onThisPage: 'On this page',
     appDocs: "This app's docs",
     allDocs: 'All documentation',
     onlineDocs: 'Online documentation',

packages/i18n/src/locales/zh.ts

@@ -1484,6 +1484,7 @@ const zh = {
     settings: '工作区设置',
   },
   help: {
+    onThisPage: '本页目录',
     appDocs: '本应用文档',
     allDocs: '全部文档',
     onlineDocs: '在线文档',

packages/plugin-markdown/package.json

@@ -35,6 +35,8 @@
     "@object-ui/core": "workspace:*",
     "@object-ui/react": "workspace:*",
     "@object-ui/types": "workspace:*",
+    "github-slugger": "^2.0.0",
+    "mermaid": "^11.4.0",
     "react-markdown": "^10.1.0",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-highlight": "^7.0.0",

packages/plugin-markdown/src/MarkdownImpl.tsx

@@ -7,14 +7,15 @@
  */
 
 import * as React from "react"
-import ReactMarkdown from "react-markdown"
+import ReactMarkdown, { type Components } from "react-markdown"
 import remarkGfm from "remark-gfm"
 import { remarkAlert } from "remark-github-blockquote-alert"
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize"
 import rehypeSlug from "rehype-slug"
 import rehypeHighlight from "rehype-highlight"
 import rehypeAutolinkHeadings from "rehype-autolink-headings"
 import { ensureMarkdownStyles } from "./markdown-theme"
+import { Mermaid } from "./Mermaid"
 
 /**
  * Props for the Markdown component implementation.
@@ -99,11 +100,39 @@ const rehypePlugins = [
   rehypeNormalizeClassName,
   // Skip code blocks tagged with an unknown language instead of throwing;
   // highlight only what it recognises.
-  [rehypeHighlight, { detect: true, ignoreMissing: true }],
+  [rehypeHighlight, { detect: true, ignoreMissing: true, plainText: ["mermaid"] }],
   [rehypeAutolinkHeadings, { behavior: "append", properties: { className: ["md-anchor"], ariaHidden: true, tabIndex: -1 }, content: { type: "text", value: "#" } }],
   [rehypeSanitize, sanitizeSchema],
 ] as React.ComponentProps<typeof ReactMarkdown>["rehypePlugins"]
 
+// Flatten a react-markdown code child down to its raw text. mermaid blocks are
+// emitted as a plain text node (rehype-highlight is told to skip "mermaid"), so
+// this yields the diagram source verbatim.
+function nodeText(node: React.ReactNode): string {
+  if (typeof node === "string") return node
+  if (typeof node === "number") return String(node)
+  if (Array.isArray(node)) return node.map(nodeText).join("")
+  if (React.isValidElement(node)) return nodeText((node.props as { children?: React.ReactNode }).children)
+  return ""
+}
+
+// Intercept fenced ```mermaid blocks at the <pre> level (so no <pre> wrapper is
+// emitted) and render them as diagrams; every other block renders normally.
+const mdComponents: Components = {
+  pre({ node: _node, children, ...rest }) {
+    const child = React.Children.toArray(children)[0]
+    const className =
+      React.isValidElement(child) && typeof (child.props as { className?: unknown }).className === "string"
+        ? ((child.props as { className?: string }).className as string)
+        : ""
+    if (/\blanguage-mermaid\b/.test(className)) {
+      const source = nodeText((child as React.ReactElement<{ children?: React.ReactNode }>).props.children)
+      return <Mermaid chart={source} />
+    }
+    return <pre {...rest}>{children}</pre>
+  },
+}
+
 /**
  * Internal Markdown implementation component.
  * This contains the actual react-markdown import (heavy ~100-200 KB).
@@ -139,6 +168,7 @@ export default function MarkdownImpl({ content, className }: MarkdownImplProps)
       <ReactMarkdown
         remarkPlugins={remarkPlugins}
         rehypePlugins={rehypePlugins}
+        components={mdComponents}
         // Defense-in-depth beyond rehype-sanitize: these never reach the DOM.
         disallowedElements={['script', 'style', 'iframe', 'object', 'embed']}
         unwrapDisallowed={true}

packages/plugin-markdown/src/Mermaid.tsx

@@ -0,0 +1,110 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import * as React from "react"
+
+/**
+ * Mermaid diagram renderer for ```mermaid fenced code blocks (ADR-0046).
+ *
+ * Mermaid is text → SVG, so it sidesteps the v1 image/binary ban while still
+ * giving docs flow / state-machine / sequence diagrams. The library is heavy,
+ * so it is dynamically imported the first time a diagram actually mounts —
+ * docs with no diagrams pay nothing.
+ *
+ * Security: rendered with `securityLevel: 'strict'` (labels sanitized, no raw
+ * HTML, no click handlers). The SVG is injected by this trusted component
+ * AFTER react-markdown's `rehype-sanitize` gate (which only sees the source
+ * text, never this output), so the two sanitizers do not fight. A render
+ * failure degrades to the raw source in a <pre>, never a thrown error.
+ */
+
+let mermaidPromise: Promise<typeof import("mermaid").default> | null = null
+function loadMermaid() {
+  if (!mermaidPromise) mermaidPromise = import("mermaid").then((m) => m.default)
+  return mermaidPromise
+}
+
+// Module-scoped monotonic id — mermaid.render needs a unique DOM id per call.
+let renderSeq = 0
+
+function isDark(): boolean {
+  return typeof document !== "undefined" && document.documentElement.classList.contains("dark")
+}
+
+export function Mermaid({ chart }: { chart: string }) {
+  const [svg, setSvg] = React.useState<string>("")
+  const [error, setError] = React.useState<string | null>(null)
+  // Re-render when the app theme toggles so the diagram matches light/dark.
+  const [dark, setDark] = React.useState<boolean>(isDark)
+
+  React.useEffect(() => {
+    if (typeof document === "undefined") return
+    const target = document.documentElement
+    const obs = new MutationObserver(() => setDark(isDark()))
+    obs.observe(target, { attributes: true, attributeFilter: ["class"] })
+    return () => obs.disconnect()
+  }, [])
+
+  React.useEffect(() => {
+    let cancelled = false
+    const source = chart.trim()
+    if (!source) {
+      setSvg("")
+      setError(null)
+      return
+    }
+    loadMermaid()
+      .then(async (mermaid) => {
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "strict",
+          theme: dark ? "dark" : "default",
+        })
+        const id = `os-mermaid-${(renderSeq += 1)}`
+        const { svg } = await mermaid.render(id, source)
+        if (!cancelled) {
+          setSvg(svg)
+          setError(null)
+        }
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : String(e))
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [chart, dark])
+
+  if (error) {
+    return (
+      <pre data-mermaid data-mermaid-error className="my-4 overflow-auto rounded border border-destructive/40 bg-muted p-3 text-xs">
+        <code>{chart}</code>
+      </pre>
+    )
+  }
+
+  if (!svg) {
+    // Pre-render placeholder: keep the source reachable to assistive tech
+    // and to tests while the (async) diagram is still being drawn.
+    return (
+      <div data-mermaid data-mermaid-pending className="my-4 text-sm text-muted-foreground">
+        <pre className="sr-only">{chart}</pre>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-mermaid
+      role="img"
+      className="my-4 flex justify-center overflow-auto [&_svg]:h-auto [&_svg]:max-w-full"
+      // eslint-disable-next-line react/no-danger -- mermaid strict-mode SVG, rendered post-sanitize by our own trusted component
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  )
+}

packages/plugin-markdown/src/index.tsx

@@ -12,6 +12,8 @@ import { Skeleton } from '@object-ui/components';
 
 // Export types for external use
 export type { MarkdownSchema } from './types';
+export { extractToc, type TocItem } from './toc';
+export { Mermaid } from './Mermaid';
 
 // 🚀 Lazy load the implementation file
 // This ensures react-markdown is only loaded when the component is actually rendered

packages/plugin-markdown/src/markdown-render.test.tsx

@@ -79,3 +79,20 @@ describe('markdown enrichments (ADR-0046)', () => {
     expect(html).not.toContain('<svg');
   });
 });
+
+describe('mermaid diagrams (ADR-0046)', () => {
+  it('routes ```mermaid blocks to a diagram container, not a code block', () => {
+    const html = render('```mermaid\ngraph TD; A-->B;\n```\n');
+    // rendered by the trusted <Mermaid> component, not the highlight pipeline
+    expect(html).toContain('data-mermaid');
+    expect(html).not.toMatch(/hljs[^"]*language-mermaid|language-mermaid[^"]*hljs/);
+    // source preserved (a11y / fallback) while the async render runs
+    expect(html).toContain('graph TD');
+  });
+
+  it('still renders ordinary fenced code as a highlighted block', () => {
+    const html = render('```js\nconst x = 1;\n```\n');
+    expect(html).not.toContain('data-mermaid');
+    expect(html).toContain('hljs');
+  });
+});

packages/plugin-markdown/src/toc.test.ts

@@ -0,0 +1,47 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { extractToc } from './toc';
+
+describe('extractToc (ADR-0046 long-doc TOC)', () => {
+  it('extracts h2/h3 with rehype-slug-compatible ids', () => {
+    const toc = extractToc('# Title\n\n## First Section\n\n### Sub A\n\n## Second\n');
+    expect(toc).toEqual([
+      { depth: 2, text: 'First Section', id: 'first-section' },
+      { depth: 3, text: 'Sub A', id: 'sub-a' },
+      { depth: 2, text: 'Second', id: 'second' },
+    ]);
+  });
+
+  it('excludes h1 and h4+ by default', () => {
+    const toc = extractToc('# H1\n\n## H2\n\n#### H4\n');
+    expect(toc.map((t) => t.depth)).toEqual([2]);
+  });
+
+  it('skips headings inside fenced code blocks', () => {
+    const toc = extractToc('## Real\n\n```\n## Not A Heading\n```\n\n~~~\n### Also Not\n~~~\n');
+    expect(toc.map((t) => t.text)).toEqual(['Real']);
+  });
+
+  it('strips inline markdown from heading text', () => {
+    const toc = extractToc('## The **overlay** `rule` and a [link](/x)\n');
+    expect(toc[0]).toEqual({ depth: 2, text: 'The overlay rule and a link', id: 'the-overlay-rule-and-a-link' });
+  });
+
+  it('matches duplicate-heading suffixes like rehype-slug (shared slugger over all headings)', () => {
+    // the h1 also advances the slugger, exactly as rehype-slug does
+    const toc = extractToc('# Setup\n\n## Setup\n\n## Setup\n');
+    expect(toc.map((t) => t.id)).toEqual(['setup-1', 'setup-2']);
+  });
+
+  it('returns [] for empty / heading-free content', () => {
+    expect(extractToc('')).toEqual([]);
+    expect(extractToc('just a paragraph\n')).toEqual([]);
+  });
+});