@hutusi/amytis 1.15.0 → 1.16.0

package/src/components/ExternalLinkIcon.tsx

@@ -0,0 +1,15 @@
+import { LuArrowUpRight } from 'react-icons/lu';
+
+/**
+ * Inline outward-arrow indicator appended after external-link text by
+ * `MarkdownRenderer`'s `<a>` override. Sized relative to the surrounding
+ * text and aria-hidden — the link's accessible name already carries intent.
+ */
+export default function ExternalLinkIcon() {
+  return (
+    <LuArrowUpRight
+      aria-hidden="true"
+      className="inline-block align-text-top ml-0.5 text-[0.85em] opacity-70"
+    />
+  );
+}

package/src/components/FeaturedStoriesSection.tsx

@@ -14,7 +14,7 @@ export interface FeaturedPost {
   excerpt: string;
   date: string;
   category: string;
-  readingTime: string;
+  readingMinutes: number;
   coverImage?: string;
   series?: string;
   pinned?: boolean;
@@ -110,7 +110,7 @@ export default function FeaturedStoriesSection({ allFeatured, maxItems }: Featur
                 <div className="flex items-center gap-2 text-xs font-mono text-white/60 mb-3 overflow-hidden">
                   <span className="text-accent uppercase tracking-wider truncate min-w-0">{hero.category}</span>
                   <span className="shrink-0">·</span>
-                  <span className="shrink-0 whitespace-nowrap">{hero.readingTime}</span>
+                  <span className="shrink-0 whitespace-nowrap">{hero.readingMinutes} {t('reading_time')}</span>
                   <span className="shrink-0">·</span>
                   <span className="shrink-0 whitespace-nowrap">{hero.date}</span>
                 </div>
@@ -141,7 +141,7 @@ export default function FeaturedStoriesSection({ allFeatured, maxItems }: Featur
                   <div className="flex items-center gap-2 text-xs font-mono text-muted mb-2">
                     <span className="text-accent uppercase tracking-wider truncate max-w-[4rem]">{post.category}</span>
                     <span className="shrink-0 hidden sm:inline">·</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">·</span>
                     <span className="shrink-0">{post.date}</span>
                   </div>

package/src/components/GithubAlert.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react';
+
+type AlertType = 'note' | 'tip' | 'important' | 'warning' | 'caution';
+
+const KNOWN_TYPES: ReadonlySet<AlertType> = new Set(['note', 'tip', 'important', 'warning', 'caution']);
+
+const ALERT_LABELS: Record<AlertType, string> = {
+  note: 'Note',
+  tip: 'Tip',
+  important: 'Important',
+  warning: 'Warning',
+  caution: 'Caution',
+};
+
+interface GithubAlertProps {
+  'data-alert-type'?: string;
+  /** Custom title from the directive label (e.g. `:::tip 智慧的疆界`). Falls back to ALERT_LABELS when absent. */
+  'data-alert-title'?: string;
+  children?: ReactNode;
+}
+
+function AlertIcon({ type }: { type: AlertType }) {
+  const common = {
+    width: 16,
+    height: 16,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round' as const,
+    strokeLinejoin: 'round' as const,
+    'aria-hidden': true,
+  };
+  switch (type) {
+    case 'note':
+      return (
+        <svg {...common}>
+          <circle cx="12" cy="12" r="10" />
+          <path d="M12 16v-4" />
+          <path d="M12 8h.01" />
+        </svg>
+      );
+    case 'tip':
+      return (
+        <svg {...common}>
+          <path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5" />
+          <path d="M9 18h6" />
+          <path d="M10 22h4" />
+        </svg>
+      );
+    case 'important':
+      return (
+        <svg {...common}>
+          <path d="M21 11a8 8 0 1 1-16 0 8 8 0 0 1 16 0Z" />
+          <path d="M12 8v4" />
+          <path d="M12 16h.01" />
+        </svg>
+      );
+    case 'warning':
+      return (
+        <svg {...common}>
+          <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+          <path d="M12 9v4" />
+          <path d="M12 17h.01" />
+        </svg>
+      );
+    case 'caution':
+      return (
+        <svg {...common}>
+          <polygon points="7.86 2 16.14 2 22 7.86 22 16.14 16.14 22 7.86 22 2 16.14 2 7.86 7.86 2" />
+          <path d="M12 8v4" />
+          <path d="M12 16h.01" />
+        </svg>
+      );
+  }
+}
+
+export default function GithubAlert(props: GithubAlertProps) {
+  const raw = (props['data-alert-type'] ?? '').toLowerCase();
+  if (!KNOWN_TYPES.has(raw as AlertType)) {
+    // Defensive: an unrecognized type means the plugin matched but we're missing
+    // a mapping. Fall through to a plain blockquote so content still renders.
+    return <blockquote>{props.children}</blockquote>;
+  }
+  const type = raw as AlertType;
+  const customTitle = props['data-alert-title']?.trim();
+  const title = customTitle && customTitle.length > 0 ? customTitle : ALERT_LABELS[type];
+  return (
+    <aside className={`alert alert-${type}`} role="note" aria-label={title}>
+      <div className="alert-title">
+        <AlertIcon type={type} />
+        <span>{title}</span>
+      </div>
+      <div className="alert-body">{props.children}</div>
+    </aside>
+  );
+}

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,20 +1,34 @@
+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';
 
 
 interface MarkdownRendererProps {
@@ -22,12 +36,33 @@ interface MarkdownRendererProps {
   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 +70,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 +113,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 +208,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 +251,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 +260,35 @@ 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,
+    // 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 +301,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/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" />

package/src/components/PostSidebar.tsx

@@ -70,6 +70,10 @@ export default function PostSidebar({ seriesSlug, seriesTitle, posts, collection
   useSidebarAutoScroll(sidebarRef, currentItemRef, currentSlug);
 
   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.
     <aside
       ref={sidebarRef}
       data-testid="post-sidebar"
@@ -87,7 +91,10 @@ export default function PostSidebar({ seriesSlug, seriesTitle, posts, collection
           {/* Header — always visible */}
           <div className="mb-3">
             <div className="flex items-center justify-between mb-1">
-              <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-accent">
+              <span
+                className="text-[10px] font-sans font-bold uppercase tracking-widest text-accent"
+                suppressHydrationWarning
+              >
                 {isCollectionContext ? t('collection') : t('series')}
               </span>
               <span className="text-[10px] font-mono text-muted/60">
@@ -172,6 +179,7 @@ export default function PostSidebar({ seriesSlug, seriesTitle, posts, collection
               <Link
                 href={`/series/${effectiveSlug}`}
                 className="text-xs font-sans text-muted hover:text-accent transition-colors no-underline flex items-center gap-1"
+                suppressHydrationWarning
               >
                 {isCollectionContext ? t('view_full_collection') : t('view_full_series')}
                 <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
@@ -185,7 +193,10 @@ export default function PostSidebar({ seriesSlug, seriesTitle, posts, collection
 
       {shareUrl && siteConfig.share?.enabled && (
         <div className="mt-6 pt-6 border-t border-muted/10">
-          <p className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted mb-3">
+          <p
+            className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted mb-3"
+            suppressHydrationWarning
+          >
             {t('share_post')}
           </p>
           <ShareBar url={shareUrl} title={shareTitle ?? ''} />