@hutusi/amytis 1.15.0 → 1.17.0

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,
       }))
     : [];
 
@@ -109,7 +112,7 @@ export default function Home() {
         excerpt: p.excerpt,
         date: p.date,
         category: p.category,
-        readingTime: p.readingTime,
+        readingMinutes: p.readingMinutes,
         coverImage: p.coverImage,
         series: p.series,
         pinned: p.pinned,
@@ -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/app/sitemap.ts

@@ -1,7 +1,7 @@
 import { MetadataRoute } from 'next';
 import { getAllPosts, getAllPages, getAllBooks, getAllFlows } from '@/lib/markdown';
 import { siteConfig } from '../../site.config';
-import { getPostUrl } from '@/lib/urls';
+import { getPostUrl, getBookUrl, getBookChapterUrl } from '@/lib/urls';
 
 export const dynamic = 'force-static';
 
@@ -29,13 +29,13 @@ export default function sitemap(): MetadataRoute.Sitemap {
 
   const bookUrls = books.flatMap((book) => [
     {
-      url: `${baseUrl}/books/${book.slug}`,
+      url: `${baseUrl}${getBookUrl(book.slug)}`,
       lastModified: book.date,
       changeFrequency: 'monthly' as const,
       priority: 0.8,
     },
     ...book.chapters.map((ch) => ({
-      url: `${baseUrl}/books/${book.slug}/${ch.id}`,
+      url: `${baseUrl}${getBookChapterUrl(book.slug, ch.id)}`,
       lastModified: book.date,
       changeFrequency: 'monthly' as const,
       priority: 0.7,

package/src/components/ArticleCopyCleaner.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { useEffect, useRef, type ReactNode } from 'react';
+
+const KEEP_BG_SELECTOR = 'pre, code, blockquote, .admonition, [class*="admonition"]';
+const STRIP_BG_SELECTOR = 'p, h1, h2, h3, h4, h5, h6, ul, ol, li, div, span, td, th, tr, article, section';
+
+function isMeaningfulBg(value: string): boolean {
+  if (!value) return false;
+  const v = value.trim().toLowerCase();
+  if (v === 'transparent' || v === 'rgba(0, 0, 0, 0)' || v === 'rgb(0, 0, 0, 0)') return false;
+  return true;
+}
+
+export default function ArticleCopyCleaner({ children }: { children: ReactNode }) {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+
+    const handleCopy = (event: ClipboardEvent) => {
+      const selection = window.getSelection();
+      if (!selection || selection.isCollapsed || selection.rangeCount === 0) return;
+
+      const range = selection.getRangeAt(0);
+      const anchor = range.commonAncestorContainer;
+      if (!(anchor instanceof Node) || !root.contains(anchor)) return;
+
+      const sandbox = document.createElement('div');
+      sandbox.setAttribute('aria-hidden', 'true');
+      sandbox.style.cssText = 'position:fixed;left:-99999px;top:0;visibility:hidden;pointer-events:none;';
+      sandbox.appendChild(range.cloneContents());
+      root.appendChild(sandbox);
+
+      try {
+        sandbox.querySelectorAll<HTMLElement>(KEEP_BG_SELECTOR).forEach((el) => {
+          const bg = getComputedStyle(el).backgroundColor;
+          if (isMeaningfulBg(bg)) el.style.backgroundColor = bg;
+        });
+
+        sandbox.querySelectorAll<HTMLElement>(STRIP_BG_SELECTOR).forEach((el) => {
+          if (el.matches(KEEP_BG_SELECTOR)) return;
+          el.style.removeProperty('background-color');
+          el.style.removeProperty('background');
+        });
+
+        const clipboard = event.clipboardData;
+        if (!clipboard) return;
+
+        clipboard.setData('text/html', sandbox.innerHTML);
+        clipboard.setData('text/plain', selection.toString());
+        event.preventDefault();
+      } finally {
+        sandbox.remove();
+      }
+    };
+
+    root.addEventListener('copy', handleCopy);
+    return () => root.removeEventListener('copy', handleCopy);
+  }, []);
+
+  return <div ref={rootRef}>{children}</div>;
+}

package/src/components/BookMobileNav.tsx

@@ -2,7 +2,7 @@
 
 import { useState } from 'react';
 import Link from 'next/link';
-import { BookTocItem, BookChapterEntry } from '@/lib/markdown';
+import { BookTocItem, BookTocSection, BookChapterRef, BookChapterEntry } from '@/lib/markdown';
 import { useLanguage } from './LanguageProvider';
 import PrevNextNav from './PrevNextNav';
 import { getBookChapterUrl } from '@/lib/urls';
@@ -23,6 +23,42 @@ export default function BookMobileNav({ bookSlug, bookTitle, toc, chapters, curr
   const prevChapter = currentIndex > 0 ? chapters[currentIndex - 1] : null;
   const nextChapter = currentIndex < chapters.length - 1 ? chapters[currentIndex + 1] : null;
 
+  const renderChapterRow = (ch: BookChapterRef, key: string) => {
+    const isCurrent = ch.id === currentChapter;
+    const chIdx = chapters.findIndex(c => c.id === ch.id);
+    const isPast = chIdx >= 0 && chIdx < currentIndex;
+    return isCurrent ? (
+      <div key={key} className="flex items-center gap-3 py-1.5 px-2 rounded-lg bg-accent/5">
+        <span className="text-sm font-semibold text-accent truncate">{ch.title}</span>
+      </div>
+    ) : (
+      <Link
+        key={key}
+        href={getBookChapterUrl(bookSlug, ch.id)}
+        className={`block py-1.5 px-2 rounded-lg text-sm no-underline hover:bg-muted/5 transition-colors ${
+          isPast ? 'text-foreground/70 hover:text-foreground' : 'text-muted hover:text-foreground'
+        }`}
+      >
+        {ch.title}
+      </Link>
+    );
+  };
+
+  const renderSection = (section: BookTocSection, key: string) => (
+    <div key={key}>
+      <div className="text-[10px] font-sans font-bold uppercase tracking-wider text-muted px-2 py-1.5">
+        {section.section}
+      </div>
+      <div className="space-y-1 pl-2">
+        {section.items.map((child, idx) =>
+          'section' in child
+            ? renderSection(child, `${key}-${idx}`)
+            : renderChapterRow(child, `${key}-${child.id}`)
+        )}
+      </div>
+    </div>
+  );
+
   return (
     <div className="lg:hidden p-5 bg-muted/5 rounded-xl border border-muted/20">
       {/* Header */}
@@ -85,58 +121,16 @@ export default function BookMobileNav({ bookSlug, bookTitle, toc, chapters, curr
                   <div className="text-[10px] font-sans font-bold uppercase tracking-wider text-muted px-2 py-1.5">
                     {item.part}
                   </div>
-                  <ol className="space-y-1">
-                    {item.chapters.map(ch => {
-                      const isCurrent = ch.id === currentChapter;
-                      const chIdx = chapters.findIndex(c => c.id === ch.id);
-                      const isPast = chIdx < currentIndex;
-
-                      return (
-                        <li key={ch.id}>
-                          {isCurrent ? (
-                            <div className="flex items-center gap-3 py-1.5 px-2 rounded-lg bg-accent/5">
-                              <span className="text-sm font-semibold text-accent truncate">{ch.title}</span>
-                            </div>
-                          ) : (
-                            <Link
-                              href={getBookChapterUrl(bookSlug, ch.id)}
-                              className={`block py-1.5 px-2 rounded-lg text-sm no-underline hover:bg-muted/5 transition-colors ${
-                                isPast ? 'text-foreground/70 hover:text-foreground' : 'text-muted hover:text-foreground'
-                              }`}
-                            >
-                              {ch.title}
-                            </Link>
-                          )}
-                        </li>
-                      );
-                    })}
-                  </ol>
-                </div>
-              );
-            } else {
-              const isCurrent = item.id === currentChapter;
-              const chIdx = chapters.findIndex(c => c.id === item.id);
-              const isPast = chIdx < currentIndex;
-
-              return (
-                <div key={item.id}>
-                  {isCurrent ? (
-                    <div className="flex items-center gap-3 py-1.5 px-2 rounded-lg bg-accent/5">
-                      <span className="text-sm font-semibold text-accent truncate">{item.title}</span>
-                    </div>
-                  ) : (
-                    <Link
-                      href={`/books/${bookSlug}/${item.id}`}
-                      className={`block py-1.5 px-2 rounded-lg text-sm no-underline hover:bg-muted/5 transition-colors ${
-                        isPast ? 'text-foreground/70 hover:text-foreground' : 'text-muted hover:text-foreground'
-                      }`}
-                    >
-                      {item.title}
-                    </Link>
-                  )}
+                  <div className="space-y-1">
+                    {item.chapters.map(ch => renderChapterRow(ch, `part-${tocIdx}-${ch.id}`))}
+                  </div>
                 </div>
               );
             }
+            if ('section' in item) {
+              return renderSection(item, `section-${tocIdx}`);
+            }
+            return renderChapterRow(item, `chapter-${item.id}`);
           })}
         </div>
       )}

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/CodeBlock.test.tsx

@@ -2,18 +2,103 @@ import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
 import CodeBlock from "./CodeBlock";
 
+async function renderCodeBlock(element: Awaited<ReturnType<typeof CodeBlock>>): Promise<string> {
+  return renderToStaticMarkup(element);
+}
+
 describe("CodeBlock", () => {
-  test("keeps code scrolling inside its own container", () => {
-    const html = renderToStaticMarkup(
-      <CodeBlock language="typescript">
-        {"const veryLongLine = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';"}
-      </CodeBlock>
-    );
+  test("keeps code scrolling inside its own container", async () => {
+    const element = await CodeBlock({
+      language: "typescript",
+      children: "const veryLongLine = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';",
+    });
+    const html = await renderCodeBlock(element);
 
     expect(html).toContain("relative my-6 w-full min-w-0 max-w-full");
     expect(html).toContain("overflow-x-auto");
     expect(html).toContain("overflow-y-hidden");
-    expect(html).toContain("max-width:100%");
-    expect(html).toContain("box-sizing:border-box");
+    expect(html).toContain("cb-root");
+    expect(html).toContain('class="shiki');
+  });
+
+  test("renders title bar when title prop is set", async () => {
+    const element = await CodeBlock({
+      language: "ts",
+      title: "src/app.ts",
+      children: "export const x = 1;",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).toContain("cb-title");
+    expect(html).toContain("src/app.ts");
+  });
+
+  test("flags <pre> with data-line-numbers when showLineNumbers is true", async () => {
+    const element = await CodeBlock({
+      language: "js",
+      showLineNumbers: true,
+      children: "const x = 1;\nconst y = 2;",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).toContain('data-line-numbers="true"');
+  });
+
+  test("marks highlighted lines from highlightLines prop", async () => {
+    const element = await CodeBlock({
+      language: "ts",
+      highlightLines: [2, 4],
+      children: "const a = 1;\nconst b = 2;\nconst c = 3;\nconst d = 4;",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).toContain('data-highlighted-line="2"');
+    expect(html).toContain('data-highlighted-line="4"');
+    expect(html).not.toContain('data-highlighted-line="1"');
+    expect(html).not.toContain('data-highlighted-line="3"');
+  });
+
+  test("applies diff add/remove classes for +/- lines in diff fences", async () => {
+    const element = await CodeBlock({
+      language: "diff",
+      children: "-removed\n+added\n unchanged",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).toContain("diff add");
+    expect(html).toContain("diff remove");
+  });
+
+  test("renders unknown languages as plaintext + emits a warn (warn-and-degrade)", async () => {
+    // Production deploys can't fail on a single unknown fence — render as
+    // plaintext and emit a build-time warn instead. CLAUDE.md's strict-build
+    // principle still applies for frontmatter/slugs/redirects, but not here.
+    const element = await CodeBlock({ language: "totally-made-up", children: "x" });
+    const html = await renderCodeBlock(element);
+    expect(html).toContain('class="shiki');
+    expect(html).toContain("totally-made-up");
+  });
+
+  test("renders plaintext when explicitly requested via `plaintext`/`text` alias", async () => {
+    const element = await CodeBlock({
+      language: "plaintext",
+      children: "no highlighting wanted here",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).toContain('class="shiki');
+    expect(html).toContain("no highlighting wanted here");
+  });
+
+  test("emits no client highlighter script tags", async () => {
+    const element = await CodeBlock({
+      language: "javascript",
+      children: "const x = 1;",
+    });
+    const html = await renderCodeBlock(element);
+
+    expect(html).not.toContain("<script");
+    expect(html).not.toContain("react-syntax-highlighter");
+    expect(html).not.toContain("token keyword");
   });
 });