@hutusi/amytis 1.15.0 → 1.17.0

package/src/components/PostReadingShell.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReader from '@/components/ImmersiveReader';
+import ImmersiveSeriesSidebar from '@/components/ImmersiveSeriesSidebar';
+import { getSeriesUrl } from '@/lib/urls';
+import type { CollectionContext, Heading, PostData } from '@/lib/markdown';
+
+interface PostReadingShellProps {
+  post: { slug: string; title: string; series?: string; headings?: Heading[] };
+  seriesSlug?: string;
+  seriesTitle?: string;
+  seriesPosts?: PostData[];
+  collectionContexts?: CollectionContext[];
+  /** Slim article subtree to render inside the overlay (header + body + nav).
+   *  Pre-built in PostLayout so the heavy MarkdownRenderer/RstRenderer is the
+   *  same ReactElement reference as in `children` — only one of the two ever
+   *  mounts, so the body renders exactly once. */
+  overlayArticle: ReactNode;
+  /** Full normal-mode layout subtree (sidebar + article + comments + nav +
+   *  related etc.). Rendered when immersive is off OR the post isn't in a
+   *  series. */
+  children: ReactNode;
+}
+
+/**
+ * Post-side analog of BookReadingShell. Branches on the immersive `enabled`
+ * flag AND whether the post belongs to a series — without a series there's no
+ * meaningful TOC for the overlay sidebar, so the toggle is a no-op and we
+ * just render the normal layout.
+ */
+export default function PostReadingShell({
+  post,
+  seriesSlug,
+  seriesTitle,
+  seriesPosts,
+  collectionContexts,
+  overlayArticle,
+  children,
+}: PostReadingShellProps) {
+  const { enabled } = useImmersiveReading();
+  const inSeries = !!(seriesSlug && seriesPosts && seriesPosts.length > 0);
+
+  if (!enabled || !inSeries) {
+    return <>{children}</>;
+  }
+
+  return (
+    <ImmersiveReader
+      rootHref={getSeriesUrl(seriesSlug)}
+      rootTitle={seriesTitle ?? seriesSlug}
+      currentTitle={post.title}
+      sidebar={
+        <ImmersiveSeriesSidebar
+          seriesSlug={seriesSlug}
+          seriesTitle={seriesTitle ?? seriesSlug}
+          posts={seriesPosts}
+          collectionContexts={collectionContexts}
+          currentSlug={post.slug}
+          headings={post.headings}
+        />
+      }
+    >
+      {overlayArticle}
+    </ImmersiveReader>
+  );
+}

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 ?? ''} />

package/src/components/ReadingProgressBar.tsx

@@ -12,7 +12,7 @@ export default function ReadingProgressBar() {
   if (progress <= 0) return null;
 
   return (
-    <div className="fixed top-16 left-0 w-full h-0.5 z-50 bg-muted/10">
+    <div data-reading-progress className="fixed top-16 left-0 w-full h-0.5 z-50 bg-muted/10">
       <div
         className="h-full bg-accent/70 transition-[width] duration-150 ease-out"
         style={{ width: `${progress}%` }}

package/src/components/RstRenderer.test.tsx

@@ -1,10 +1,10 @@
 import { describe, expect, test } from 'bun:test';
-import { renderToStaticMarkup } from 'react-dom/server';
 import RstRenderer from './RstRenderer';
+import { renderAsync } from '@/test-utils/render';
 
 describe('RstRenderer', () => {
-  test('renders pre-rendered html when available', () => {
-    const html = renderToStaticMarkup(
+  test('renders pre-rendered html when available', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={
@@ -28,8 +28,8 @@ describe('RstRenderer', () => {
     expect(html).not.toContain('javascript:alert(4)');
   });
 
-  test('blocks data urls on images', () => {
-    const html = renderToStaticMarkup(
+  test('blocks data urls on images', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<p><img src="data:image/svg+xml,<svg onload=alert(1)>" alt="Bad" /></p>'}
@@ -40,8 +40,8 @@ describe('RstRenderer', () => {
     expect(html).not.toContain('data:image');
   });
 
-  test('preserves MathML elements', () => {
-    const html = renderToStaticMarkup(
+  test('preserves MathML elements', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<math xmlns="http://www.w3.org/1998/Math/MathML"><mrow><mi>x</mi><mo>=</mo><mn>2</mn></mrow></math>'}
@@ -53,8 +53,8 @@ describe('RstRenderer', () => {
     expect(html).toContain('<mi>x</mi>');
   });
 
-  test('wraps rendered rst tables with the same scroll container pattern as markdown', () => {
-    const html = renderToStaticMarkup(
+  test('wraps rendered rst tables with the same scroll container pattern as markdown', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content="Fallback body"
         html={'<table><thead><tr><th>A</th></tr></thead><tbody><tr><td>B</td></tr></tbody></table>'}
@@ -67,8 +67,8 @@ describe('RstRenderer', () => {
     expect(html).toContain('<td>B</td>');
   });
 
-  test('renders converted headings, links, and code blocks through the markdown renderer', () => {
-    const html = renderToStaticMarkup(
+  test('renders converted headings, links, and code blocks through the markdown renderer', async () => {
+    const html = await renderAsync(
       <RstRenderer
         content={[
           'Section',
@@ -85,9 +85,9 @@ describe('RstRenderer', () => {
 
     expect(html).toContain('Section');
     expect(html).toContain('https://example.com');
-    expect(html).toContain('language-ts');
-    expect(html).toContain('<code class="language-ts"');
-    expect(html).toContain('token keyword');
-    expect(html).toContain('token number');
+    // Shiki produces a .shiki container with language-aware token spans, not Prism's
+    // legacy class="language-ts" + token markup. Assert the new highlighter ran.
+    expect(html).toContain('class="shiki');
+    expect(html).toContain('export');
   });
 });

package/src/components/RstRenderer.tsx

@@ -2,6 +2,7 @@ import MarkdownRenderer from '@/components/MarkdownRenderer';
 import KatexStyles from '@/components/KatexStyles';
 import type { SlugRegistryEntry } from '@/lib/markdown';
 import { rstToMarkdown } from '@/lib/rst';
+import { applyShikiToRstHtml } from '@/lib/shiki-rst';
 import sanitizeHtml from 'sanitize-html';
 
 interface RstRendererProps {
@@ -30,6 +31,11 @@ const allowedTags = [
   'figure',
   'figcaption',
   'aside',
+  // Tabbed code groups (CSS-only via radio + label). Without these on the
+  // allowlist, the rST path drops to stacked code blocks with no tabs.
+  // transformTags below restricts `input` to type="radio" only.
+  'input',
+  'label',
   'math',
   'annotation',
   'annotation-xml',
@@ -64,6 +70,13 @@ const allowedTags = [
   'semantics',
 ];
 
+// Shiki emits inline `style="--shiki-light:#...; --shiki-dark:#..."` CSS vars on
+// every token <span> when running in dual-theme mode, plus our custom transformers
+// add `data-language`, `data-line-numbers`, `data-highlighted-line`, and `data-title`
+// to <pre>/<span>. Stripping any of these silently kills syntax highlighting in rST
+// output while leaving Markdown unaffected — covered by RstRenderer.test.tsx.
+const codeBlockAttrs = ['style', 'data-language', 'data-line', 'data-line-numbers', 'data-highlighted-line', 'data-title', 'tabindex'];
+
 const allowedAttributes: sanitizeHtml.IOptions['allowedAttributes'] = {
   ...sanitizeHtml.defaults.allowedAttributes,
   '*': ['id', 'class', 'title', 'lang', 'dir', 'role', 'aria-label', 'aria-hidden'],
@@ -77,6 +90,15 @@ const allowedAttributes: sanitizeHtml.IOptions['allowedAttributes'] = {
   math: ['display', 'xmlns'],
   annotation: ['encoding'],
   'annotation-xml': ['encoding'],
+  pre: ['class', 'style', ...codeBlockAttrs],
+  code: ['class', 'style', ...codeBlockAttrs],
+  span: ['class', 'style', ...codeBlockAttrs],
+  div: ['class', 'style', 'data-group-id', 'data-panel', ...codeBlockAttrs],
+  // Tabbed code groups: input is restricted to type=radio via transformTags.
+  // Defense-in-depth: even if an unexpected attr slips in, the CSS-only tab
+  // mechanism can't do anything dangerous with a stray radio button.
+  input: ['type', 'name', 'id', 'checked', 'data-idx', 'aria-controls', 'tabindex', 'class'],
+  label: ['for', 'class', 'role', 'aria-controls', 'tabindex', 'data-cg-icon'],
 };
 
 function sanitizeRenderedHtml(html: string): string {
@@ -88,12 +110,25 @@ function sanitizeRenderedHtml(html: string): string {
       img: ['http', 'https'],
     },
     allowProtocolRelative: false,
+    transformTags: {
+      // Restrict <input> to type="radio" only. Anything else gets stripped.
+      // Prevents an rST author from injecting password/file/etc. inputs.
+      input: (tagName, attribs) => {
+        if (attribs.type !== 'radio') {
+          return { tagName: 'span', attribs: {} };
+        }
+        return { tagName, attribs };
+      },
+    },
   });
 }
 
-export default function RstRenderer({ content, html, latex = false, slug, slugRegistry }: RstRendererProps) {
+export default async function RstRenderer({ content, html, latex = false, slug, slugRegistry }: RstRendererProps) {
   if (html) {
-    const sanitizedHtml = sanitizeRenderedHtml(html).replace(
+    // The docutils pass emits opaque <pre data-amytis-code> markers; run them through
+    // Shiki here (server-side, build-time for SSG) before sanitizing.
+    const highlighted = await applyShikiToRstHtml(html);
+    const sanitizedHtml = sanitizeRenderedHtml(highlighted).replace(
       /<table\b([^>]*)>/g,
       '<div class="rst-table-wrapper"><table$1>'
     ).replace(/<\/table>/g, '</table></div>');

package/src/components/Search.tsx

@@ -130,8 +130,11 @@ export default function Search() {
   // True while debounce is pending — suppress "no results" flash
   const isTyping = query.length > 0 && query !== debouncedQuery;
 
-  // Load recent searches on mount
+  // Load recent searches on mount. localStorage is unavailable during SSR,
+  // so this can't be hoisted into useState's initializer without breaking
+  // hydration — the mount-only effect is the documented React pattern.
   useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setRecentSearches(loadRecentSearches());
   }, []);
 
@@ -142,16 +145,22 @@ export default function Search() {
     }
   }, [isOpen]);
 
-  // Debounce query
+  // Debounce query. The sync reset when `query` is empty is intentional:
+  // skipping it would leave stale results visible for DEBOUNCE_MS after the
+  // user clears the input.
   useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!query) { setDebouncedQuery(''); return; }
     const timer = setTimeout(() => setDebouncedQuery(query), DEBOUNCE_MS);
     return () => clearTimeout(timer);
   }, [query]);
 
-  // Run Pagefind search on debounced query
+  // Run Pagefind search on debounced query. Synchronous resets when the
+  // query becomes empty are the simplest way to clear results state without
+  // threading conditional renders through every consumer of allResults.
   useEffect(() => {
     if (!debouncedQuery) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setAllResults([]);
       setActiveIndex(-1);
       setActiveType('All');
@@ -214,17 +223,22 @@ export default function Search() {
     return () => window.removeEventListener('keydown', handleKeyDown);
   }, []);
 
-  // Focus on open; full reset on close
+  // Focus on open; full reset on close. The 6 resets are batched into a
+  // single React render — the rule's "cascading renders" warning doesn't
+  // apply when state changes are batched as siblings, only when one update
+  // triggers the next.
   useEffect(() => {
     if (isOpen) {
       setTimeout(() => inputRef.current?.focus(), 100);
     } else {
+      /* eslint-disable react-hooks/set-state-in-effect */
       setQuery('');
       setDebouncedQuery('');
       setAllResults([]);
       setActiveIndex(-1);
       setActiveType('All');
       setIsFetching(false);
+      /* eslint-enable react-hooks/set-state-in-effect */
     }
   }, [isOpen]);
 

package/src/components/SelectedBooksSection.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import CoverImage from './CoverImage';
 import HorizontalScroll from './HorizontalScroll';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getBooksListUrl, getBookUrl, getBookChapterUrl } from '@/lib/urls';
 
 export interface BookItem {
@@ -16,19 +17,37 @@ export interface BookItem {
   authors: string[];
   chapterCount: number;
   firstChapter?: string;
+  date: string;
 }
 
+type BookOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface SelectedBooksSectionProps {
   books: BookItem[];
   maxItems?: number;
+  order?: BookOrder;
+}
+
+function canonicalOrder(books: BookItem[], order: BookOrder): BookItem[] {
+  if (order === 'date-desc') return [...books].sort(byDateDesc);
+  if (order === 'date-asc')  return [...books].sort(byDateAsc);
+  // For 'shuffle': SSR-stable canonical order (input is already date-desc from getAllBooks).
+  // The post-mount useEffect swaps to a random permutation on the client.
+  return books;
 }
 
-export default function SelectedBooksSection({ books, maxItems = 4 }: SelectedBooksSectionProps) {
+export default function SelectedBooksSection({ books, maxItems = 4, order = 'shuffle' }: SelectedBooksSectionProps) {
   const { t } = useLanguage();
-  const [displayed, setDisplayed] = useState(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(books, dailySeed).slice(0, maxItems);
-  });
+  const [displayed, setDisplayed] = useState(() => canonicalOrder(books, order).slice(0, maxItems));
+
+  // Shuffle on mount so every reload re-rolls. SSR's canonical render is stable; the
+  // post-hydration swap is the intentional client-only behaviour, not a sync issue.
+  useEffect(() => {
+    if (order === 'shuffle') {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setDisplayed(shuffle(books).slice(0, maxItems));
+    }
+  }, [books, maxItems, order]);
 
   const handleShuffle = useCallback(() => {
     setDisplayed(shuffle(books).slice(0, maxItems));
@@ -41,7 +60,7 @@ export default function SelectedBooksSection({ books, maxItems = 4 }: SelectedBo
       <div className="flex items-center justify-between mb-8">
         <h2 className="text-2xl sm:text-3xl font-serif font-bold text-heading">{t('selected_books')}</h2>
         <div className="flex items-center gap-4">
-          {books.length > maxItems && (
+          {order === 'shuffle' && books.length > maxItems && (
             <button
               onClick={handleShuffle}
               className="rounded-sm text-sm text-muted transition-colors hover:text-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50 focus-visible:ring-offset-2"

package/src/components/SeriesCatalog.tsx

@@ -68,7 +68,7 @@ export default function SeriesCatalog({ posts, startIndex = 0, totalPosts, colle
                     <div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs font-mono text-muted mb-3">
                       <span>{post.date}</span>
                       <span className="hidden sm:inline">•</span>
-                      <span className="text-accent/80">{post.readingTime}</span>
+                      <span className="text-accent/80">{post.readingMinutes} {t('reading_time')}</span>
                       {post.category && (
                         <>
                           <span className="hidden sm:inline">•</span>

package/src/components/ShareBar.tsx

@@ -77,6 +77,10 @@ export default function ShareBar({ url, title, className = '' }: ShareBarProps)
   const btnClass = 'inline-flex items-center justify-center w-8 h-8 rounded text-muted hover:text-accent hover:bg-muted/10 transition-colors';
 
   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.
     <div className={`flex flex-row flex-wrap gap-1 ${className}`}>
       {platforms.map((platform) => {
         const { label, Icon } = PLATFORM_META[platform];
@@ -90,6 +94,7 @@ export default function ShareBar({ url, title, className = '' }: ShareBarProps)
               title={copyLabel}
               aria-label={copyLabel}
               className={`${btnClass} ${copied ? 'text-accent' : ''}`}
+              suppressHydrationWarning
             >
               {copied ? <LuCheck size={16} /> : <Icon size={16} />}
             </button>

package/src/components/TocPanel.tsx

@@ -19,9 +19,16 @@ export default function TocPanel({ headings, className = '' }: TocPanelProps) {
   if (headings.length === 0) return null;
 
   return (
-    <nav aria-label={t('on_this_page')} className={className}>
+    // 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 aria-label={t('on_this_page')} className={className} suppressHydrationWarning>
       <div className="flex items-center justify-between mb-3">
-        <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted">
+        <span
+          className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted"
+          suppressHydrationWarning
+        >
           {t('on_this_page')}
         </span>
         <button
@@ -30,6 +37,7 @@ export default function TocPanel({ headings, className = '' }: TocPanelProps) {
           className="text-muted hover:text-foreground transition-colors"
           aria-expanded={!collapsed}
           aria-label={collapsed ? t('toc_expand') : t('toc_collapse')}
+          suppressHydrationWarning
         >
           <svg
             className={`w-3.5 h-3.5 transition-transform duration-200 ${collapsed ? '' : 'rotate-180'}`}

package/src/hooks/useActiveHeading.ts

@@ -2,11 +2,12 @@
 
 import { useState, useEffect } from 'react';
 import type { Heading } from '@/lib/markdown';
-import { useScrollY } from './useScrollY';
+import { getScrollableAncestor } from '@/lib/scroll-utils';
+
+const ACTIVATION_LINE_PX = 100;
 
 export function useActiveHeading(headings: Heading[], enabled = true): string {
   const [activeId, setActiveId] = useState('');
-  const scrollY = useScrollY();
 
   useEffect(() => {
     if (!enabled || headings.length === 0) return;
@@ -14,19 +15,40 @@ export function useActiveHeading(headings: Heading[], enabled = true): string {
     const elements = headings
       .map(h => document.getElementById(h.id))
       .filter(Boolean) as HTMLElement[];
-
     if (elements.length === 0) return;
 
-    const scrollPosition = scrollY + 100;
-    let current = elements[0];
-    for (const el of elements) {
-      if (el.offsetTop <= scrollPosition) current = el;
-      else break;
-    }
-
-    const rafId = requestAnimationFrame(() => { if (current) setActiveId(current.id); });
-    return () => cancelAnimationFrame(rafId);
-  }, [scrollY, headings, enabled]);
+    // In immersive reading mode the chapter scrolls inside the overlay's
+    // <main>, not the window, so subscribe to whichever ancestor is doing
+    // the scrolling. `getScrollableAncestor` returns null for normal pages.
+    const container = getScrollableAncestor(elements[0]);
+    const target: HTMLElement | Window = container ?? window;
+
+    let rafId = 0;
+    const compute = () => {
+      const containerTop = container
+        ? container.getBoundingClientRect().top
+        : 0;
+      let current = elements[0];
+      for (const el of elements) {
+        const top = el.getBoundingClientRect().top - containerTop;
+        if (top <= ACTIVATION_LINE_PX) current = el;
+        else break;
+      }
+      setActiveId(current.id);
+    };
+
+    const onScroll = () => {
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(compute);
+    };
+
+    compute();
+    target.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      cancelAnimationFrame(rafId);
+      target.removeEventListener('scroll', onScroll);
+    };
+  }, [enabled, headings]);
 
   return activeId;
 }

package/src/hooks/useSidebarAutoScroll.ts

@@ -1,18 +1,42 @@
 'use client';
 
-import { useEffect, type RefObject } from 'react';
+import { useEffect, useRef, type RefObject } from 'react';
 
+/**
+ * Scrolls the current sidebar item into view when `dep` changes.
+ *
+ * - **First run** (sidebar just mounted — e.g. the reader landed on a page
+ *   mid-TOC): centres the current item so there's context above and below.
+ * - **Subsequent runs** (the reader clicked another sidebar link to
+ *   navigate): only scrolls if the new current item is out of view, and
+ *   only enough to bring it on-screen. Crucially, if the target was
+ *   already visible, the sidebar's scroll position does **not** change —
+ *   clicking a chapter right in front of you no longer makes the sidebar
+ *   jump.
+ *
+ * The previous implementation always hard-centred via `scrollTop = ...`
+ * regardless of visibility, which on long book TOCs visibly snapped the
+ * sidebar back toward the top whenever the new current chapter was in
+ * the upper half. `scrollIntoView({ block: 'nearest' })` handles the
+ * "skip if already visible" case natively. The `sidebarRef` first
+ * parameter is kept for API stability (all callers still pass it); the
+ * new implementation doesn't need it because `scrollIntoView` walks up
+ * to the nearest scrollable ancestor on its own.
+ */
 export function useSidebarAutoScroll(
-  sidebarRef: RefObject<HTMLElement | null>,
+  _sidebarRef: RefObject<HTMLElement | null>,
   itemRef: RefObject<HTMLElement | null>,
   dep: unknown,
 ): void {
+  const hasRunRef = useRef(false);
   useEffect(() => {
-    if (itemRef.current && sidebarRef.current) {
-      const item = itemRef.current;
-      const sidebar = sidebarRef.current;
-      sidebar.scrollTop = item.offsetTop - sidebar.clientHeight / 2 + item.offsetHeight / 2;
-    }
+    const item = itemRef.current;
+    if (!item) return;
+    item.scrollIntoView({
+      block: hasRunRef.current ? 'nearest' : 'center',
+      inline: 'nearest',
+    });
+    hasRunRef.current = true;
   // refs are stable; only re-run when dep changes
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dep]);

package/src/i18n/translations.ts

@@ -14,6 +14,7 @@ export const translations = {
     view_archive: "View Archive",
     written_by: "Written by",
     reading_time: "min read",
+    words: "words",
     next_page: "Next",
     prev_page: "Prev",
     back_to_home: "Back to Home",
@@ -144,6 +145,27 @@ export const translations = {
     archive_description: "A complete chronological archive of all articles.",
     tags_description: "Explore topics spanning all articles and flow notes.",
     posts_description: "Browse all articles.",
+    immersive_reading: "Immersive reading",
+    exit_reading_mode: "Exit reading mode",
+    reading_preferences: "Reading preferences",
+    font_size: "Font size",
+    reading_theme: "Theme",
+    column_width: "Width",
+    theme_auto: "Auto",
+    theme_light: "Light",
+    theme_sepia: "Sepia",
+    theme_dark: "Dark",
+    size_small: "S",
+    size_medium: "M",
+    size_large: "L",
+    size_xl: "XL",
+    width_narrow: "Narrow",
+    width_medium: "Medium",
+    width_wide: "Wide",
+    width_full: "Full",
+    collapse_sidebar: "Collapse sidebar",
+    expand_sidebar: "Expand sidebar",
+    reset_to_defaults: "Reset to defaults",
   },
   zh: {
     home: "首页",
@@ -160,6 +182,7 @@ export const translations = {
     view_archive: "查看归档",
     written_by: "作者",
     reading_time: "分钟阅读",
+    words: "字",
     next_page: "下一页",
     prev_page: "上一页",
     back_to_home: "返回首页",
@@ -290,6 +313,27 @@ export const translations = {
     archive_description: "全部文章的时间轴归档。",
     tags_description: "浏览全部文章与随笔的主题标签。",
     posts_description: "浏览全部文章。",
+    immersive_reading: "沉浸式阅读",
+    exit_reading_mode: "退出阅读模式",
+    reading_preferences: "阅读设置",
+    font_size: "字号",
+    reading_theme: "主题",
+    column_width: "宽度",
+    theme_auto: "自动",
+    theme_light: "浅色",
+    theme_sepia: "护眼",
+    theme_dark: "深色",
+    size_small: "小",
+    size_medium: "中",
+    size_large: "大",
+    size_xl: "特大",
+    width_narrow: "窄",
+    width_medium: "中",
+    width_wide: "宽",
+    width_full: "全宽",
+    collapse_sidebar: "收起目录",
+    expand_sidebar: "展开目录",
+    reset_to_defaults: "恢复默认",
   },
 };