@hutusi/amytis 1.15.0 → 1.17.0

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>
+  );
+}

package/src/components/ImmersiveReaderTopBar.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import Link from 'next/link';
+import { useRef } from 'react';
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+import { useLanguage } from '@/components/LanguageProvider';
+import ImmersiveReadingPrefsPopover from '@/components/ImmersiveReadingPrefsPopover';
+
+interface ImmersiveReaderTopBarProps {
+  /** Breadcrumb root link — caller computes the URL (book URL or series URL). */
+  rootHref: string;
+  /** Left side of the breadcrumb. */
+  rootTitle: string;
+  /** Right side of the breadcrumb. */
+  currentTitle: string;
+}
+
+export default function ImmersiveReaderTopBar({
+  rootHref,
+  rootTitle,
+  currentTitle,
+}: ImmersiveReaderTopBarProps) {
+  const { t } = useLanguage();
+  const { sidebarOpen, prefsPanelOpen, toggleSidebar, togglePrefsPanel, exit } = useImmersiveReading();
+
+  const prefsButtonRef = useRef<HTMLButtonElement>(null);
+
+  return (
+    <header
+      // `relative z-30` is load-bearing: `backdrop-blur-md` creates a stacking
+      // context on the header, which would otherwise paint at "block-in-flow"
+      // (step 3) of the overlay's stacking context — BELOW positioned
+      // descendants of <main>, e.g. code blocks (cb-root is `position: relative`).
+      // Promoting the header to a positioned descendant with z-index pushes it
+      // above those, so the Aa popover (which renders inside the header and
+      // visually overflows down into the article area) stays on top and
+      // clickable when it overlaps a code block.
+      className="relative z-30 h-12 flex items-center gap-3 px-3 border-b border-muted/15 bg-background/95 backdrop-blur-md shrink-0 select-none"
+    >
+      <button
+        type="button"
+        onClick={toggleSidebar}
+        aria-pressed={sidebarOpen}
+        aria-label={sidebarOpen ? t('collapse_sidebar') : t('expand_sidebar')}
+        title={sidebarOpen ? t('collapse_sidebar') : t('expand_sidebar')}
+        className="h-8 w-8 inline-flex items-center justify-center rounded-md text-foreground/80 hover:text-accent hover:bg-muted/10 transition-colors"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <line x1="3" y1="6" x2="21" y2="6" />
+          <line x1="3" y1="12" x2="21" y2="12" />
+          <line x1="3" y1="18" x2="21" y2="18" />
+        </svg>
+      </button>
+
+      <div className="min-w-0 flex-1 flex items-center gap-2 text-sm">
+        <Link
+          href={rootHref}
+          className="font-serif font-semibold text-heading hover:text-accent truncate no-underline"
+          title={rootTitle}
+        >
+          {rootTitle}
+        </Link>
+        <span className="text-muted/50 hidden sm:inline" aria-hidden="true">/</span>
+        <span className="text-muted truncate hidden sm:inline" title={currentTitle}>
+          {currentTitle}
+        </span>
+      </div>
+
+      <div className="relative shrink-0">
+        <button
+          ref={prefsButtonRef}
+          type="button"
+          onClick={togglePrefsPanel}
+          aria-expanded={prefsPanelOpen}
+          aria-haspopup="dialog"
+          aria-label={t('reading_preferences')}
+          title={t('reading_preferences')}
+          className={`h-8 w-9 inline-flex items-center justify-center rounded-md transition-colors ${
+            prefsPanelOpen
+              ? 'bg-muted/10 text-accent'
+              : 'text-foreground/80 hover:text-accent hover:bg-muted/10'
+          }`}
+        >
+          <span aria-hidden="true" className="font-serif leading-none">
+            <span className="text-[15px] font-bold">A</span>
+            <span className="text-[10px]">a</span>
+          </span>
+        </button>
+        <ImmersiveReadingPrefsPopover toggleButtonRef={prefsButtonRef} />
+      </div>
+
+      <button
+        type="button"
+        onClick={exit}
+        aria-label={t('exit_reading_mode')}
+        title={t('exit_reading_mode')}
+        className="h-8 w-8 inline-flex items-center justify-center rounded-md text-foreground/80 hover:text-accent hover:bg-muted/10 transition-colors shrink-0"
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <line x1="18" y1="6" x2="6" y2="18" />
+          <line x1="6" y1="6" x2="18" y2="18" />
+        </svg>
+      </button>
+    </header>
+  );
+}

package/src/components/ImmersiveReadingFlagHandler.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useImmersiveReading } from '@/components/ImmersiveReadingProvider';
+
+/**
+ * Watches the URL for `?immersive=1` (set by the "Immersive reading" CTA on
+ * the book index page) and, when present, enters the reader and strips the
+ * flag so back-navigation doesn't loop it open.
+ *
+ * Lives in its own component so the `useSearchParams` bailout to client
+ * rendering is contained — the Suspense boundary in the parent layout only
+ * wraps this null-rendering handler, not the chapter content. Keeps the rest
+ * of the book sub-tree statically prerenderable.
+ *
+ * No one-shot ref guard: router.replace strips the flag, which updates
+ * useSearchParams reactively, which re-fires this effect with the flag gone
+ * (early return). A subsequent explicit visit to another `?immersive=1` URL
+ * in the same tab (e.g. browser back, or clicking the CTA again) re-triggers
+ * the entry — a stale ref would silently swallow that.
+ */
+export default function ImmersiveReadingFlagHandler() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+  const { enter } = useImmersiveReading();
+
+  useEffect(() => {
+    if (searchParams?.get('immersive') !== '1') return;
+    const activate = () => enter();
+    activate();
+    const params = new URLSearchParams(searchParams.toString());
+    params.delete('immersive');
+    const qs = params.toString();
+    router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false });
+  }, [searchParams, pathname, router, enter]);
+
+  return null;
+}

package/src/components/ImmersiveReadingPrefsPopover.tsx

@@ -0,0 +1,249 @@
+'use client';
+
+import { useEffect, useRef, type ReactNode, type RefObject } from 'react';
+import {
+  useImmersiveReading,
+  type ReadingColumnWidth,
+  type ReadingFontSize,
+  type ReadingTheme,
+} from '@/components/ImmersiveReadingProvider';
+import { useLanguage } from '@/components/LanguageProvider';
+import type { TranslationKey } from '@/i18n/translations';
+
+interface ImmersiveReadingPrefsPopoverProps {
+  /** The toggle button — its ref is excluded from outside-click closing so the
+   * button's onClick is the single source of truth for toggling. */
+  toggleButtonRef: RefObject<HTMLElement | null>;
+}
+
+const FONT_PREVIEW_PX: Record<ReadingFontSize, number> = {
+  s: 12,
+  m: 15,
+  l: 19,
+  xl: 24,
+};
+
+const FONT_OPTIONS: Array<{ value: ReadingFontSize; labelKey: TranslationKey }> = [
+  { value: 's', labelKey: 'size_small' },
+  { value: 'm', labelKey: 'size_medium' },
+  { value: 'l', labelKey: 'size_large' },
+  { value: 'xl', labelKey: 'size_xl' },
+];
+
+const THEME_OPTIONS: Array<{ value: ReadingTheme; labelKey: TranslationKey }> = [
+  { value: 'auto', labelKey: 'theme_auto' },
+  { value: 'light', labelKey: 'theme_light' },
+  { value: 'sepia', labelKey: 'theme_sepia' },
+  { value: 'dark', labelKey: 'theme_dark' },
+];
+
+const WIDTH_OPTIONS: Array<{ value: ReadingColumnWidth; labelKey: TranslationKey; barWidthPct: number }> = [
+  { value: 'narrow', labelKey: 'width_narrow', barWidthPct: 35 },
+  { value: 'medium', labelKey: 'width_medium', barWidthPct: 55 },
+  { value: 'wide', labelKey: 'width_wide', barWidthPct: 75 },
+  { value: 'full', labelKey: 'width_full', barWidthPct: 100 },
+];
+
+// Tailwind classes baked into the theme swatch — concrete hex / vars so the
+// reader sees the actual colours, not an approximation.
+const THEME_SWATCH_STYLE: Record<ReadingTheme, string> = {
+  auto: 'bg-gradient-to-br from-stone-50 from-50% to-stone-800 to-50% text-stone-700',
+  light: 'bg-stone-50 text-stone-900',
+  sepia: 'bg-[#f4ecd8] text-[#3b2f24]',
+  dark: 'bg-stone-800 text-stone-100',
+};
+
+function GroupHeading({ children }: { children: ReactNode }) {
+  return (
+    <div className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted/80 mb-2">
+      {children}
+    </div>
+  );
+}
+
+function OptionButton({
+  active,
+  onClick,
+  ariaLabel,
+  title,
+  children,
+  className = '',
+}: {
+  active: boolean;
+  onClick: () => void;
+  ariaLabel: string;
+  title: string;
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      aria-label={ariaLabel}
+      title={title}
+      className={`relative flex items-center justify-center rounded-lg transition-all duration-150 ${
+        active
+          ? 'ring-2 ring-accent ring-offset-2 ring-offset-background'
+          : 'ring-1 ring-muted/20 hover:ring-muted/40'
+      } ${className}`}
+    >
+      {children}
+    </button>
+  );
+}
+
+export default function ImmersiveReadingPrefsPopover({ toggleButtonRef }: ImmersiveReadingPrefsPopoverProps) {
+  const { t } = useLanguage();
+  const {
+    prefsPanelOpen,
+    fontSize,
+    readingTheme,
+    columnWidth,
+    setFontSize,
+    setReadingTheme,
+    setColumnWidth,
+    closePrefsPanel,
+    resetPrefs,
+  } = useImmersiveReading();
+
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!prefsPanelOpen) return;
+    // pointerdown unifies mouse, touch, and pen — needed so taps outside the
+    // popover dismiss it on mobile too (mousedown alone doesn't fire there
+    // reliably).
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node;
+      if (rootRef.current?.contains(target)) return;
+      if (toggleButtonRef.current?.contains(target)) return;
+      closePrefsPanel();
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => document.removeEventListener('pointerdown', onPointerDown);
+  }, [prefsPanelOpen, closePrefsPanel, toggleButtonRef]);
+
+  if (!prefsPanelOpen) return null;
+
+  return (
+    <div
+      ref={rootRef}
+      role="dialog"
+      aria-label={t('reading_preferences')}
+      className="absolute top-full right-0 mt-2 z-50 min-w-[280px] bg-background/95 backdrop-blur-md border border-muted/20 rounded-xl shadow-xl p-5 animate-slide-down"
+    >
+      {/* Font Size */}
+      <div className="mb-5">
+        <GroupHeading>{t('font_size')}</GroupHeading>
+        <div className="grid grid-cols-4 gap-2">
+          {FONT_OPTIONS.map(opt => {
+            const active = opt.value === fontSize;
+            return (
+              <OptionButton
+                key={opt.value}
+                active={active}
+                onClick={() => setFontSize(opt.value)}
+                ariaLabel={`${t('font_size')}: ${t(opt.labelKey)}`}
+                title={t(opt.labelKey)}
+                className="h-12 bg-background"
+              >
+                <span
+                  aria-hidden="true"
+                  className="font-serif font-semibold text-foreground leading-none"
+                  style={{ fontSize: `${FONT_PREVIEW_PX[opt.value]}px` }}
+                >
+                  A
+                </span>
+              </OptionButton>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Theme */}
+      <div className="mb-5">
+        <GroupHeading>{t('reading_theme')}</GroupHeading>
+        <div className="grid grid-cols-4 gap-2">
+          {THEME_OPTIONS.map(opt => {
+            const active = opt.value === readingTheme;
+            return (
+              <OptionButton
+                key={opt.value}
+                active={active}
+                onClick={() => setReadingTheme(opt.value)}
+                ariaLabel={`${t('reading_theme')}: ${t(opt.labelKey)}`}
+                title={t(opt.labelKey)}
+                className="flex-col h-14 overflow-hidden"
+              >
+                <span
+                  aria-hidden="true"
+                  className={`flex-1 w-full flex items-center justify-center text-[13px] font-serif font-semibold ${THEME_SWATCH_STYLE[opt.value]}`}
+                >
+                  Aa
+                </span>
+                <span className="block w-full text-[9px] text-muted py-0.5 bg-background border-t border-muted/15">
+                  {t(opt.labelKey)}
+                </span>
+              </OptionButton>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Width */}
+      <div>
+        <GroupHeading>{t('column_width')}</GroupHeading>
+        <div className="grid grid-cols-4 gap-2">
+          {WIDTH_OPTIONS.map(opt => {
+            const active = opt.value === columnWidth;
+            return (
+              <OptionButton
+                key={opt.value}
+                active={active}
+                onClick={() => setColumnWidth(opt.value)}
+                ariaLabel={`${t('column_width')}: ${t(opt.labelKey)}`}
+                title={t(opt.labelKey)}
+                className="h-12 bg-background"
+              >
+                <span
+                  aria-hidden="true"
+                  className="flex flex-col items-center justify-center gap-1 w-full"
+                >
+                  <span
+                    className="block h-0.5 bg-foreground/70 rounded-full"
+                    style={{ width: `${opt.barWidthPct}%` }}
+                  />
+                  <span
+                    className="block h-0.5 bg-foreground/40 rounded-full"
+                    style={{ width: `${opt.barWidthPct}%` }}
+                  />
+                  <span
+                    className="block h-0.5 bg-foreground/40 rounded-full"
+                    style={{ width: `${opt.barWidthPct}%` }}
+                  />
+                </span>
+              </OptionButton>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Reset to defaults — non-destructive (re-pickable), no confirmation. */}
+      <div className="mt-4 pt-3 border-t border-muted/15 flex justify-end">
+        <button
+          type="button"
+          onClick={resetPrefs}
+          className="text-xs font-sans text-muted hover:text-accent transition-colors inline-flex items-center gap-1.5"
+        >
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+            <path d="M3 12a9 9 0 1 0 3-6.7" />
+            <polyline points="3 4 3 10 9 10" />
+          </svg>
+          {t('reset_to_defaults')}
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/ImmersiveReadingProvider.tsx

@@ -0,0 +1,168 @@
+'use client';
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import { DEFAULT_PREFS, readStoredPrefs, writeStoredPrefs } from '@/lib/immersive-reading-prefs';
+
+export type ReadingFontSize = 's' | 'm' | 'l' | 'xl';
+export type ReadingTheme = 'auto' | 'light' | 'sepia' | 'dark';
+export type ReadingColumnWidth = 'narrow' | 'medium' | 'wide' | 'full';
+
+interface ImmersiveReadingContextValue {
+  enabled: boolean;
+  fontSize: ReadingFontSize;
+  readingTheme: ReadingTheme;
+  columnWidth: ReadingColumnWidth;
+  sidebarOpen: boolean;
+  prefsPanelOpen: boolean;
+  toggle: () => void;
+  enter: () => void;
+  exit: () => void;
+  setFontSize: (size: ReadingFontSize) => void;
+  setReadingTheme: (theme: ReadingTheme) => void;
+  setColumnWidth: (width: ReadingColumnWidth) => void;
+  toggleSidebar: () => void;
+  setSidebarOpen: (open: boolean) => void;
+  togglePrefsPanel: () => void;
+  closePrefsPanel: () => void;
+  resetPrefs: () => void;
+}
+
+const ImmersiveReadingContext = createContext<ImmersiveReadingContextValue | undefined>(undefined);
+
+export function ImmersiveReadingProvider({ children }: { children: ReactNode }) {
+  // Initial state intentionally matches DEFAULT_PREFS so SSR/CSR render
+  // identically — localStorage is read in an effect after mount.
+  const [enabled, setEnabled] = useState(false);
+  const [fontSize, setFontSize] = useState<ReadingFontSize>(DEFAULT_PREFS.fontSize);
+  const [readingTheme, setReadingTheme] = useState<ReadingTheme>(DEFAULT_PREFS.readingTheme);
+  const [columnWidth, setColumnWidth] = useState<ReadingColumnWidth>(DEFAULT_PREFS.columnWidth);
+  const [sidebarOpen, setSidebarOpen] = useState(DEFAULT_PREFS.sidebarOpen);
+  const [prefsPanelOpen, setPrefsPanelOpen] = useState(false);
+
+  const enter = useCallback(() => setEnabled(true), []);
+  const exit = useCallback(() => {
+    setEnabled(false);
+    setPrefsPanelOpen(false);
+  }, []);
+  const toggle = useCallback(() => {
+    setEnabled(prev => {
+      if (prev) setPrefsPanelOpen(false);
+      return !prev;
+    });
+  }, []);
+  const toggleSidebar = useCallback(() => setSidebarOpen(prev => !prev), []);
+  const togglePrefsPanel = useCallback(() => setPrefsPanelOpen(prev => !prev), []);
+  const closePrefsPanel = useCallback(() => setPrefsPanelOpen(false), []);
+  const resetPrefs = useCallback(() => {
+    setFontSize(DEFAULT_PREFS.fontSize);
+    setReadingTheme(DEFAULT_PREFS.readingTheme);
+    setColumnWidth(DEFAULT_PREFS.columnWidth);
+    setSidebarOpen(DEFAULT_PREFS.sidebarOpen);
+  }, []);
+
+  // Hydrate prefs from localStorage on mount, then persist on every change.
+  // The persist effect itself flips `hydratedRef` on its first run and
+  // no-ops — without this, the initial commit's persist run would race
+  // ahead of the hydration setters (state hasn't re-rendered yet, so it'd
+  // read the React defaults from the closure and clobber the stored blob
+  // with them before the next render restores the correct values).
+  const hydratedRef = useRef(false);
+  useEffect(() => {
+    const stored = readStoredPrefs();
+    const applyStored = () => {
+      setFontSize(stored.fontSize);
+      setReadingTheme(stored.readingTheme);
+      setColumnWidth(stored.columnWidth);
+      setSidebarOpen(stored.sidebarOpen);
+    };
+    applyStored();
+  }, []);
+  useEffect(() => {
+    if (!hydratedRef.current) {
+      hydratedRef.current = true;
+      return;
+    }
+    writeStoredPrefs({ fontSize, readingTheme, columnWidth, sidebarOpen });
+  }, [fontSize, readingTheme, columnWidth, sidebarOpen]);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+    if (enabled) {
+      root.dataset.immersive = 'true';
+      const previousOverflow = document.body.style.overflow;
+      document.body.style.overflow = 'hidden';
+      return () => {
+        delete root.dataset.immersive;
+        document.body.style.overflow = previousOverflow;
+      };
+    }
+    delete root.dataset.immersive;
+  }, [enabled]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      if (prefsPanelOpen) {
+        setPrefsPanelOpen(false);
+      } else {
+        setEnabled(false);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [enabled, prefsPanelOpen]);
+
+  // Auto-collapse the sidebar on narrow viewports when entering immersive mode
+  // (or when resizing into the narrow range). Without this, the sidebar
+  // overlaps the article on tablets / phones. Deliberately one-directional:
+  // we never auto-open on a wide-resize, so a user who manually closed the
+  // sidebar on desktop keeps that preference instead of having it overridden.
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+    const mq = window.matchMedia('(max-width: 1023px)');
+    const collapseIfNarrow = (matches: boolean) => {
+      if (matches) setSidebarOpen(false);
+    };
+    collapseIfNarrow(mq.matches);
+    const onChange = (e: MediaQueryListEvent) => collapseIfNarrow(e.matches);
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [enabled]);
+
+  return (
+    <ImmersiveReadingContext.Provider
+      value={{
+        enabled,
+        fontSize,
+        readingTheme,
+        columnWidth,
+        sidebarOpen,
+        prefsPanelOpen,
+        toggle,
+        enter,
+        exit,
+        setFontSize,
+        setReadingTheme,
+        setColumnWidth,
+        toggleSidebar,
+        setSidebarOpen,
+        togglePrefsPanel,
+        closePrefsPanel,
+        resetPrefs,
+      }}
+    >
+      {children}
+    </ImmersiveReadingContext.Provider>
+  );
+}
+
+export function useImmersiveReading(): ImmersiveReadingContextValue {
+  const ctx = useContext(ImmersiveReadingContext);
+  if (!ctx) {
+    throw new Error('useImmersiveReading must be used within an ImmersiveReadingProvider');
+  }
+  return ctx;
+}