@hutusi/amytis 1.16.0 → 1.17.0

package/src/app/globals.css

@@ -996,3 +996,70 @@ html.dark .rst-rendered aside.admonition-danger {
   font-weight: 600;
   color: var(--heading);
 }
+
+/* Immersive reading mode.
+ * Toggled by ImmersiveReadingProvider via the html element's data-immersive
+ * attribute. The fullscreen ImmersiveReader overlay also covers the site
+ * chrome, but these rules are kept as defense-in-depth (and reset the
+ * navbar offset so the scroll padding doesn't peek through the overlay).
+ * Do not strip the data-site-nav / data-site-footer / data-reading-progress
+ * hooks.
+ *
+ * IMPORTANT: every attribute selector below uses an explicit ="true" value,
+ * and no rule starts with `html[...]`. Tailwind v4 / Lightning CSS silently
+ * dead-code-eliminates rules that start with `html[...]` and bare attribute
+ * selectors like `[data-site-nav]` — they end up missing from the compiled
+ * CSS bundle even though they're written here in source. The surviving
+ * patterns are bare-attribute-with-value (e.g. `[data-palette="blue"]`,
+ * `[data-line-numbers="true"]`) and class-prefixed compounds (e.g.
+ * `.dark[data-palette="blue"]`). React serialises a bare JSX
+ * `data-site-nav` prop to the HTML `data-site-nav="true"`, so writing
+ * `="true"` here costs nothing on the component side. */
+[data-immersive="true"] [data-site-nav="true"],
+[data-immersive="true"] [data-site-footer="true"],
+[data-immersive="true"] [data-reading-progress="true"] {
+  display: none;
+}
+[data-immersive="true"] #main-content {
+  padding-top: 0;
+}
+
+/* Font-size in the reader overlay is driven by a CSS var set inline on the
+ * overlay container. A var (not stacked text-* classes) sidesteps fighting
+ * the prose-lg specificity. */
+[data-reader-overlay="true"] .prose {
+  font-size: var(--reading-font-size, 1.125rem);
+}
+
+/* Reading-theme overrides — scoped to the overlay so they compose with the
+ * site's light/dark theme without leaking outside. 'auto' inherits the site
+ * theme (no override needed); 'light' / 'dark' / 'sepia' set their own
+ * variables. The overlay also adds Tailwind's `.dark` class on its container
+ * when readingTheme === 'dark' so `dark:prose-invert` activates regardless of
+ * the site theme. Shiki code blocks keep their own theme on purpose. */
+[data-reader-overlay="true"][data-reading-theme="light"] {
+  --background: #fafaf9;
+  --foreground: #44403c;
+  --heading: #1c1917;
+  --muted: #78716c;
+}
+[data-reader-overlay="true"][data-reading-theme="dark"] {
+  --background: #292524;
+  --foreground: #f5f5f4;
+  --heading: #fafaf9;
+  --muted: #a8a29e;
+}
+[data-reader-overlay="true"][data-reading-theme="sepia"] {
+  --background: #f4ecd8;
+  --foreground: #5b4636;
+  --heading: #3b2f24;
+  --muted: #8a7a66;
+}
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h1,
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h2,
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h3,
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h4,
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h5,
+[data-reader-overlay="true"][data-reading-theme="sepia"] .prose h6 {
+  color: var(--heading);
+}

package/src/app/page.tsx

@@ -34,6 +34,7 @@ type HomepageSection = {
   enabled?: boolean;
   weight: number;
   maxItems?: number;
+  order?: 'shuffle' | 'date-desc' | 'date-asc';
 };
 
 export default function Home() {
@@ -76,6 +77,7 @@ export default function Home() {
           url: `/series/${slug}`,
           postCount: seriesPosts.length,
           topPosts: seriesPosts.slice(0, 3).map(p => ({ slug: p.slug, title: p.title })),
+          date: seriesData?.date ?? seriesPosts[0]?.date ?? '',
         };
       })
     : [];
@@ -89,6 +91,7 @@ export default function Home() {
         authors: b.authors,
         chapterCount: b.chapters.length,
         firstChapter: b.chapters[0]?.id,
+        date: b.date,
       }))
     : [];
 
@@ -133,6 +136,7 @@ export default function Home() {
             key="featured-series"
             allSeries={seriesItems}
             maxItems={section.maxItems ?? 6}
+            order={section.order ?? 'shuffle'}
           />
         );
       case 'featured-books':
@@ -142,6 +146,7 @@ export default function Home() {
             key="featured-books"
             books={bookItems}
             maxItems={section.maxItems ?? 4}
+            order={section.order ?? 'shuffle'}
           />
         );
       case 'featured-posts':
@@ -151,6 +156,7 @@ export default function Home() {
             key="featured-posts"
             allFeatured={featuredItems}
             maxItems={section.maxItems ?? 4}
+            order={section.order ?? 'shuffle'}
           />
         );
       case 'latest-posts':

package/src/app/posts/layout.tsx

@@ -0,0 +1,20 @@
+import { Suspense, type ReactNode } from 'react';
+import { ImmersiveReadingProvider } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReadingFlagHandler from '@/components/ImmersiveReadingFlagHandler';
+
+// Mirror of `src/app/[slug]/layout.tsx` for the default-path post URL
+// (`/posts/<slug>`). Series posts can live under either URL pattern
+// depending on the `series.autoPaths` setting in site.config.ts — having the
+// provider mounted at both layout boundaries means immersive state persists
+// across in-series navigation regardless of which pattern the user's site
+// uses. Same Suspense isolation around the flag handler.
+export default function PostsLayout({ children }: { children: ReactNode }) {
+  return (
+    <ImmersiveReadingProvider>
+      <Suspense fallback={null}>
+        <ImmersiveReadingFlagHandler />
+      </Suspense>
+      {children}
+    </ImmersiveReadingProvider>
+  );
+}

package/src/app/series/[slug]/page.tsx

@@ -156,16 +156,40 @@ export default async function SeriesPage({ params }: { params: Promise<{ slug: s
             const firstPost = (seriesData?.sort === 'date-asc' || seriesData?.sort === 'manual' || isCollection)
               ? allPosts[0]
               : allPosts[allPosts.length - 1];
+            const primaryHref = isCollection ? getPostUrlInCollection(firstPost, slug) : getPostUrl(firstPost);
+            // primaryHref already carries `?collection=<slug>` for collection
+            // contexts (see getPostUrlInCollection), so naïvely appending
+            // `?immersive=1` would produce an invalid double-`?` URL and the
+            // flag handler would never fire. Use the right separator.
+            const immersiveHref = `${primaryHref}${primaryHref.includes('?') ? '&' : '?'}immersive=1`;
             return (
-            <Link
-              href={isCollection ? getPostUrlInCollection(firstPost, slug) : getPostUrl(firstPost)}
-              className="mt-6 inline-flex items-center gap-2 px-5 py-2.5 rounded-full bg-accent text-white text-sm font-medium hover:bg-accent/90 transition-colors no-underline"
-            >
-              {t('start_reading')}
-              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-                <polyline points="9 18 15 12 9 6" />
-              </svg>
-            </Link>
+              <div className="mt-6 flex flex-wrap items-center justify-center gap-3">
+                <Link
+                  href={primaryHref}
+                  className="inline-flex items-center gap-2 px-5 py-2.5 rounded-full bg-accent text-white text-sm font-medium hover:bg-accent/90 transition-colors no-underline"
+                >
+                  {t('start_reading')}
+                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                    <polyline points="9 18 15 12 9 6" />
+                  </svg>
+                </Link>
+                {/* Secondary CTA — opens the first post of the series in immersive mode.
+                    The `?immersive=1` query param is read by ImmersiveReadingProvider
+                    on mount, which calls enter() then strips the flag from the URL
+                    so back-navigation doesn't re-trigger it. */}
+                <Link
+                  href={immersiveHref}
+                  className="inline-flex items-center gap-2 px-5 py-2.5 border border-muted/30 text-foreground/80 hover:text-accent hover:border-accent/50 rounded-full text-sm font-medium no-underline transition-colors"
+                >
+                  <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" />
+                  </svg>
+                  {t('immersive_reading')}
+                </Link>
+              </div>
             );
           })()}
           {authors.length > 0 && (

package/src/components/BookReadingShell.tsx

@@ -0,0 +1,145 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import BookSidebar from '@/components/BookSidebar';
+import BookMobileNav from '@/components/BookMobileNav';
+import PrevNextNav from '@/components/PrevNextNav';
+import ReadingProgressBar from '@/components/ReadingProgressBar';
+import Comments from '@/components/Comments';
+import { useLanguage } from '@/components/LanguageProvider';
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReader from '@/components/ImmersiveReader';
+import ImmersiveToggleButton from '@/components/ImmersiveToggleButton';
+import type { BookTocItem, BookChapterEntry, Heading } from '@/lib/markdown';
+import { getBookUrl } from '@/lib/urls';
+
+interface BookReadingShellProps {
+  book: {
+    slug: string;
+    title: string;
+    toc: BookTocItem[];
+    chapters: BookChapterEntry[];
+    showChapterExcerpt: boolean;
+  };
+  chapter: {
+    slug: string;
+    title: string;
+    wordCount: number;
+    readingMinutes: number;
+    excerpt?: string;
+    headings: Heading[];
+  };
+  prev: { href: string; title: string } | null;
+  next: { href: string; title: string } | null;
+  comments: { slug: string; postUrl: string } | null;
+  children: ReactNode;
+}
+
+export default function BookReadingShell({
+  book,
+  chapter,
+  prev,
+  next,
+  comments,
+  children,
+}: BookReadingShellProps) {
+  const { t } = useLanguage();
+  const { enabled } = useImmersiveReading();
+
+  const chapterHeader = (
+    <header className="mb-12 pb-8 border-b border-muted/10">
+      <div className="flex items-center gap-3 text-xs font-sans text-muted mb-4">
+        <span className="uppercase tracking-widest font-semibold text-accent">
+          {t('chapter')}
+        </span>
+        <span className="w-1 h-1 rounded-full bg-muted/30" />
+        <span className="font-mono">
+          {chapter.wordCount.toLocaleString()} {t('words')}
+        </span>
+        <span className="w-1 h-1 rounded-full bg-muted/30" />
+        <span className="font-mono text-muted/70">
+          {chapter.readingMinutes} {t('reading_time')}
+        </span>
+        {/* ImmersiveToggleButton hides itself when enabled — no outer wrap
+            needed beyond the layout positioning. */}
+        <span className="ml-auto">
+          <ImmersiveToggleButton />
+        </span>
+      </div>
+
+      <h1 className="text-3xl md:text-4xl font-serif font-bold text-heading leading-tight mb-4">
+        {chapter.title}
+      </h1>
+
+      {book.showChapterExcerpt && chapter.excerpt && (
+        <p className="text-lg text-muted font-serif italic leading-relaxed">
+          {chapter.excerpt}
+        </p>
+      )}
+    </header>
+  );
+
+  const prevNext = (
+    <div className="mt-16 pt-8 border-t border-muted/10">
+      <PrevNextNav prev={prev} next={next} size="lg" />
+    </div>
+  );
+
+  if (enabled) {
+    return (
+      <ImmersiveReader
+        rootHref={getBookUrl(book.slug)}
+        rootTitle={book.title}
+        currentTitle={chapter.title}
+        sidebar={
+          <BookSidebar
+            mode="fill"
+            bookSlug={book.slug}
+            bookTitle={book.title}
+            toc={book.toc}
+            chapters={book.chapters}
+            currentChapter={chapter.slug}
+            headings={chapter.headings}
+          />
+        }
+      >
+        {chapterHeader}
+        {children}
+        {prevNext}
+      </ImmersiveReader>
+    );
+  }
+
+  return (
+    <div className="layout-container">
+      <ReadingProgressBar />
+      <div className="grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start">
+        <BookSidebar
+          bookSlug={book.slug}
+          bookTitle={book.title}
+          toc={book.toc}
+          chapters={book.chapters}
+          currentChapter={chapter.slug}
+          headings={chapter.headings}
+        />
+
+        <article className="min-w-0 w-full max-w-3xl mx-auto overflow-x-hidden">
+          <div className="lg:hidden mb-8">
+            <BookMobileNav
+              bookSlug={book.slug}
+              bookTitle={book.title}
+              toc={book.toc}
+              chapters={book.chapters}
+              currentChapter={chapter.slug}
+            />
+          </div>
+
+          {chapterHeader}
+          {children}
+          {comments && <Comments slug={comments.slug} postUrl={comments.postUrl} />}
+          {prevNext}
+        </article>
+      </div>
+    </div>
+  );
+}

package/src/components/CuratedSeriesSection.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import HorizontalScroll from './HorizontalScroll';
 import CoverImage from './CoverImage';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getPostUrl, getSeriesListUrl } from '@/lib/urls';
 
 export interface SeriesItem {
@@ -16,21 +17,38 @@ export interface SeriesItem {
   url: string;
   postCount: number;
   topPosts: { slug: string; title: string }[];
+  date: string;
 }
 
+type SeriesOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface CuratedSeriesSectionProps {
   allSeries: SeriesItem[];
   maxItems: number;
+  order?: SeriesOrder;
+}
+
+function canonicalOrder(series: SeriesItem[], order: SeriesOrder): SeriesItem[] {
+  if (order === 'date-desc') return [...series].sort(byDateDesc);
+  if (order === 'date-asc')  return [...series].sort(byDateAsc);
+  return series;
 }
 
-export default function CuratedSeriesSection({ allSeries, maxItems }: CuratedSeriesSectionProps) {
+export default function CuratedSeriesSection({ allSeries, maxItems, order = 'shuffle' }: CuratedSeriesSectionProps) {
   const { t } = useLanguage();
-  // Use a daily seed so SSR and client hydration agree on the initial order,
-  // preventing a visible reshuffle flash on page load.
-  const [displayed, setDisplayed] = useState(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(allSeries, dailySeed).slice(0, maxItems);
-  });
+  // SSR renders the canonical input order so server and client agree on first paint.
+  // For 'shuffle', the post-mount useEffect swaps to a fresh random permutation,
+  // so every reload re-rolls without any hydration mismatch.
+  const [displayed, setDisplayed] = useState(() => canonicalOrder(allSeries, 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(allSeries).slice(0, maxItems));
+    }
+  }, [allSeries, maxItems, order]);
 
   const handleShuffle = useCallback(() => {
     setDisplayed(shuffle(allSeries).slice(0, maxItems));
@@ -43,7 +61,7 @@ export default function CuratedSeriesSection({ allSeries, maxItems }: CuratedSer
       <div className="flex items-center justify-between mb-8">
         <h2 className="text-2xl sm:text-3xl font-serif font-bold text-heading">{t('curated_series')}</h2>
         <div className="flex items-center gap-4">
-          {allSeries.length > maxItems && (
+          {order === 'shuffle' && allSeries.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/FeaturedStoriesSection.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useEffect, useCallback } from 'react';
 import Link from 'next/link';
 import CoverImage from './CoverImage';
 import { useLanguage } from './LanguageProvider';
-import { shuffle, shuffleSeeded } from '@/lib/shuffle';
+import { shuffle } from '@/lib/shuffle';
+import { byDateAsc, byDateDesc } from '@/lib/sort';
 import { getPostUrl } from '@/lib/urls';
 
 export interface FeaturedPost {
@@ -20,56 +21,76 @@ export interface FeaturedPost {
   pinned?: boolean;
 }
 
+type PostOrder = 'shuffle' | 'date-desc' | 'date-asc';
+
 interface FeaturedStoriesSectionProps {
   allFeatured: FeaturedPost[];
   maxItems: number;
+  order?: PostOrder;
+}
+
+function canonicalOrder(posts: FeaturedPost[], order: PostOrder): FeaturedPost[] {
+  if (order === 'date-desc') return [...posts].sort(byDateDesc);
+  if (order === 'date-asc')  return [...posts].sort(byDateAsc);
+  return posts;
 }
 
-function buildDisplayed(allFeatured: FeaturedPost[], maxItems: number, shuffledNonPinned: FeaturedPost[]): FeaturedPost[] {
+function buildDisplayed(allFeatured: FeaturedPost[], maxItems: number, orderedNonPinned: FeaturedPost[]): FeaturedPost[] {
   const pinned = allFeatured.filter(p => p.pinned);
-  const nonPinned = allFeatured.filter(p => !p.pinned);
 
-  const hero = pinned[0] ?? nonPinned[0];
+  const hero = pinned[0] ?? orderedNonPinned[0];
   if (!hero) return [];
 
   const maxSecondaries = maxItems - 1;
   const fixedSecondaries = pinned.slice(1, maxSecondaries + 1); // cap to available secondary slots
-  const shuffleSlots = Math.max(0, maxSecondaries - fixedSecondaries.length);
+  const fillSlots = Math.max(0, maxSecondaries - fixedSecondaries.length);
 
   // Non-pinned pool excludes the hero if the hero is non-pinned
   const heroIsNonPinned = !hero.pinned;
-  const shufflePool = heroIsNonPinned ? nonPinned.filter(p => p.slug !== hero.slug) : nonPinned;
-  const shuffledSlice = shuffledNonPinned.filter(p => shufflePool.some(q => q.slug === p.slug)).slice(0, shuffleSlots);
+  const fillPool = heroIsNonPinned ? orderedNonPinned.filter(p => p.slug !== hero.slug) : orderedNonPinned;
+  const fillSlice = fillPool.slice(0, fillSlots);
 
-  return [hero, ...fixedSecondaries, ...shuffledSlice];
+  return [hero, ...fixedSecondaries, ...fillSlice];
 }
 
-export default function FeaturedStoriesSection({ allFeatured, maxItems }: FeaturedStoriesSectionProps) {
+export default function FeaturedStoriesSection({ allFeatured, maxItems, order = 'shuffle' }: FeaturedStoriesSectionProps) {
   const { t } = useLanguage();
 
   const nonPinned = allFeatured.filter(p => !p.pinned);
 
-  // Use a daily seed so SSR and client hydration agree on the initial order,
-  // preventing a visible reshuffle flash on page load.
-  const [shuffledNonPinned, setShuffledNonPinned] = useState<FeaturedPost[]>(() => {
-    const dailySeed = Math.floor(Date.now() / 86400000);
-    return shuffleSeeded(nonPinned, dailySeed);
-  });
+  // SSR renders the canonical input order so server and client agree on first paint.
+  // For 'shuffle', the post-mount useEffect swaps to a fresh random permutation,
+  // so every reload re-rolls without any hydration mismatch.
+  const [orderedNonPinned, setOrderedNonPinned] = useState<FeaturedPost[]>(() => canonicalOrder(nonPinned, order));
+
+  // 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
+      setOrderedNonPinned(shuffle(nonPinned));
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [allFeatured, order]);
 
   const handleShuffle = useCallback(() => {
-    setShuffledNonPinned(shuffle(nonPinned));
+    setOrderedNonPinned(shuffle(nonPinned));
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [allFeatured]);
 
-  const displayed = buildDisplayed(allFeatured, maxItems, shuffledNonPinned);
+  const displayed = buildDisplayed(allFeatured, maxItems, orderedNonPinned);
 
   if (displayed.length === 0) return null;
 
-  // Show shuffle button only when there are more non-pinned posts than available shuffle slots
+  // Show shuffle button only when shuffling AND there's at least one non-pinned slot
+  // AND there are more non-pinned posts than available slots
   const pinned = allFeatured.filter(p => p.pinned);
   const fixedCount = 1 + Math.min(pinned.slice(1).length, maxItems - 1);
   const shuffleSlots = Math.max(0, maxItems - fixedCount);
-  const canShuffle = nonPinned.length > shuffleSlots + (pinned.length === 0 ? 1 : 0);
+  const canShuffle =
+    order === 'shuffle'
+    && shuffleSlots > 0
+    && nonPinned.length > shuffleSlots + (pinned.length === 0 ? 1 : 0);
 
   const [hero, ...secondary] = displayed;
 

package/src/components/Footer.tsx

@@ -11,7 +11,7 @@ export default function Footer() {
   const { t, language } = useLanguage();
   
   return (
-    <footer className="bg-muted/5 border-t border-muted/10 mt-auto select-none">
+    <footer data-site-footer className="bg-muted/5 border-t border-muted/10 mt-auto select-none">
       <div className="max-w-6xl mx-auto px-6 py-10 lg:py-16">
         <div className="grid grid-cols-2 lg:grid-cols-4 gap-8 lg:gap-12 mb-10 lg:mb-12">
           {/* Brand */}

package/src/components/ImmersiveReader.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import ImmersiveReaderTopBar from '@/components/ImmersiveReaderTopBar';
+import {
+  useImmersiveReading,
+  type ReadingColumnWidth,
+  type ReadingFontSize,
+} from '@/components/ImmersiveReadingProvider';
+
+const FONT_SIZE_REM: Record<ReadingFontSize, string> = {
+  s: '1rem',
+  m: '1.125rem',
+  l: '1.25rem',
+  xl: '1.5rem',
+};
+
+const COLUMN_WIDTH_CLASS: Record<ReadingColumnWidth, string> = {
+  narrow: 'max-w-2xl',
+  medium: 'max-w-3xl',
+  wide: 'max-w-4xl',
+  full: 'max-w-none',
+};
+
+const COLUMN_PADDING_CLASS: Record<ReadingColumnWidth, string> = {
+  narrow: 'px-6 sm:px-8',
+  medium: 'px-6 sm:px-8',
+  wide: 'px-6 sm:px-8',
+  full: 'px-6 sm:px-10',
+};
+
+interface ImmersiveReaderProps {
+  /** Breadcrumb root link — book detail page for books, series index for series. */
+  rootHref: string;
+  /** Left side of the top-bar breadcrumb (book title or series title). */
+  rootTitle: string;
+  /** Right side of the breadcrumb (chapter or post title). */
+  currentTitle: string;
+  /** Pre-rendered sidebar element. Caller passes `<BookSidebar mode="fill" ...>`
+   *  or `<SeriesList mode="fill" ...>` so the overlay stays content-type-agnostic. */
+  sidebar: ReactNode;
+  children: ReactNode;
+}
+
+export default function ImmersiveReader({
+  rootHref,
+  rootTitle,
+  currentTitle,
+  sidebar,
+  children,
+}: ImmersiveReaderProps) {
+  const { fontSize, readingTheme, columnWidth, sidebarOpen } = useImmersiveReading();
+
+  const mainRef = useRef<HTMLElement>(null);
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const main = mainRef.current;
+    if (!main) return;
+    let rafId = 0;
+    const compute = () => {
+      const scrollable = main.scrollHeight - main.clientHeight;
+      const pct =
+        scrollable > 0
+          ? Math.min(100, Math.max(0, (main.scrollTop / scrollable) * 100))
+          : 0;
+      setProgress(pct);
+    };
+    const onScroll = () => {
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(compute);
+    };
+    compute();
+    main.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      cancelAnimationFrame(rafId);
+      main.removeEventListener('scroll', onScroll);
+    };
+  }, []);
+
+  const overlayStyle: CSSProperties = {
+    ['--reading-font-size' as keyof CSSProperties]: FONT_SIZE_REM[fontSize],
+  } as CSSProperties;
+
+  return (
+    <div
+      data-reader-overlay
+      data-reading-theme={readingTheme}
+      style={overlayStyle}
+      // `dark` is added when readingTheme === 'dark' so Tailwind's `dark:`
+      // variants (notably `dark:prose-invert` in MarkdownRenderer) activate
+      // inside the overlay even when the site itself is in light mode.
+      className={`fixed inset-0 z-40 flex flex-col bg-background text-foreground ${
+        readingTheme === 'dark' ? 'dark' : ''
+      }`}
+      role="dialog"
+      aria-modal="true"
+      aria-label={rootTitle}
+    >
+      <ImmersiveReaderTopBar
+        rootHref={rootHref}
+        rootTitle={rootTitle}
+        currentTitle={currentTitle}
+      />
+
+      {progress > 0 && (
+        <div className="h-0.5 w-full bg-muted/10 shrink-0">
+          <div
+            className="h-full bg-accent/70 transition-[width] duration-150 ease-out"
+            style={{ width: `${progress}%` }}
+          />
+        </div>
+      )}
+
+      <div className="flex-1 min-h-0 flex">
+        {sidebarOpen && (
+          <aside className="w-[280px] shrink-0 border-r border-muted/15 bg-background/60">
+            {sidebar}
+          </aside>
+        )}
+
+        <main ref={mainRef} className="flex-1 min-w-0 overflow-y-auto">
+          <article className={`${COLUMN_WIDTH_CLASS[columnWidth]} mx-auto ${COLUMN_PADDING_CLASS[columnWidth]} py-10`}>
+            {children}
+          </article>
+        </main>
+      </div>
+    </div>
+  );
+}