@hutusi/amytis 1.15.0 → 1.17.0

package/site.config.example.ts

@@ -140,11 +140,11 @@ export const siteConfig = {
   homepage: {
     sections: [
       { id: 'hero',            enabled: true, weight: 1 },
-      { id: 'featured-posts',  enabled: true, weight: 2, maxItems: 4 },
+      { id: 'featured-posts',  enabled: true, weight: 2, maxItems: 4, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
       { id: 'latest-posts',    enabled: true, weight: 3, maxItems: 3 },
       { id: 'recent-flows',    enabled: false, weight: 4, maxItems: 8 },
-      { id: 'featured-series', enabled: true, weight: 5, maxItems: 6 },
-      { id: 'featured-books',  enabled: false, weight: 6, maxItems: 4 },
+      { id: 'featured-series', enabled: true, weight: 5, maxItems: 6, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
+      { id: 'featured-books',  enabled: false, weight: 6, maxItems: 4, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
     ],
   },
 

package/site.config.ts

@@ -139,11 +139,11 @@ export const siteConfig = {
   homepage: {
     sections: [
       { id: 'hero',            enabled: true, weight: 1 },
-      { id: 'featured-posts',  enabled: true, weight: 2, maxItems: 4 },
+      { id: 'featured-posts',  enabled: true, weight: 2, maxItems: 4, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
       { id: 'latest-posts',    enabled: true, weight: 3, maxItems: 4 },
       { id: 'recent-flows',    enabled: true, weight: 4, maxItems: 7 },
-      { id: 'featured-series', enabled: true, weight: 5, maxItems: 6 },
-      { id: 'featured-books',  enabled: true, weight: 6, maxItems: 4 },
+      { id: 'featured-series', enabled: true, weight: 5, maxItems: 6, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
+      { id: 'featured-books',  enabled: true, weight: 6, maxItems: 4, order: 'shuffle' as 'shuffle' | 'date-desc' | 'date-asc' },
     ],
   },
 

package/src/app/[slug]/layout.tsx

@@ -0,0 +1,30 @@
+import { Suspense, type ReactNode } from 'react';
+import { ImmersiveReadingProvider } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReadingFlagHandler from '@/components/ImmersiveReadingFlagHandler';
+
+// Mounts the immersive-reading state above the series-prefixed post route
+// (`/<series-slug>/<post>` when series.autoPaths is enabled, which is the
+// default). This is what lets immersive mode persist across client-side
+// navigation between sibling posts in the same series — without it, the
+// provider would remount on every post navigation and reader state would
+// reset.
+//
+// Note this layout wraps ALL single-segment routes under `/`, not just series
+// posts (also redirectFrom aliases, custom-path posts, etc.). The provider
+// only activates when the toggle is clicked, and the toggle is gated on
+// `post.series`, so non-series routes pay only the mount cost.
+//
+// The flag handler reads `?immersive=1` from the URL (set by the CTA on the
+// series index page) and enters the reader. It's wrapped in <Suspense> on its
+// own so its `useSearchParams` bailout doesn't drag {children} out of static
+// prerender.
+export default function SlugLayout({ children }: { children: ReactNode }) {
+  return (
+    <ImmersiveReadingProvider>
+      <Suspense fallback={null}>
+        <ImmersiveReadingFlagHandler />
+      </Suspense>
+      {children}
+    </ImmersiveReadingProvider>
+  );
+}

package/src/app/books/[slug]/{[chapter] → [...chapter]}/page.tsx

@@ -6,11 +6,31 @@ import BookLayout from '@/layouts/BookLayout';
 import { resolveLocale } from '@/lib/i18n';
 import { buildBookChapterJsonLd, serializeJsonLd } from '@/lib/json-ld';
 import { getBookUrl, getBookChapterUrl } from '@/lib/urls';
+import { safeDecodeParam } from '@/lib/series-redirects';
+
+/**
+ * The chapter route is a catch-all (`[...chapter]`) so that nested chapter ids
+ * like `maths/linear/introduction` can be served at `/books/<slug>/maths/linear/introduction`
+ * — mapping VuePress-style nested folder paths to URLs 1:1. Single-segment legacy
+ * ids continue to work since catch-all matches one-or-more segments.
+ */
+
+function chapterIdFromParams(rawChapter: string | string[] | undefined): string {
+  if (!rawChapter) return '';
+  if (Array.isArray(rawChapter)) {
+    return rawChapter.map(safeDecodeParam).join('/');
+  }
+  return safeDecodeParam(rawChapter);
+}
+
+function chapterIdToParamSegments(chapterId: string): string[] {
+  return chapterId.split('/').filter(Boolean);
+}
 
 export async function generateStaticParams() {
   const books = getAllBooks();
-  if (books.length === 0) return [{ slug: '_', chapter: '_' }];
-  const params: { slug: string; chapter: string }[] = [];
+  if (books.length === 0) return [{ slug: '_', chapter: ['_'] }];
+  const params: { slug: string; chapter: string[] }[] = [];
 
   for (const book of books) {
     for (const ch of book.chapters) {
@@ -19,21 +39,23 @@ export async function generateStaticParams() {
       // frontmatter) would cause notFound() at render time, which in
       // output:export dev mode surfaces as a confusing "missing param" 500.
       if (getBookChapter(book.slug, ch.id) !== null) {
-        params.push({ slug: book.slug, chapter: ch.id });
+        params.push({ slug: book.slug, chapter: chapterIdToParamSegments(ch.id) });
       }
     }
   }
 
   // Ensure we never return an empty array with output: export
-  return params.length > 0 ? params : [{ slug: '_', chapter: '_' }];
+  return params.length > 0 ? params : [{ slug: '_', chapter: ['_'] }];
 }
 
 export const dynamicParams = false;
 
-export async function generateMetadata({ params }: { params: Promise<{ slug: string; chapter: string }> }): Promise<Metadata> {
+type ChapterPageParams = Promise<{ slug: string; chapter: string[] }>;
+
+export async function generateMetadata({ params }: { params: ChapterPageParams }): Promise<Metadata> {
   const { slug: rawSlug, chapter: rawChapter } = await params;
-  const slug = decodeURIComponent(rawSlug);
-  const chapterSlug = decodeURIComponent(rawChapter);
+  const slug = safeDecodeParam(rawSlug);
+  const chapterSlug = chapterIdFromParams(rawChapter);
 
   const book = getBookData(slug);
   const chapter = getBookChapter(slug, chapterSlug);
@@ -66,10 +88,10 @@ export async function generateMetadata({ params }: { params: Promise<{ slug: str
   };
 }
 
-export default async function BookChapterPage({ params }: { params: Promise<{ slug: string; chapter: string }> }) {
+export default async function BookChapterPage({ params }: { params: ChapterPageParams }) {
   const { slug: rawSlug, chapter: rawChapter } = await params;
-  const slug = decodeURIComponent(rawSlug);
-  const chapterSlug = decodeURIComponent(rawChapter);
+  const slug = safeDecodeParam(rawSlug);
+  const chapterSlug = chapterIdFromParams(rawChapter);
 
   const book = getBookData(slug);
   const chapter = getBookChapter(slug, chapterSlug);

package/src/app/books/[slug]/layout.tsx

@@ -0,0 +1,24 @@
+import { Suspense, type ReactNode } from 'react';
+import { ImmersiveReadingProvider } from '@/components/ImmersiveReadingProvider';
+import ImmersiveReadingFlagHandler from '@/components/ImmersiveReadingFlagHandler';
+
+// Mounts the immersive-reading state above the chapter route. This is what
+// lets immersive mode persist across client-side navigation between chapters
+// of the same book (state would otherwise reset on every chapter unmount).
+// State is in-memory only — a hard refresh or navigating to a different book
+// resets it.
+//
+// The flag handler reads `?immersive=1` from the URL (set by the CTA on the
+// book index page) and enters the reader. It's wrapped in <Suspense> on its
+// own so its `useSearchParams` bailout doesn't drag {children} (the chapter
+// page) out of static prerender.
+export default function BookSlugLayout({ children }: { children: ReactNode }) {
+  return (
+    <ImmersiveReadingProvider>
+      <Suspense fallback={null}>
+        <ImmersiveReadingFlagHandler />
+      </Suspense>
+      {children}
+    </ImmersiveReadingProvider>
+  );
+}

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

@@ -1,4 +1,4 @@
-import { getBookData, getAllBooks, getAuthorSlug } from '@/lib/markdown';
+import { getBookData, getAllBooks, getAuthorSlug, type BookTocSection, type BookChapterRef } from '@/lib/markdown';
 import { notFound } from 'next/navigation';
 import { Metadata } from 'next';
 import { siteConfig } from '../../../../site.config';
@@ -7,7 +7,52 @@ import MarkdownRenderer from '@/components/MarkdownRenderer';
 import Link from 'next/link';
 import { t, resolveLocale } from '@/lib/i18n';
 import { buildBookJsonLd, serializeJsonLd } from '@/lib/json-ld';
-import { getBookUrl } from '@/lib/urls';
+import { getBookUrl, getBookChapterUrl } from '@/lib/urls';
+import { safeDecodeParam } from '@/lib/series-redirects';
+
+// Visual depth limit for nested-section headings. After the first two levels
+// we keep nesting structurally but stop bumping the heading style so deeply
+// nested books don't degrade into tiny text.
+const MAX_HEADING_DEPTH = 2;
+
+function chapterRow(ref: BookChapterRef, slug: string, key: string) {
+  return (
+    <li key={key}>
+      <Link
+        href={getBookChapterUrl(slug, ref.id)}
+        className="group flex items-center gap-3 py-2 text-foreground/80 hover:text-accent no-underline transition-colors"
+      >
+        <svg className="w-4 h-4 text-muted group-hover:text-accent flex-shrink-0 transition-colors" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+        </svg>
+        <span className="text-base">{ref.title}</span>
+      </Link>
+    </li>
+  );
+}
+
+function renderTocSection(section: BookTocSection, slug: string, keyPrefix: string, depth: number): React.ReactNode {
+  const headingDepth = Math.min(depth, MAX_HEADING_DEPTH);
+  const headingClass =
+    headingDepth === 0
+      ? 'text-lg font-serif font-bold text-heading mb-3'
+      : headingDepth === 1
+      ? 'text-sm font-sans font-bold uppercase tracking-wider text-muted mb-3'
+      : 'text-xs font-sans font-semibold uppercase tracking-wider text-muted/80 mb-2';
+
+  return (
+    <div key={keyPrefix} className={depth === 0 ? '' : 'mt-3'}>
+      <h3 className={headingClass}>{section.section}</h3>
+      <ol className="space-y-2 pl-4 border-l-2 border-muted/10">
+        {section.items.map((child, idx) =>
+          'section' in child
+            ? <li key={`${keyPrefix}-${idx}`}>{renderTocSection(child, slug, `${keyPrefix}-${idx}`, depth + 1)}</li>
+            : chapterRow(child, slug, `${keyPrefix}-${child.id}`)
+        )}
+      </ol>
+    </div>
+  );
+}
 
 export async function generateStaticParams() {
   const books = getAllBooks();
@@ -19,7 +64,7 @@ export const dynamicParams = false;
 
 export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
   const { slug } = await params;
-  const book = getBookData(decodeURIComponent(slug));
+  const book = getBookData(safeDecodeParam(slug));
 
   if (!book) {
     return { title: 'Book Not Found' };
@@ -36,7 +81,7 @@ export async function generateMetadata({ params }: { params: Promise<{ slug: str
       title: book.title,
       description: book.excerpt,
       type: 'website',
-      url: `${siteConfig.baseUrl}/books/${slug}`,
+      url: `${siteConfig.baseUrl}${getBookUrl(book.slug)}`,
       siteName: resolveLocale(siteConfig.title),
       images: [{ url: ogImage, width: 1200, height: 630, alt: book.title }],
     },
@@ -51,7 +96,7 @@ export async function generateMetadata({ params }: { params: Promise<{ slug: str
 
 export default async function BookLandingPage({ params }: { params: Promise<{ slug: string }> }) {
   const { slug: rawSlug } = await params;
-  const slug = decodeURIComponent(rawSlug);
+  const slug = safeDecodeParam(rawSlug);
   const book = getBookData(slug);
 
   if (!book || (process.env.NODE_ENV === 'production' && book.draft)) {
@@ -114,11 +159,11 @@ export default async function BookLandingPage({ params }: { params: Promise<{ sl
             </p>
           )}
 
-          {/* Start Reading CTA */}
+          {/* Start Reading CTAs */}
           {firstChapter && (
-            <div className="mt-8">
+            <div className="mt-8 flex flex-wrap items-center justify-center gap-3">
               <Link
-                href={`/books/${book.slug}/${firstChapter.id}`}
+                href={getBookChapterUrl(book.slug, firstChapter.id)}
                 className="inline-flex items-center gap-2 px-6 py-3 bg-accent text-white rounded-xl font-sans font-medium text-sm hover:bg-accent/90 no-underline transition-colors shadow-lg shadow-accent/20"
               >
                 {t('start_reading')}
@@ -126,6 +171,22 @@ export default async function BookLandingPage({ params }: { params: Promise<{ sl
                   <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
                 </svg>
               </Link>
+              {/* Secondary CTA — opens the first chapter 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={`${getBookChapterUrl(book.slug, firstChapter.id)}?immersive=1`}
+                className="inline-flex items-center gap-2 px-5 py-3 border border-muted/30 text-foreground/80 hover:text-accent hover:border-accent/50 rounded-xl font-sans font-medium text-sm no-underline transition-colors"
+              >
+                <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+                  <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>
           )}
         </div>
@@ -143,36 +204,26 @@ export default async function BookLandingPage({ params }: { params: Promise<{ sl
                     {item.part}
                   </h3>
                   <ol className="space-y-2 pl-4 border-l-2 border-muted/10">
-                    {item.chapters.map(ch => (
-                      <li key={ch.id}>
-                        <Link
-                          href={`/books/${book.slug}/${ch.id}`}
-                          className="group flex items-center gap-3 py-2 text-foreground/80 hover:text-accent no-underline transition-colors"
-                        >
-                          <svg className="w-4 h-4 text-muted group-hover:text-accent flex-shrink-0 transition-colors" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
-                          </svg>
-                          <span className="text-base">{ch.title}</span>
-                        </Link>
-                      </li>
-                    ))}
+                    {item.chapters.map(ch => chapterRow(ch, book.slug, ch.id))}
                   </ol>
                 </div>
               );
-            } else {
-              return (
-                <Link
-                  key={item.id}
-                  href={`/books/${book.slug}/${item.id}`}
-                  className="group flex items-center gap-3 py-2 text-foreground/80 hover:text-accent no-underline transition-colors"
-                >
-                  <svg className="w-4 h-4 text-muted group-hover:text-accent flex-shrink-0 transition-colors" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
-                  </svg>
-                  <span className="text-base">{item.title}</span>
-                </Link>
-              );
             }
+            if ('section' in item) {
+              return renderTocSection(item, book.slug, `section-${idx}`, 0);
+            }
+            return (
+              <Link
+                key={item.id}
+                href={getBookChapterUrl(book.slug, item.id)}
+                className="group flex items-center gap-3 py-2 text-foreground/80 hover:text-accent no-underline transition-colors"
+              >
+                <svg className="w-4 h-4 text-muted group-hover:text-accent flex-shrink-0 transition-colors" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+                </svg>
+                <span className="text-base">{item.title}</span>
+              </Link>
+            );
           })}
         </div>
       </section>