@hutusi/amytis 1.16.0 → 1.17.0

package/src/layouts/BookLayout.tsx

@@ -1,12 +1,7 @@
 import path from 'path';
 import { BookData, BookChapterData, getBookDirPath } from '@/lib/markdown';
 import MarkdownRenderer from '@/components/MarkdownRenderer';
-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 { t } from '@/lib/i18n';
+import BookReadingShell from '@/components/BookReadingShell';
 import { getBookChapterUrl } from '@/lib/urls';
 import { siteConfig } from '../../site.config';
 import { resolveCommentable } from '@/lib/comments';
@@ -33,89 +28,51 @@ export default function BookLayout({ book, chapter }: BookLayoutProps) {
     imageSlug = parentDir === '.' ? `books/${book.slug}` : `books/${book.slug}/${parentDir}`;
   }
 
-  return (
-    <div className="layout-container lg:max-w-7xl">
-      <ReadingProgressBar />
-      <div className="grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start">
-        {/* Left: Sidebar */}
-        <BookSidebar
-          bookSlug={book.slug}
-          bookTitle={book.title}
-          toc={book.toc}
-          chapters={book.chapters}
-          currentChapter={chapter.slug}
-          headings={chapter.headings}
-        />
-
-        {/* Main content */}
-        <article className="min-w-0 w-full max-w-3xl overflow-x-hidden">
-          {/* Mobile nav */}
-          <div className="lg:hidden mb-8">
-            <BookMobileNav
-              bookSlug={book.slug}
-              bookTitle={book.title}
-              toc={book.toc}
-              chapters={book.chapters}
-              currentChapter={chapter.slug}
-            />
-          </div>
-
-          {/* Chapter header */}
-          <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>
-            </div>
-
-            <h1 className="text-3xl md:text-4xl font-serif font-bold text-heading leading-tight mb-4">
-              {chapter.title}
-            </h1>
+  const prev = chapter.prevChapter
+    ? { href: getBookChapterUrl(book.slug, chapter.prevChapter.id), title: chapter.prevChapter.title }
+    : null;
+  const next = chapter.nextChapter
+    ? { href: getBookChapterUrl(book.slug, chapter.nextChapter.id), title: chapter.nextChapter.title }
+    : null;
+  const comments = resolveCommentable(chapter.commentable, 'bookChapters')
+    ? {
+        slug: `books/${book.slug}/${chapter.slug}`,
+        postUrl: `${siteConfig.baseUrl.replace(/\/+$/, '')}${getBookChapterUrl(book.slug, chapter.slug)}`,
+      }
+    : null;
 
-            {book.showChapterExcerpt && chapter.excerpt && (
-              <p className="text-lg text-muted font-serif italic leading-relaxed">
-                {chapter.excerpt}
-              </p>
-            )}
-          </header>
-
-          {/* Content */}
-          <MarkdownRenderer
-            content={chapter.content}
-            latex={chapter.latex}
-            slug={imageSlug}
-            bookContext={{
-              bookSlug: book.slug,
-              bookDir,
-              chapterSourcePath: chapter.sourcePath,
-              validChapterIds,
-            }}
-          />
-
-          {/* Comments */}
-          {resolveCommentable(chapter.commentable, 'bookChapters') && (
-            <Comments
-              slug={`books/${book.slug}/${chapter.slug}`}
-              postUrl={`${siteConfig.baseUrl.replace(/\/+$/, '')}${getBookChapterUrl(book.slug, chapter.slug)}`}
-            />
-          )}
-
-          {/* Prev/Next navigation */}
-          <div className="mt-16 pt-8 border-t border-muted/10">
-            <PrevNextNav
-              prev={chapter.prevChapter ? { href: getBookChapterUrl(book.slug, chapter.prevChapter.id), title: chapter.prevChapter.title } : null}
-              next={chapter.nextChapter ? { href: getBookChapterUrl(book.slug, chapter.nextChapter.id), title: chapter.nextChapter.title } : null}
-              size="lg"
-            />
-          </div>
-        </article>
-      </div>
-    </div>
+  return (
+    <BookReadingShell
+      book={{
+        slug: book.slug,
+        title: book.title,
+        toc: book.toc,
+        chapters: book.chapters,
+        showChapterExcerpt: book.showChapterExcerpt,
+      }}
+      chapter={{
+        slug: chapter.slug,
+        title: chapter.title,
+        wordCount: chapter.wordCount,
+        readingMinutes: chapter.readingMinutes,
+        excerpt: chapter.excerpt,
+        headings: chapter.headings,
+      }}
+      prev={prev}
+      next={next}
+      comments={comments}
+    >
+      <MarkdownRenderer
+        content={chapter.content}
+        latex={chapter.latex}
+        slug={imageSlug}
+        bookContext={{
+          bookSlug: book.slug,
+          bookDir,
+          chapterSourcePath: chapter.sourcePath,
+          validChapterIds,
+        }}
+      />
+    </BookReadingShell>
   );
 }

package/src/layouts/PostLayout.tsx

@@ -15,6 +15,8 @@ import ReadingProgressBar from '@/components/ReadingProgressBar';
 import PostNavigation from '@/components/PostNavigation';
 import AuthorCard from '@/components/AuthorCard';
 import ShareBar from '@/components/ShareBar';
+import ImmersiveToggleButton from '@/components/ImmersiveToggleButton';
+import PostReadingShell from '@/components/PostReadingShell';
 import { siteConfig } from '../../site.config';
 import { t } from '@/lib/i18n';
 import { getPostUrl, getStaticPageUrl } from '@/lib/urls';
@@ -46,142 +48,179 @@ export default function PostLayout({ post, relatedPosts, seriesPosts, seriesTitl
     ? <RstRenderer content={post.content} html={post.renderedHtml} latex={post.latex} slug={post.imageBaseSlug} slugRegistry={slugRegistry} />
     : <MarkdownRenderer content={post.content} latex={post.latex} slug={post.imageBaseSlug} slugRegistry={slugRegistry} />;
 
-  return (
-    <div className="layout-container">
-      <ReadingProgressBar />
-      <div className={showSidebar
-        ? 'grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start'
-        : 'max-w-6xl mx-auto'
-      }>
-        {/* Left sidebar: series nav + page TOC */}
-        {showSidebar && (
-          <Suspense fallback={null}>
-            <PostSidebar
-              seriesSlug={hasSeries ? post.series : undefined}
-              seriesTitle={hasSeries ? (seriesTitle || post.series) : undefined}
-              posts={hasSeries ? seriesPosts : undefined}
-              collectionContexts={collectionContexts}
-              currentSlug={post.slug}
-              headings={showToc ? post.headings : []}
-              shareUrl={postUrl}
-              shareTitle={post.title}
-            />
-          </Suspense>
+  // The article <header> is identical in both the normal and the immersive
+  // article subtrees — extracting it as a variable lets us reference it in
+  // both places (only one of the two trees ever mounts, so it renders once).
+  // Includes the immersive toggle when the post is in a series.
+  const articleHeader = (
+    <header className="mb-16 border-b border-muted/10 pb-8">
+      {post.draft && (
+        <div className="mb-4">
+          <span className="text-xs font-bold text-red-500 bg-red-100 dark:bg-red-900/30 px-2 py-1 rounded tracking-widest inline-block">
+            DRAFT
+          </span>
+        </div>
+      )}
+      <div className="flex items-center gap-3 text-xs font-sans text-muted mb-6">
+        <span className="uppercase tracking-widest font-semibold text-accent">
+          {post.category}
+        </span>
+        <span className="w-1 h-1 rounded-full bg-muted/30" />
+        <time className="font-mono" data-pagefind-meta="date[content]">{post.date}</time>
+        <span className="w-1 h-1 rounded-full bg-muted/30" />
+        <span className="font-mono">
+          {post.wordCount.toLocaleString()} {t('words')}
+        </span>
+        <span className="w-1 h-1 rounded-full bg-muted/30" />
+        <span className="font-mono text-muted/70">{post.readingMinutes} {t('reading_time')}</span>
+        {hasSeries && (
+          <span className="ml-auto">
+            <ImmersiveToggleButton />
+          </span>
         )}
+      </div>
 
-        <article className="min-w-0 w-full max-w-3xl mx-auto overflow-x-hidden">
-          <header className="mb-16 border-b border-muted/10 pb-8">
-            {post.draft && (
-              <div className="mb-4">
-                <span className="text-xs font-bold text-red-500 bg-red-100 dark:bg-red-900/30 px-2 py-1 rounded tracking-widest inline-block">
-                  DRAFT
-                </span>
-              </div>
-            )}
-            <div className="flex items-center gap-3 text-xs font-sans text-muted mb-6">
-              <span className="uppercase tracking-widest font-semibold text-accent">
-                {post.category}
-              </span>
-              <span className="w-1 h-1 rounded-full bg-muted/30" />
-              <time className="font-mono" data-pagefind-meta="date[content]">{post.date}</time>
-              <span className="w-1 h-1 rounded-full bg-muted/30" />
-              <span className="font-mono">
-                {post.wordCount.toLocaleString()} {t('words')}
+      <h1 className="text-4xl md:text-5xl font-serif font-bold text-heading leading-tight mb-4">
+        {post.title}
+      </h1>
+
+      {post.subtitle && (
+        <p className="text-xl md:text-2xl font-serif italic text-muted leading-snug mb-6">
+          {post.subtitle}
+        </p>
+      )}
+
+      {siteConfig.posts?.authors?.showInHeader !== false && post.authors.length > 0 && (
+        <div className="flex items-center gap-2 mb-8 text-sm font-serif italic text-muted">
+          <span>{t('written_by')}</span>
+          <div className="flex items-center gap-1">
+            {post.authors.map((author, index) => (
+              <span key={author} className="flex items-center">
+                <Link
+                  href={`/authors/${getAuthorSlug(author)}`}
+                  className="text-foreground hover:text-accent no-underline transition-colors duration-200"
+                >
+                  {author}
+                </Link>
+                {index < post.authors.length - 1 && <span className="mr-1">,</span>}
               </span>
-              <span className="w-1 h-1 rounded-full bg-muted/30" />
-              <span className="font-mono text-muted/70">{post.readingMinutes} {t('reading_time')}</span>
-            </div>
-
-            <h1 className="text-4xl md:text-5xl font-serif font-bold text-heading leading-tight mb-4">
-              {post.title}
-            </h1>
-
-            {post.subtitle && (
-              <p className="text-xl md:text-2xl font-serif italic text-muted leading-snug mb-6">
-                {post.subtitle}
-              </p>
-            )}
+            ))}
+          </div>
+        </div>
+      )}
+
+      {post.excerpt && (
+        <p className="text-xl text-foreground font-serif italic leading-relaxed mb-8">
+          {post.excerpt}
+        </p>
+      )}
+
+      {post.tags && post.tags.length > 0 && (
+        <div className="flex flex-wrap gap-2">
+          {post.tags.map((tag) => (
+            <Tag key={tag} tag={tag} variant="default" />
+          ))}
+        </div>
+      )}
+    </header>
+  );
+
+  // Slim subtree for the immersive overlay: header + body + prev/next nav. We
+  // deliberately skip AuthorCard / ShareBar / Comments / RelatedPosts here —
+  // the reader is focused on long-form reading; chrome lives in normal mode.
+  const overlayArticle = (
+    <>
+      {articleHeader}
+      {bodyRenderer}
+      <div className="mt-16 pt-8 border-t border-muted/10">
+        <Suspense fallback={null}>
+          <PostNavigation prev={prevPost ?? null} next={nextPost ?? null} currentSlug={post.slug} collectionContexts={collectionContexts} />
+        </Suspense>
+      </div>
+    </>
+  );
+
+  return (
+    <PostReadingShell
+      post={post}
+      seriesSlug={hasSeries ? post.series : undefined}
+      seriesTitle={hasSeries ? (seriesTitle || post.series) : undefined}
+      seriesPosts={hasSeries ? seriesPosts : undefined}
+      collectionContexts={collectionContexts}
+      overlayArticle={overlayArticle}
+    >
+      <div className="layout-container">
+        <ReadingProgressBar />
+        <div className={showSidebar
+          ? 'grid grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)] gap-8 items-start'
+          : 'max-w-6xl mx-auto'
+        }>
+          {/* Left sidebar: series nav + page TOC */}
+          {showSidebar && (
+            <Suspense fallback={null}>
+              <PostSidebar
+                seriesSlug={hasSeries ? post.series : undefined}
+                seriesTitle={hasSeries ? (seriesTitle || post.series) : undefined}
+                posts={hasSeries ? seriesPosts : undefined}
+                collectionContexts={collectionContexts}
+                currentSlug={post.slug}
+                headings={showToc ? post.headings : []}
+                shareUrl={postUrl}
+                shareTitle={post.title}
+              />
+            </Suspense>
+          )}
 
-            {siteConfig.posts?.authors?.showInHeader !== false && post.authors.length > 0 && (
-              <div className="flex items-center gap-2 mb-8 text-sm font-serif italic text-muted">
-                <span>{t('written_by')}</span>
-                <div className="flex items-center gap-1">
-                  {post.authors.map((author, index) => (
-                    <span key={author} className="flex items-center">
-                      <Link
-                        href={`/authors/${getAuthorSlug(author)}`}
-                        className="text-foreground hover:text-accent no-underline transition-colors duration-200"
-                      >
-                        {author}
-                      </Link>
-                      {index < post.authors.length - 1 && <span className="mr-1">,</span>}
-                    </span>
-                  ))}
-                </div>
+          <article className="min-w-0 w-full max-w-3xl mx-auto overflow-x-hidden">
+            {articleHeader}
+
+            {(hasSeries || (collectionContexts && collectionContexts.length > 0)) && (
+              <div className="lg:hidden mb-12">
+                <Suspense fallback={null}>
+                  <SeriesList seriesSlug={hasSeries ? post.series! : undefined} seriesTitle={hasSeries ? (seriesTitle || post.series!) : undefined} posts={hasSeries ? seriesPosts! : undefined} collectionContexts={collectionContexts} currentSlug={post.slug} />
+                </Suspense>
               </div>
             )}
 
-            {post.excerpt && (
-              <p className="text-xl text-foreground font-serif italic leading-relaxed mb-8">
-                {post.excerpt}
-              </p>
+            {bodyRenderer}
+
+            {siteConfig.posts?.authors?.showAuthorCard !== false && (
+              <AuthorCard authors={post.authors} />
             )}
 
             {post.tags && post.tags.length > 0 && (
-              <div className="flex flex-wrap gap-2">
+              <div className="mt-12 pt-12 border-t border-muted/20 flex flex-wrap items-center gap-2">
+                <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted mr-1">{t('tags')}</span>
                 {post.tags.map((tag) => (
                   <Tag key={tag} tag={tag} variant="default" />
                 ))}
               </div>
             )}
-          </header>
-
-          {(hasSeries || (collectionContexts && collectionContexts.length > 0)) && (
-            <div className="lg:hidden mb-12">
-              <Suspense fallback={null}>
-                <SeriesList seriesSlug={hasSeries ? post.series! : undefined} seriesTitle={hasSeries ? (seriesTitle || post.series!) : undefined} posts={hasSeries ? seriesPosts! : undefined} collectionContexts={collectionContexts} currentSlug={post.slug} />
-              </Suspense>
-            </div>
-          )}
-
-          {bodyRenderer}
 
-          {siteConfig.posts?.authors?.showAuthorCard !== false && (
-            <AuthorCard authors={post.authors} />
-          )}
-
-          {post.tags && post.tags.length > 0 && (
-            <div className="mt-12 pt-12 border-t border-muted/20 flex flex-wrap items-center gap-2">
-              <span className="text-[10px] font-sans font-bold uppercase tracking-widest text-muted mr-1">{t('tags')}</span>
-              {post.tags.map((tag) => (
-                <Tag key={tag} tag={tag} variant="default" />
-              ))}
-            </div>
-          )}
+            <Backlinks backlinks={backlinks ?? []} />
 
-          <Backlinks backlinks={backlinks ?? []} />
-
-          <ShareBar
-            url={postUrl}
-            title={post.title}
-            className={showSidebar ? 'mt-8 lg:hidden' : 'mt-8'}
-          />
+            <ShareBar
+              url={postUrl}
+              title={post.title}
+              className={showSidebar ? 'mt-8 lg:hidden' : 'mt-8'}
+            />
 
-          {resolveCommentable(post.commentable, commentCategory) && (
-            <Comments slug={commentSlug} postUrl={postUrl} />
-          )}
+            {resolveCommentable(post.commentable, commentCategory) && (
+              <Comments slug={commentSlug} postUrl={postUrl} />
+            )}
 
-          {post.externalLinks && post.externalLinks.length > 0 && (
-            <ExternalLinks links={post.externalLinks} />
-          )}
+            {post.externalLinks && post.externalLinks.length > 0 && (
+              <ExternalLinks links={post.externalLinks} />
+            )}
 
-          <Suspense fallback={null}>
-            <PostNavigation prev={prevPost ?? null} next={nextPost ?? null} currentSlug={post.slug} collectionContexts={collectionContexts} />
-          </Suspense>
+            <Suspense fallback={null}>
+              <PostNavigation prev={prevPost ?? null} next={nextPost ?? null} currentSlug={post.slug} collectionContexts={collectionContexts} />
+            </Suspense>
 
-          <RelatedPosts posts={relatedPosts || []} />
-        </article>
+            <RelatedPosts posts={relatedPosts || []} />
+          </article>
+        </div>
       </div>
-    </div>
+    </PostReadingShell>
   );
 }

package/src/lib/immersive-reading-prefs.ts

@@ -0,0 +1,104 @@
+// Storage layer for the immersive reader's persisted preferences. Lives here
+// (not inside ImmersiveReadingProvider) so the defensive-parsing and write-
+// silencing logic is unit-testable without rendering React or mocking
+// `window.localStorage` globally — tests pass an in-memory storage object via
+// the optional `storage` parameter.
+//
+// Public contract: STORAGE_KEY is the user-visible localStorage key. Renaming
+// it invalidates every existing reader's prefs — don't.
+
+import type {
+  ReadingColumnWidth,
+  ReadingFontSize,
+  ReadingTheme,
+} from '@/components/ImmersiveReadingProvider';
+
+export const STORAGE_KEY = 'amytis-reader-prefs';
+
+const FONT_SIZE_VALUES: readonly ReadingFontSize[] = ['s', 'm', 'l', 'xl'];
+const THEME_VALUES: readonly ReadingTheme[] = ['auto', 'light', 'sepia', 'dark'];
+const COLUMN_WIDTH_VALUES: readonly ReadingColumnWidth[] = ['narrow', 'medium', 'wide', 'full'];
+
+export interface StoredPrefs {
+  fontSize: ReadingFontSize;
+  readingTheme: ReadingTheme;
+  columnWidth: ReadingColumnWidth;
+  sidebarOpen: boolean;
+}
+
+export const DEFAULT_PREFS: StoredPrefs = {
+  fontSize: 'm',
+  readingTheme: 'auto',
+  columnWidth: 'wide',
+  sidebarOpen: true,
+};
+
+/** Resolve the default storage lazily — `globalThis.localStorage` is undefined
+ * during SSR and accessing it at module top-level would crash imports. The
+ * try/catch is also load-bearing: in some privacy-restricted browser modes
+ * (Safari "block all cookies", Firefox with site data disabled) the
+ * `localStorage` getter itself throws a SecurityError instead of returning
+ * the object — without the catch, that would escape into readStoredPrefs /
+ * writeStoredPrefs and crash the reader. */
+function defaultReadStorage(): Pick<Storage, 'getItem'> | null {
+  if (typeof globalThis === 'undefined') return null;
+  try {
+    const ls = (globalThis as { localStorage?: Storage }).localStorage;
+    return ls ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultWriteStorage(): Pick<Storage, 'setItem'> | null {
+  if (typeof globalThis === 'undefined') return null;
+  try {
+    const ls = (globalThis as { localStorage?: Storage }).localStorage;
+    return ls ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read + validate prefs from storage. Per-key defensive: if any key is
+ * stale / unknown / wrong-typed (schema drift, manual edits), fall back to
+ * its default rather than discarding the whole blob. */
+export function readStoredPrefs(storage?: Pick<Storage, 'getItem'>): StoredPrefs {
+  const ls = storage ?? defaultReadStorage();
+  if (!ls) return DEFAULT_PREFS;
+  try {
+    const raw = ls.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULT_PREFS;
+    const parsed: unknown = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return DEFAULT_PREFS;
+    const obj = parsed as Record<string, unknown>;
+    return {
+      fontSize: (FONT_SIZE_VALUES as readonly string[]).includes(obj.fontSize as string)
+        ? (obj.fontSize as ReadingFontSize)
+        : DEFAULT_PREFS.fontSize,
+      readingTheme: (THEME_VALUES as readonly string[]).includes(obj.readingTheme as string)
+        ? (obj.readingTheme as ReadingTheme)
+        : DEFAULT_PREFS.readingTheme,
+      columnWidth: (COLUMN_WIDTH_VALUES as readonly string[]).includes(obj.columnWidth as string)
+        ? (obj.columnWidth as ReadingColumnWidth)
+        : DEFAULT_PREFS.columnWidth,
+      sidebarOpen:
+        typeof obj.sidebarOpen === 'boolean' ? obj.sidebarOpen : DEFAULT_PREFS.sidebarOpen,
+    };
+  } catch {
+    return DEFAULT_PREFS;
+  }
+}
+
+export function writeStoredPrefs(
+  prefs: StoredPrefs,
+  storage?: Pick<Storage, 'setItem'>,
+): void {
+  const ls = storage ?? defaultWriteStorage();
+  if (!ls) return;
+  try {
+    ls.setItem(STORAGE_KEY, JSON.stringify(prefs));
+  } catch {
+    /* private browsing / quota exceeded — ignore */
+  }
+}

package/src/lib/markdown.ts

@@ -5,6 +5,7 @@ import { siteConfig } from '../../site.config';
 import GithubSlugger from 'github-slugger';
 import { z } from 'zod';
 import { getPostUrl } from './urls';
+import { byDateAsc, byDateDesc } from './sort';
 import { parseRstDocument, RstParseError } from './rst';
 import { renderRstFile, renderRstFilesBatch, type RenderedRstDocument } from './rst-renderer';
 
@@ -970,7 +971,7 @@ export function getAllPosts(): PostData[] {
       }
       return true;
     })
-    .sort((a, b) => (a.date < b.date ? 1 : -1));
+    .sort(byDateDesc);
   postsCache.set(cacheKey, result);
   return result;
 }
@@ -1249,9 +1250,9 @@ export function getSeriesPosts(seriesName: string): PostData[] {
       // Default Sort: date-desc (Newest first)
       const sortOrder = seriesData?.sort || 'date-desc';
       if (sortOrder === 'date-asc') {
-          posts.sort((a, b) => (a.date > b.date ? 1 : -1));
+          posts.sort(byDateAsc);
       } else {
-          posts.sort((a, b) => (a.date < b.date ? 1 : -1));
+          posts.sort(byDateDesc);
       }
   }
   
@@ -1292,7 +1293,7 @@ export function getAllSeries(): Record<string, PostData[]> {
       return; // Skip draft series in production
     }
     series[slug] = seriesData?.type === 'collection'
-      ? getCollectionPosts(slug).slice().sort((a, b) => (a.date < b.date ? 1 : -1))
+      ? getCollectionPosts(slug).slice().sort(byDateDesc)
       : getSeriesPosts(slug);
   });
 
@@ -1645,9 +1646,11 @@ export function flattenBookChapters(toc: BookTocItem[]): BookChapterEntry[] {
 
 /**
  * Resolves a chapter id (possibly nested with `/`) to a markdown file on disk.
- * Returns `{ path, isFolder }` if a file exists in one of the four supported forms,
- * or `null` if the id has no match. Guards against `..`-style path escapes — any
- * id that resolves outside `bookDir` returns null.
+ * Returns `{ path, isFolder }` if a file exists in one of the six supported
+ * forms (`<id>.mdx`, `<id>.md`, `<id>/index.mdx`, `<id>/index.md`,
+ * `<id>/README.mdx`, `<id>/README.md`), or `null` if the id has no match.
+ * Guards against `..`-style path escapes — any id that resolves outside
+ * `bookDir` returns null.
  */
 function resolveChapterFilePath(
   bookDir: string,
@@ -1665,10 +1668,14 @@ function resolveChapterFilePath(
   const chMd = `${candidate}.md`;
   const chFolderMdx = path.join(candidate, 'index.mdx');
   const chFolderMd = path.join(candidate, 'index.md');
+  const chFolderReadmeMdx = path.join(candidate, 'README.mdx');
+  const chFolderReadmeMd = path.join(candidate, 'README.md');
   if (fs.existsSync(chMdx)) return { path: chMdx, isFolder: false };
   if (fs.existsSync(chMd)) return { path: chMd, isFolder: false };
   if (fs.existsSync(chFolderMdx)) return { path: chFolderMdx, isFolder: true };
   if (fs.existsSync(chFolderMd)) return { path: chFolderMd, isFolder: true };
+  if (fs.existsSync(chFolderReadmeMdx)) return { path: chFolderReadmeMdx, isFolder: true };
+  if (fs.existsSync(chFolderReadmeMd)) return { path: chFolderReadmeMd, isFolder: true };
   return null;
 }
 
@@ -1707,7 +1714,7 @@ export function getBookData(slug: string): BookData | null {
     throw new Error(
       `[amytis] Book "${slug}" references chapter${missing.length === 1 ? '' : 's'} ` +
       `with no matching file on disk: ${missing.map(id => `"${id}"`).join(', ')}. ` +
-      `Expected one of <bookDir>/<id>.{md,mdx} or <bookDir>/<id>/index.{md,mdx}.`
+      `Expected one of <bookDir>/<id>.{md,mdx}, <bookDir>/<id>/index.{md,mdx}, or <bookDir>/<id>/README.{md,mdx}.`
     );
   }
 
@@ -1821,7 +1828,7 @@ export function getAllBooks(): BookData[] {
     books.push(book);
   }
 
-  return books.sort((a, b) => (a.date < b.date ? 1 : -1));
+  return books.sort(byDateDesc);
 }
 
 export function getFeaturedBooks(): BookData[] {
@@ -1940,7 +1947,7 @@ export function getAllFlows(): FlowData[] {
       }
       return true;
     })
-    .sort((a, b) => (a.date < b.date ? 1 : -1));
+    .sort(byDateDesc);
 }
 
 export function getFlowBySlug(slug: string): FlowData | null {
@@ -2091,7 +2098,7 @@ export function getAllNotes(): NoteData[] {
 
   _allNotes = notes
     .filter(note => process.env.NODE_ENV !== 'production' || !note.draft)
-    .sort((a, b) => (a.date < b.date ? 1 : -1));
+    .sort(byDateDesc);
 
   return _allNotes;
 }