@hutusi/amytis 1.15.0 → 1.17.0

package/src/components/ImmersiveSeriesSidebar.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+import { useRef } from 'react';
+import { useSearchParams } from 'next/navigation';
+import Link from 'next/link';
+import type { PostData, CollectionContext, Heading } from '@/lib/markdown';
+import { useLanguage } from './LanguageProvider';
+import { useImmersiveReading } from './ImmersiveReadingProvider';
+import { useSidebarAutoScroll } from '@/hooks/useSidebarAutoScroll';
+import InlineBookToc from './InlineBookToc';
+import { getPostUrl, getPostUrlInCollection, getSeriesListUrl, getSeriesUrl } from '@/lib/urls';
+
+// Dedicated TOC sidebar for the immersive reader on a series post. Visually
+// mirrors BookSidebar's `mode="fill"` shape (clean numbered list, left-
+// border accent on the current item, inlined headings under the current
+// post, footer pointing at the listing page) rather than the page-mode
+// SeriesList card — see PR #95 review feedback.
+
+interface ImmersiveSeriesSidebarProps {
+  seriesSlug: string;
+  seriesTitle: string;
+  posts: PostData[];
+  /** When the post is in a collection, the sidebar can render in that
+   *  collection's scope by appending `?collection=<slug>` to the URL. Same
+   *  resolution logic as SeriesList. */
+  collectionContexts?: CollectionContext[];
+  currentSlug: string;
+  /** h2/h3 headings for the current post — rendered as an inline TOC under
+   *  the current post's row via the shared InlineBookToc component. */
+  headings?: Heading[];
+}
+
+export default function ImmersiveSeriesSidebar({
+  seriesSlug,
+  seriesTitle,
+  posts,
+  collectionContexts,
+  currentSlug,
+  headings = [],
+}: ImmersiveSeriesSidebarProps) {
+  const { t } = useLanguage();
+  const { enabled: immersiveEnabled } = useImmersiveReading();
+  const searchParams = useSearchParams();
+  const collectionParam = searchParams.get('collection');
+  const activeCollection = collectionParam
+    ? (collectionContexts ?? []).find(c => c.slug === collectionParam) ?? null
+    : null;
+
+  const effectiveSlug = activeCollection?.slug ?? seriesSlug;
+  const effectiveTitle = activeCollection?.title ?? seriesTitle;
+  const effectivePosts = activeCollection?.posts ?? posts;
+  const isCollectionContext = !!activeCollection;
+
+  // Collections mix posts from different layout segments (`/posts/[slug]` vs
+  // `/[series]/[slug]`). When clicking across that boundary, the
+  // ImmersiveReadingProvider remounts with `enabled=false` and the overlay
+  // closes. Appending `?immersive=1` lets the destination layout's
+  // ImmersiveReadingFlagHandler re-enter the reader and strip the flag.
+  const postHref = (post: PostData) => {
+    const base = activeCollection
+      ? getPostUrlInCollection(post, activeCollection.slug)
+      : getPostUrl(post);
+    if (!immersiveEnabled) return base;
+    const sep = base.includes('?') ? '&' : '?';
+    return `${base}${sep}immersive=1`;
+  };
+
+  const currentIndex = effectivePosts.findIndex(p => p.slug === currentSlug);
+  const currentItemRef = useRef<HTMLLIElement>(null);
+  const sidebarRef = useRef<HTMLElement>(null);
+  useSidebarAutoScroll(sidebarRef, currentItemRef, currentSlug);
+
+  if (effectivePosts.length === 0) return null;
+
+  return (
+    <aside
+      ref={sidebarRef}
+      className="block w-full h-full overflow-y-auto px-4 py-6 scrollbar-hide hover:scrollbar-thin"
+    >
+      {/* Header — series / collection label + post count + title link */}
+      <div className="mb-6 pb-4 border-b border-muted/10">
+        <div className="flex items-center justify-between mb-2">
+          <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-accent">
+            {isCollectionContext ? t('collection') : t('series')}
+          </span>
+          <span className="text-xs font-mono text-muted whitespace-nowrap">
+            {currentIndex + 1}/{effectivePosts.length}
+          </span>
+        </div>
+        <Link href={getSeriesUrl(effectiveSlug)} className="group block no-underline">
+          <h3 className="font-serif font-bold text-heading text-lg leading-snug group-hover:text-accent transition-colors">
+            {effectiveTitle}
+          </h3>
+        </Link>
+      </div>
+
+      {/* Posts list — flat, current with left-border + accent (same treatment
+          as BookSidebar's chapter link). Past posts dimmed less than future
+          posts, also matching BookSidebar. */}
+      <nav aria-label={isCollectionContext ? t('collection') : t('series')}>
+        <ul className="space-y-1">
+          {effectivePosts.map((post, index) => {
+            const isCurrent = post.slug === currentSlug;
+            const isPast = index < currentIndex;
+            return (
+              <li key={post.slug} ref={isCurrent ? currentItemRef : undefined}>
+                <Link
+                  href={postHref(post)}
+                  className={`block py-2 px-3 rounded-lg text-sm no-underline transition-all duration-200 ${
+                    isCurrent
+                      ? 'bg-accent/10 text-accent font-semibold border-l-2 border-accent'
+                      : isPast
+                        ? 'text-foreground/70 hover:text-foreground hover:bg-muted/5'
+                        : 'text-muted hover:text-foreground hover:bg-muted/5'
+                  }`}
+                  aria-current={isCurrent ? 'page' : undefined}
+                >
+                  {post.title}
+                </Link>
+                {isCurrent && <InlineBookToc headings={headings} />}
+              </li>
+            );
+          })}
+        </ul>
+      </nav>
+
+      {/* Footer — points at the series listing (not back to the current
+          series detail, which the header already links to). Matches
+          BookSidebar's "All Books" footer pattern. */}
+      <div className="mt-6 pt-4 border-t border-muted/10">
+        <Link
+          href={getSeriesListUrl()}
+          className="text-xs font-sans text-muted hover:text-accent transition-colors no-underline flex items-center gap-1"
+        >
+          {t('all_series')}
+          <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+          </svg>
+        </Link>
+      </div>
+    </aside>
+  );
+}

package/src/components/ImmersiveToggleButton.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import { useLanguage } from '@/components/LanguageProvider';
+
+export default function ImmersiveToggleButton() {
+  const { enabled, toggle } = useImmersiveReading();
+  const { t } = useLanguage();
+  // The button is the "enter" affordance; in immersive mode the top bar's
+  // exit (✕) is the only way out, so the inline button hides to avoid
+  // duplicating the exit and reading "Exit reading mode" next to it. Owning
+  // the visibility here means callers (PostLayout's article header, etc.)
+  // don't need to gate it with `{!enabled && ...}` separately.
+  if (enabled) return null;
+  const label = t('immersive_reading');
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      title={label}
+      aria-label={label}
+      className="inline-flex items-center gap-1.5 px-2 py-1 rounded-md text-xs font-sans text-muted hover:text-accent hover:bg-muted/10 transition-colors border border-transparent hover:border-muted/20 select-none"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M3 7V5a2 2 0 0 1 2-2h2" />
+        <path d="M17 3h2a2 2 0 0 1 2 2v2" />
+        <path d="M21 17v2a2 2 0 0 1-2 2h-2" />
+        <path d="M7 21H5a2 2 0 0 1-2-2v-2" />
+        <path d="M8 12h8" />
+      </svg>
+      <span className="hidden sm:inline">{label}</span>
+    </button>
+  );
+}

package/src/components/MarkdownRenderer.test.tsx

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
 import MarkdownRenderer from "./MarkdownRenderer";
+import { renderAsync } from "@/test-utils/render";
 
 describe("MarkdownRenderer", () => {
   describe("image rendering", () => {
@@ -12,6 +13,9 @@ describe("MarkdownRenderer", () => {
       expect(html).toContain('height="900"');
       // style override ensures the image renders at its natural size
       expect(html).toContain('width:100%');
+      // fetchpriority="low" prevents React 19 from auto-preloading local
+      // markdown images as LCP candidates (matches the external-image fix)
+      expect(html).toContain('fetchPriority="low"');
     });
 
     test("uses plain img for external images", () => {
@@ -42,7 +46,7 @@ describe("MarkdownRenderer", () => {
     });
   });
 
-  test("adds horizontal overflow containment while preserving code scrolling", () => {
+  test("adds horizontal overflow containment while preserving code scrolling", async () => {
     const content = [
       "## Example",
       "",
@@ -51,16 +55,22 @@ describe("MarkdownRenderer", () => {
       "```",
     ].join("\n");
 
-    const html = renderToStaticMarkup(<MarkdownRenderer content={content} />);
+    const html = await renderAsync(<MarkdownRenderer content={content} />);
 
     expect(html).toContain("overflow-x-hidden");
     expect(html).toContain("not-prose w-full min-w-0 max-w-full");
     expect(html).toContain("overflow-x-auto");
+    // Shiki rendered the block — ensure the highlighted shell pass produced output.
+    expect(html).toContain('class="shiki');
   });
 
-  test("wraps content in a background container for copy-paste fidelity", () => {
+  test("wraps content in ArticleCopyCleaner so paste output is stripped of per-paragraph backgrounds", () => {
     const content = "Hello world";
     const html = renderToStaticMarkup(<MarkdownRenderer content={content} />);
-    expect(html).toMatch(/class="[^"]*\bbg-background\b[^"]*"/);
+    // The cleaner renders a bare wrapper div; the page background lives on body now,
+    // so the article HTML must not paint its own background (which is what caused
+    // Chromium's clipboard serializer to inline `background-color` on every <p>).
+    expect(html).not.toMatch(/class="[^"]*\bbg-background\b[^"]*"/);
+    expect(html).toContain('<p class="mb-4 leading-relaxed text-foreground">Hello world</p>');
   });
 });

package/src/components/MarkdownRenderer.tsx

@@ -1,33 +1,84 @@
+import React from 'react';
 import ReactMarkdown, { Components, ExtraProps } from 'react-markdown';
 import RssFeedWidget from '@/components/RssFeedWidget';
 import Mermaid from '@/components/Mermaid';
 import CodeBlock from '@/components/CodeBlock';
+import CodeGroup from '@/components/CodeGroup';
+import GithubAlert from '@/components/GithubAlert';
 import KatexStyles from '@/components/KatexStyles';
+import ExternalLinkIcon from '@/components/ExternalLinkIcon';
+import ArticleCopyCleaner from '@/components/ArticleCopyCleaner';
 import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkCodeGroup from '@/lib/remark-code-group';
+import remarkGithubAlerts from '@/lib/remark-github-alerts';
+import remarkVuepressContainers, { normalizeVuepressContainerSyntax } from '@/lib/remark-vuepress-containers';
+import { normalizeVuepressBlockMath } from '@/lib/normalize-vuepress-math';
+import remarkBookChapterLinks, { type BookChapterLinksOptions } from '@/lib/remark-book-chapter-links';
 import rehypeRaw from 'rehype-raw';
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
 import rehypeSlug from 'rehype-slug';
 import rehypeImageMetadata from '@/lib/rehype-image-metadata';
+import rehypeFenceMeta from '@/lib/rehype-fence-meta';
 import { siteConfig } from '../../site.config';
 import remarkWikilinks from '@/lib/remark-wikilinks';
 import ExportedImage from 'next-image-export-optimizer';
 import { PluggableList } from 'unified';
 import type { SlugRegistryEntry } from '@/lib/markdown';
 import { shouldBypassImageOptimization } from '@/lib/image-utils';
+import { parseFenceMeta } from '@/lib/shiki';
+import { isExternalUrl } from '@/lib/urls';
 
 
+// Flatten an arbitrary React children tree to its text content. Used by the
+// raw-HTML <mermaid> handler below — react-markdown hands us the mermaid
+// source as a tree of text nodes (possibly nested through whitespace-only
+// wrappers) and the Mermaid component expects a single string.
+function flattenChildrenToText(node: React.ReactNode): string {
+  if (node == null || typeof node === 'boolean') return '';
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(flattenChildrenToText).join('');
+  if (React.isValidElement(node)) {
+    const children = (node.props as { children?: React.ReactNode }).children;
+    return flattenChildrenToText(children);
+  }
+  return '';
+}
+
 interface MarkdownRendererProps {
   content: string;
   latex?: boolean;
   slug?: string;
   slugRegistry?: Map<string, SlugRegistryEntry>;
+  /**
+   * Set when rendering a book chapter. Enables inter-chapter `.md` link
+   * rewriting and `:::container` → GitHub Alert conversion (the latter runs
+   * for everyone, but the link rewriter needs source-path context).
+   */
+  bookContext?: BookChapterLinksOptions;
 }
 
-export default function MarkdownRenderer({ content, latex = false, slug, slugRegistry }: MarkdownRendererProps) {
-  const remarkPlugins: PluggableList = [remarkGfm];
+export default function MarkdownRenderer({ content, latex = false, slug, slugRegistry, bookContext }: MarkdownRendererProps) {
+  // remark-directive must precede remark-code-group AND remark-vuepress-containers
+  // so they see parsed containerDirective nodes. Order vs remark-gfm doesn't matter
+  // — they touch disjoint node types.
+  const remarkPlugins: PluggableList = [
+    remarkGfm,
+    remarkGithubAlerts,
+    remarkDirective,
+    remarkCodeGroup,
+    remarkVuepressContainers,
+  ];
+  if (bookContext) {
+    remarkPlugins.push([remarkBookChapterLinks, bookContext]);
+  }
   const cdnBaseUrl = siteConfig.images?.cdnBaseUrl ?? '';
-  const rehypePlugins: PluggableList = [rehypeRaw, rehypeSlug, [rehypeImageMetadata, { slug, cdnBaseUrl }]];
+  // rehypeFenceMeta must run BEFORE rehypeRaw — rehypeRaw round-trips through HTML
+  // serialization, which drops node.data.meta (a non-HTML field). Copying meta to a
+  // real data-meta attribute first lets it survive the round trip.
+  const rehypePlugins: PluggableList = [rehypeFenceMeta, rehypeRaw, rehypeSlug, [rehypeImageMetadata, { slug, cdnBaseUrl }]];
 
   if (slugRegistry && slugRegistry.size > 0) {
     remarkPlugins.push([remarkWikilinks, { slugRegistry }]);
@@ -35,7 +86,15 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
 
   if (latex) {
     remarkPlugins.push(remarkMath);
-    rehypePlugins.push(rehypeKatex);
+    // Silence only KaTeX's `unicodeTextInMathMode` warnings — Chinese-language
+    // books routinely write math like `$输入$` or `$h_{隐藏状态}$` and KaTeX
+    // renders the CJK characters fine; the warning is pure noise (one log per
+    // character per chapter view). A bare `strict: 'ignore'` would silence
+    // *every* KaTeX strict check including genuinely broken math, so use a
+    // predicate that targets just this transgression.
+    rehypePlugins.push([rehypeKatex, {
+      strict: (code: string) => (code === 'unicodeTextInMathMode' ? 'ignore' : 'warn'),
+    }]);
   }
 
   const components: Components = {
@@ -70,37 +129,68 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
     pre: ({ children }) => <div className="not-prose w-full min-w-0 max-w-full">{children}</div>,
     // Style links individually to avoid hover-all issue
     a: (props) => {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { node: _node, className, ...rest } = props as React.AnchorHTMLAttributes<HTMLAnchorElement> & ExtraProps;
+      const { node, className, children, href, target, rel, ...rest } = props as React.AnchorHTMLAttributes<HTMLAnchorElement> & ExtraProps;
       // Preserve wikilink classes injected by remark-wikilinks — they have their own CSS styling
       if (className?.includes('wikilink')) {
-        return <a {...rest} className={className} />;
+        return <a {...rest} href={href} target={target} rel={rel} className={className}>{children}</a>;
+      }
+      const linkClass = "text-accent no-underline hover:underline transition-colors duration-200";
+      if (isExternalUrl(href)) {
+        // Image-as-link (`[![alt](img)](href)`): an inline arrow after the
+        // image looks like a glyph, not a hint. The HAST `node` exposes the
+        // pre-override children so we can spot an `<img>` child reliably —
+        // by the time react-markdown passes `children` to us, our own `img`
+        // override has already replaced the raw <img> with a component.
+        const hastChildren = (node && 'children' in node) ? node.children : [];
+        const isImageLink = hastChildren.length === 1 && 'tagName' in hastChildren[0] && hastChildren[0].tagName === 'img';
+        return (
+          <a
+            {...rest}
+            href={href}
+            target={target ?? '_blank'}
+            rel={rel ?? 'noopener noreferrer'}
+            className={linkClass}
+          >
+            {children}
+            {!isImageLink && <ExternalLinkIcon />}
+          </a>
+        );
       }
-      return <a {...rest} className="text-accent no-underline hover:underline transition-colors duration-200" />;
+      return <a {...rest} href={href} target={target} rel={rel} className={linkClass}>{children}</a>;
     },
     // Custom code renderer: handles 'mermaid' blocks and syntax highlighting
     code(props: React.ClassAttributes<HTMLElement> & React.HTMLAttributes<HTMLElement> & ExtraProps) {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { className, children, node: _node, ...rest } = props;
-      const match = /language-(\w+)/.exec(className || '');
+      const { className, children } = props;
+      // [^\s]+ rather than \w+ so fences like ```c++ or ```objective-c++ are detected
+      // as `c++` / `objective-c++` and not truncated to `c` at the punctuation boundary.
+      const match = /language-([^\s]+)/.exec(className || '');
       const language = match ? match[1] : '';
       const isMultiLine = String(children).includes('\n');
-      
-      // In react-markdown v10, 'inline' prop is removed. 
+
+      // In react-markdown v10, 'inline' prop is removed.
       // We use className presence (e.g. language-js) or newline presence to detect code blocks.
       if (match || isMultiLine) {
         if (language === 'mermaid') {
           return <Mermaid chart={String(children).replace(/\n$/, '')} />;
         }
+        // react-markdown v10 strips node.data before invoking overrides, so the
+        // fence meta is surfaced as a real `data-meta` attribute by rehypeFenceMeta.
+        const meta = (props as unknown as Record<string, unknown>)['data-meta'];
+        const parsedMeta = parseFenceMeta(typeof meta === 'string' ? meta : undefined);
         return (
-          <CodeBlock language={language} {...rest}>
+          <CodeBlock
+            language={language}
+            title={parsedMeta.title}
+            showLineNumbers={parsedMeta.showLineNumbers}
+            highlightLines={parsedMeta.highlightLines}
+          >
             {String(children).replace(/\n$/, '')}
           </CodeBlock>
         );
       }
 
       return (
-        <code className={className} {...rest}>
+        <code className={className}>
           {children}
         </code>
       );
@@ -134,11 +224,36 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
     // In development mode, use unoptimized images since WebP versions don't exist yet
     img: (props: React.ClassAttributes<HTMLImageElement> & React.ImgHTMLAttributes<HTMLImageElement> & ExtraProps) => {
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { src, alt, width, height, node: _node, ...rest } = props;
+      const { src, alt, width, height, node: _node, style, ...rest } = props;
       const isDev = process.env.NODE_ENV === 'development';
       const imageSrc = src as string;
       const isExternal = imageSrc?.startsWith('http') || imageSrc?.startsWith('//');
 
+      // Author-supplied inline `style` is a strong signal the <img> came from
+      // raw HTML inside the markdown (typically inline icons like social-media
+      // badges) rather than from a markdown `![alt](src)`. Markdown images
+      // never carry a style attribute. Preserve the author's styling and
+      // skip optimization for these — wrapping a 22px icon in <ExportedImage>
+      // strips the style and renders it at its natural 500px size.
+      if (style) {
+        // width / height were destructured out of `rest` above, so re-apply
+        // them here. Mixed author markup like `<img src="..." width="120"
+        // style="border-radius:4px">` should keep its explicit sizing rather
+        // than render at the SVG's natural dimensions.
+        return (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={imageSrc}
+            alt={alt || ''}
+            width={width}
+            height={height}
+            style={style}
+            {...rest}
+            fetchPriority="low"
+          />
+        );
+      }
+
       if (!isExternal) {
         const shouldBypassOptimization = shouldBypassImageOptimization(imageSrc);
         return (
@@ -152,6 +267,7 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
             unoptimized={isDev || shouldBypassOptimization}
             placeholder={shouldBypassOptimization ? 'empty' : 'blur'}
             style={(!width || !height) ? { width: '100%', height: 'auto' } : undefined}
+            fetchPriority="low"
           />
         );
       }
@@ -160,16 +276,50 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
     },
   };
 
-  // Merge custom HTML elements not in the Components type (e.g. web components used in MDX)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const allComponents = { ...components, 'rss-feed': () => <RssFeedWidget /> } as any;
+  // Merge custom HTML elements not in the Components type (e.g. web components used in MDX,
+  // and the synthetic <code-group> / <github-alert> tagNames emitted by our remark plugins).
+  //
+  // VuePress component pass-throughs: imported VuePress books may use Vue
+  // components like <Swiper>/<Slide> (image carousel), <ClientOnly>, <HomeHero>,
+  // <ChatDemo>, <GlobalTOC>. hast/React lowercases these tags, and without a
+  // handler React logs "The tag <swiper> is unrecognized in this browser". Map
+  // each one to a passive renderer so the warnings go away and inner content
+  // (where it makes sense) still appears as a graceful degradation.
+  const allComponents = {
+    ...components,
+    'rss-feed': () => <RssFeedWidget />,
+    'code-group': CodeGroup,
+    'github-alert': GithubAlert,
+    swiper: ({ children }: { children?: React.ReactNode }) => <div className="my-6 space-y-4">{children}</div>,
+    slide: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+    clientonly: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+    globaltoc: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+    homehero: () => null,
+    chatdemo: () => null,
+    // <mermaid>...graph syntax...</mermaid> is the VuePress inline form. We
+    // already handle ```mermaid fenced blocks via the `code` renderer above;
+    // route the raw-HTML form to the same Mermaid component by flattening
+    // the children to a string.
+    mermaid: ({ children }: { children?: React.ReactNode }) => (
+      <Mermaid chart={flattenChildrenToText(children).trim()} />
+    ),
+    // <GitHubWrapper>...</GitHubWrapper> wraps GitHub project links / cards
+    // in the fenix VuePress book. Pass children through unchanged — they're
+    // usually a paragraph or an <a>/<img> the author wants to display.
+    githubwrapper: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+    // <words type='span' chapter='/' /> is a VuePress word-count widget that
+    // we can't reproduce without the upstream counter. Render nothing — the
+    // surrounding prose ("全文合计 X 字") degrades to "全文合计  字".
+    words: () => null,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any;
 
   return (
     <>
     {latex && <KatexStyles />}
-    <div className="bg-background"> {/* Explicit background for better copy-paste fidelity */}
+    <ArticleCopyCleaner>
       <div className="prose prose-lg max-w-none min-w-0 overflow-x-hidden text-foreground
-            prose-headings:font-serif prose-headings:text-heading 
+            prose-headings:font-serif prose-headings:text-heading
             prose-p:text-foreground prose-p:leading-loose
             prose-strong:text-heading prose-strong:font-semibold
             prose-code:bg-muted/15 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:border prose-code:border-muted/20 prose-code:text-[0.9em] prose-code:font-medium
@@ -182,10 +332,12 @@ export default function MarkdownRenderer({ content, latex = false, slug, slugReg
           rehypePlugins={rehypePlugins}
           components={allComponents}
         >
-          {content}
+          {latex
+            ? normalizeVuepressBlockMath(normalizeVuepressContainerSyntax(content))
+            : normalizeVuepressContainerSyntax(content)}
         </ReactMarkdown>
       </div>
-    </div>
+    </ArticleCopyCleaner>
     </>
   );
 }

package/src/components/Mermaid.tsx

@@ -4,6 +4,26 @@ import React, { useEffect, useRef, useState } from "react";
 import mermaid from "mermaid";
 import { useTheme } from "next-themes";
 
+// Mermaid bundles its own KaTeX and invokes it with `{throwOnError: true,
+// displayMode: true, output: 'mathml'}` — no `strict` option, so KaTeX
+// defaults to `'warn'` and floods the console with one warning per CJK
+// character in math labels (e.g. `S["$$解码器状态：s_{t-1}$$"]`). There is
+// no `mermaid.initialize()` setting to override this. Filter the very
+// specific KaTeX warning template at the console layer; everything else
+// passes through. Idempotent under HMR.
+let consoleWarnFilterInstalled = false;
+function installConsoleWarnFilter(): void {
+  if (consoleWarnFilterInstalled || typeof window === "undefined") return;
+  consoleWarnFilterInstalled = true;
+  const originalWarn = console.warn.bind(console);
+  console.warn = (...args: unknown[]) => {
+    if (typeof args[0] === "string" && args[0].includes("[unicodeTextInMathMode]")) {
+      return;
+    }
+    originalWarn(...args);
+  };
+}
+
 interface MermaidProps {
   chart: string;
 }
@@ -28,6 +48,7 @@ const Mermaid: React.FC<MermaidProps> = ({ chart }) => {
 
   useEffect(() => {
     if (ref.current && chart && mounted) {
+      installConsoleWarnFilter();
       const currentTheme = theme === 'system' ? systemTheme : theme;
       const isDark = currentTheme === 'dark';
 
@@ -76,11 +97,21 @@ const Mermaid: React.FC<MermaidProps> = ({ chart }) => {
   }, [chart, theme, systemTheme, mounted]);
 
   return (
-    <div className="my-8 p-4 md:p-8 rounded-lg border border-muted/20 bg-muted/5 overflow-x-auto shadow-sm">
+    <div className="my-6 overflow-x-auto">
+      {/*
+        suppressHydrationWarning is intentional: Mermaid runs client-side
+        in `useEffect`, injects its SVG via `dangerouslySetInnerHTML`, and
+        then mutates the DOM further (adding `data-processed="true"` on
+        this wrapper). React's virtual DOM has no record of those
+        mutations, so any HMR-triggered re-render in dev flags the drift
+        as a hydration mismatch. Telling React this div is
+        intentionally-mutated terrain is the blessed escape hatch.
+      */}
       <div
         className="mermaid w-full flex justify-center"
         dangerouslySetInnerHTML={{ __html: svg }}
         ref={ref}
+        suppressHydrationWarning
       />
     </div>
   );

package/src/components/Navbar.tsx

@@ -91,7 +91,9 @@ export default function Navbar({ seriesList = [], booksList = [] }: NavbarProps)
   }, [isMenuOpen]);
 
   return (
-    <nav className={`fixed top-0 left-0 w-full z-50 border-b transition-all duration-300 select-none ${
+    <nav
+      data-site-nav
+      className={`fixed top-0 left-0 w-full z-50 border-b transition-all duration-300 select-none ${
       isScrolled
         ? 'border-muted/10 bg-background/90 backdrop-blur-md shadow-sm'
         : 'border-transparent bg-transparent'

package/src/components/PostList.tsx

@@ -61,7 +61,7 @@ export default function PostList({
                       <span className="shrink-0">·</span>
                     </>
                   )}
-                  <span className="shrink-0 hidden sm:inline">{post.readingTime}</span>
+                  <span className="shrink-0 hidden sm:inline">{post.readingMinutes} {t('reading_time')}</span>
                   <span className="shrink-0 hidden sm:inline">·</span>
                   <span className="shrink-0 whitespace-nowrap">{post.date}</span>
                   {post.draft && (

package/src/components/PostNavigation.tsx

@@ -37,16 +37,24 @@ export default function PostNavigation({ prev, next, currentSlug, collectionCont
   if (!effectivePrev && !effectiveNext) return null;
 
   return (
+    // suppressHydrationWarning on locale-bound nodes is a band-aid for the
+    // known static-export + client-i18n drift: SSR renders defaultLocale,
+    // `useLanguage()` hook serves the user's saved locale on hydration. The
+    // real fix is per-locale URL routing, tracked as a separate refactor.
     <nav
       className="mt-12 pt-12 border-t border-muted/20 grid grid-cols-1 sm:grid-cols-2 gap-3"
       aria-label={t('post_navigation')}
+      suppressHydrationWarning
     >
       {effectivePrev && (
         <Link
           href={postHref(effectivePrev)}
           className="group flex flex-col gap-1.5 p-4 rounded-xl border border-muted/15 hover:border-accent/30 hover:bg-accent/5 transition-all no-underline"
         >
-          <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted flex items-center gap-1.5">
+          <span
+            className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted flex items-center gap-1.5"
+            suppressHydrationWarning
+          >
             <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
               <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
             </svg>
@@ -64,7 +72,10 @@ export default function PostNavigation({ prev, next, currentSlug, collectionCont
           href={postHref(effectiveNext)}
           className={`group flex flex-col gap-1.5 p-4 rounded-xl border border-muted/15 hover:border-accent/30 hover:bg-accent/5 transition-all no-underline sm:items-end sm:text-right${!effectivePrev ? ' sm:col-start-2' : ''}`}
         >
-          <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted flex items-center gap-1.5">
+          <span
+            className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted flex items-center gap-1.5"
+            suppressHydrationWarning
+          >
             {t('next')}
             <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
               <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />