@hutusi/amytis 1.16.0 → 1.17.0

package/src/lib/scroll-utils.ts

@@ -1,11 +1,49 @@
 import type React from 'react';
 
-export function scrollToHeading(e: React.MouseEvent<HTMLAnchorElement>, id: string): void {
+const HEADING_OFFSET_PX = 80;
+
+/**
+ * Walks up from `el` looking for the closest ancestor that actually scrolls
+ * vertically. Returns `null` if the document/window is the scroll container —
+ * that's the normal-page case; immersive reading mode is the case where this
+ * returns the overlay's `<main>` element. The `scrollHeight > clientHeight`
+ * guard skips `overflow:auto` boxes that aren't currently overflowing (e.g.
+ * the overlay's sidebar `<aside>` or the article wrapper).
+ */
+export function getScrollableAncestor(el: HTMLElement): HTMLElement | null {
+  let cur: HTMLElement | null = el.parentElement;
+  while (cur && cur !== document.documentElement) {
+    const { overflowY } = window.getComputedStyle(cur);
+    if (
+      (overflowY === 'auto' || overflowY === 'scroll') &&
+      cur.scrollHeight > cur.clientHeight
+    ) {
+      return cur;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+export function scrollToHeading(
+  e: React.MouseEvent<HTMLAnchorElement>,
+  id: string,
+): void {
   const element = document.getElementById(id);
-  if (element) {
-    e.preventDefault();
-    const elementPosition = element.getBoundingClientRect().top + window.scrollY;
-    window.scrollTo({ top: elementPosition - 80, behavior: 'smooth' });
-    history.pushState(null, '', `#${id}`);
+  if (!element) return;
+  e.preventDefault();
+
+  const container = getScrollableAncestor(element);
+  if (container) {
+    const elRect = element.getBoundingClientRect();
+    const containerRect = container.getBoundingClientRect();
+    const top =
+      elRect.top - containerRect.top + container.scrollTop - HEADING_OFFSET_PX;
+    container.scrollTo({ top, behavior: 'smooth' });
+  } else {
+    const top =
+      element.getBoundingClientRect().top + window.scrollY - HEADING_OFFSET_PX;
+    window.scrollTo({ top, behavior: 'smooth' });
   }
+  history.pushState(null, '', `#${id}`);
 }

package/src/lib/shuffle.ts

@@ -10,6 +10,18 @@ export function shuffle<T>(array: T[]): T[] {
   return shuffled;
 }
 
+/**
+ * splitmix32 finalizer: decorrelates small consecutive integer seeds before
+ * they feed xorshift32. Without this, seeds like day-index 20608 / 20609 / 20610
+ * land on the same permutation for short arrays, making "daily rotation" invisible.
+ */
+function mixSeed(z: number): number {
+  z = (z + 0x9e3779b9) | 0;
+  z = Math.imul(z ^ (z >>> 16), 0x85ebca6b);
+  z = Math.imul(z ^ (z >>> 13), 0xc2b2ae35);
+  return (z ^ (z >>> 16)) >>> 0;
+}
+
 /**
  * Deterministic Fisher-Yates shuffle using a seeded xorshift32 PRNG.
  * Produces the same order for the same seed on both server and client,
@@ -17,7 +29,9 @@ export function shuffle<T>(array: T[]): T[] {
  */
 export function shuffleSeeded<T>(array: T[], seed: number): T[] {
   const shuffled = [...array];
-  let s = seed || 1;
+  // splitmix32 is a bijection on 32-bit ints, so exactly one input maps to 0.
+  // Guard against that one input since xorshift32 locks at the all-zero state.
+  let s = mixSeed(seed || 1) || 1;
   const rand = () => {
     s ^= s << 13;
     s ^= s >> 17;

package/src/lib/sort.ts

@@ -0,0 +1,15 @@
+/**
+ * Stable date comparators that return 0 on ties so equal-date items preserve
+ * insertion order under V8's TimSort. Centralised here so every "newest-first"
+ * or "oldest-first" sort in the codebase uses the same antisymmetric comparator.
+ */
+
+export function byDateDesc<T extends { date: string }>(a: T, b: T): number {
+  if (a.date === b.date) return 0;
+  return a.date < b.date ? 1 : -1;
+}
+
+export function byDateAsc<T extends { date: string }>(a: T, b: T): number {
+  if (a.date === b.date) return 0;
+  return a.date > b.date ? 1 : -1;
+}

package/src/lib/urls.ts

@@ -81,6 +81,11 @@ export function getBooksListUrl(): string {
   return '/books';
 }
 
+/** Returns the canonical URL path for a series landing page. */
+export function getSeriesUrl(slug: string): string {
+  return `/series/${slug}`;
+}
+
 /** Returns the canonical URL path for a book landing page. */
 export function getBookUrl(slug: string): string {
   return `/books/${slug}`;

package/tests/integration/book-index-cta.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import BookLandingPage from "@/app/books/[slug]/page";
+import { renderAsync } from "@/test-utils/render";
+import { getBookData } from "@/lib/markdown";
+import { t } from "@/lib/i18n";
+import { getBookChapterUrl } from "@/lib/urls";
+
+// Renders the actual book landing page server component for a real fixture
+// book under content/books/. The page is async (calls getBookData internally)
+// so we use the project's renderAsync helper — same pattern as
+// tests/integration/book-chapter-links.test.ts. Catches the regression
+// modes that pure-helper tests can't: someone removes either CTA from the
+// JSX, or changes the href format and drops ?immersive=1.
+
+const FIXTURE_BOOK_SLUG = "sample-book";
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Returns the inner HTML of the smallest <a> element on the page whose href
+// attribute equals the given value, or null if no such anchor exists. We
+// match the anchor body rather than just `href="..."` so the label-text
+// assertion is bound to the same element — otherwise an unrelated link with
+// the same href (e.g. a TOC chapter row pointing at the first chapter) would
+// satisfy a naïve `toContain('href="..."')` check and let an accidentally
+// deleted CTA pass.
+function findAnchorBodyByHref(html: string, href: string): string | null {
+  const re = new RegExp(`<a[^>]*\\bhref="${escapeRegex(href)}"[^>]*>([\\s\\S]*?)</a>`);
+  const m = html.match(re);
+  return m ? m[1] : null;
+}
+
+describe("Integration: book index Immersive reading CTA", () => {
+  test("renders an Immersive reading CTA linking to the first chapter with ?immersive=1", async () => {
+    const book = getBookData(FIXTURE_BOOK_SLUG);
+    if (!book || book.chapters.length === 0) {
+      throw new Error(
+        `Fixture book "${FIXTURE_BOOK_SLUG}" not found or has no chapters — this test depends on it`,
+      );
+    }
+    const firstChapter = book.chapters[0];
+    const expectedHref = `${getBookChapterUrl(book.slug, firstChapter.id)}?immersive=1`;
+
+    const html = await renderAsync(
+      BookLandingPage({ params: Promise.resolve({ slug: FIXTURE_BOOK_SLUG }) }),
+    );
+
+    const body = findAnchorBodyByHref(html, expectedHref);
+    expect(body).not.toBeNull();
+    // Label text is rendered inside the same anchor — guards against the
+    // anchor existing but having been repurposed to a different CTA.
+    expect(body).toContain(t("immersive_reading"));
+  });
+
+  test("primary 'Start reading' CTA still renders alongside the immersive CTA", async () => {
+    const book = getBookData(FIXTURE_BOOK_SLUG);
+    if (!book || book.chapters.length === 0) {
+      throw new Error(
+        `Fixture book "${FIXTURE_BOOK_SLUG}" not found or has no chapters`,
+      );
+    }
+    const firstChapter = book.chapters[0];
+    const primaryHref = getBookChapterUrl(book.slug, firstChapter.id);
+
+    const html = await renderAsync(
+      BookLandingPage({ params: Promise.resolve({ slug: FIXTURE_BOOK_SLUG }) }),
+    );
+
+    // Multiple links may share this href (TOC rows also point at the first
+    // chapter), so iterate over all matches and confirm at least one of them
+    // is the CTA — the one containing the start_reading label text.
+    const re = new RegExp(
+      `<a[^>]*\\bhref="${escapeRegex(primaryHref)}"[^>]*>([\\s\\S]*?)</a>`,
+      "g",
+    );
+    const label = t("start_reading");
+    let foundCta = false;
+    for (const match of html.matchAll(re)) {
+      if (match[1].includes(label)) {
+        foundCta = true;
+        break;
+      }
+    }
+    expect(foundCta).toBe(true);
+  });
+});

package/tests/integration/series-index-cta.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import SeriesPage from "@/app/series/[slug]/page";
+import { renderAsync } from "@/test-utils/render";
+import { getSeriesData, getSeriesPosts } from "@/lib/markdown";
+import { t } from "@/lib/i18n";
+import { getPostUrl } from "@/lib/urls";
+
+// Renders the actual series landing page server component for a real fixture
+// series under content/series/. Same pattern as book-index-cta.test.ts —
+// catches accidental removal of either CTA or a broken ?immersive=1 href
+// without needing component-rendering test infrastructure.
+
+const FIXTURE_SERIES_SLUG = "digital-garden";
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Returns the inner HTML of the smallest <a> element on the page whose href
+// attribute equals the given value, or null if no such anchor exists. We
+// match the anchor body rather than just `href="..."` so the label-text
+// assertion is bound to the same element — otherwise an unrelated link with
+// the same href (e.g. a post-row in the series list) would satisfy a naïve
+// `toContain('href="..."')` check and let an accidentally deleted CTA pass.
+function findAnchorBodyByHref(html: string, href: string): string | null {
+  const re = new RegExp(`<a[^>]*\\bhref="${escapeRegex(href)}"[^>]*>([\\s\\S]*?)</a>`);
+  const m = html.match(re);
+  return m ? m[1] : null;
+}
+
+// Picks the first installment respecting series sort order, mirroring the
+// inline logic in src/app/series/[slug]/page.tsx (the test would otherwise
+// have to assume a particular sort).
+function pickFirstPostHref(slug: string): string {
+  const posts = getSeriesPosts(slug);
+  if (posts.length === 0) {
+    throw new Error(`Fixture series "${slug}" has no posts`);
+  }
+  const data = getSeriesData(slug) as (Record<string, unknown> | null);
+  // Series sort lives on the index frontmatter — top-level on the resolved
+  // PostData blob, same access the page uses. Treated as unknown here to
+  // avoid leaning on internal PostData shape.
+  const sort = typeof data?.sort === 'string' ? data.sort : undefined;
+  const firstPost = sort === 'date-asc' || sort === 'manual' ? posts[0] : posts[posts.length - 1];
+  return getPostUrl(firstPost);
+}
+
+describe("Integration: series index Immersive reading CTA", () => {
+  test("renders an Immersive reading CTA linking to the first post with ?immersive=1", async () => {
+    const primaryHref = pickFirstPostHref(FIXTURE_SERIES_SLUG);
+    const expectedHref = `${primaryHref}?immersive=1`;
+
+    const html = await renderAsync(
+      SeriesPage({ params: Promise.resolve({ slug: FIXTURE_SERIES_SLUG }) }),
+    );
+
+    const body = findAnchorBodyByHref(html, expectedHref);
+    expect(body).not.toBeNull();
+    // Label text inside the same anchor — guards against the anchor existing
+    // but having been repurposed to a different CTA.
+    expect(body).toContain(t("immersive_reading"));
+  });
+
+  test("primary 'Start reading' CTA still renders alongside the immersive CTA", async () => {
+    const primaryHref = pickFirstPostHref(FIXTURE_SERIES_SLUG);
+
+    const html = await renderAsync(
+      SeriesPage({ params: Promise.resolve({ slug: FIXTURE_SERIES_SLUG }) }),
+    );
+
+    // Multiple links may share this href (the series posts list also points
+    // at the first post), so iterate over all matches and confirm at least
+    // one of them is the CTA — the one containing the start_reading label.
+    const re = new RegExp(
+      `<a[^>]*\\bhref="${escapeRegex(primaryHref)}"[^>]*>([\\s\\S]*?)</a>`,
+      "g",
+    );
+    const label = t("start_reading");
+    let foundCta = false;
+    for (const match of html.matchAll(re)) {
+      if (match[1].includes(label)) {
+        foundCta = true;
+        break;
+      }
+    }
+    expect(foundCta).toBe(true);
+  });
+});

package/tests/integration/sync-vuepress-book.test.ts

@@ -11,10 +11,10 @@ const FIXTURE_SOURCE = path.resolve("tests/fixtures/sync-vuepress-book/docs");
 // `--source` / `--dest` flags so the test exercises everything a real user does:
 // the package.json script wiring + the CLI argv parser, not just the inner sync
 // pipeline.
-function runSync(source: string, dest: string) {
+function runSync(source: string, dest: string, extraArgs: string[] = []) {
   return spawnSync(
     "bun",
-    ["run", "sync-vuepress-book", "--source", source, "--dest", dest],
+    ["run", "sync-vuepress-book", "--source", source, "--dest", dest, ...extraArgs],
     {
       encoding: "utf8",
       cwd: process.cwd(),
@@ -89,6 +89,35 @@ describe("Integration: sync-vuepress-book script", () => {
     expect(Array.isArray(refreshed.chapters)).toBe(true);
   });
 
+  test("re-sync only touches the chapters field — never re-applies first-sync defaults", () => {
+    // First run creates index.mdx with bootstrap defaults (title, date,
+    // draft, featured).
+    expect(runSync(FIXTURE_SOURCE, dest).status).toBe(0);
+
+    // Author strips the script's bootstrap defaults to validate that
+    // re-sync does not auto-fill them again. `featured` is explicitly
+    // removed; `date` is left as an empty string (which the old behavior
+    // would have stomped with today's date because `!data.date` is true
+    // for `""`).
+    const indexPath = path.join(dest, "index.mdx");
+    const parsed = matter(readFileSync(indexPath, "utf8")) as unknown as { data: Record<string, unknown>; content: string };
+    delete parsed.data.featured;
+    parsed.data.date = "";
+    parsed.data.draft = true;
+    writeFileSync(indexPath, matter.stringify(parsed.content, parsed.data));
+
+    // Re-run.
+    expect(runSync(FIXTURE_SOURCE, dest).status).toBe(0);
+    const refreshed = matter(readFileSync(indexPath, "utf8")) as unknown as { data: Record<string, unknown> };
+
+    // `chapters:` refreshed; everything else byte-equivalent to what the
+    // author wrote.
+    expect(Array.isArray(refreshed.data.chapters)).toBe(true);
+    expect(refreshed.data.featured).toBeUndefined();
+    expect(refreshed.data.date).toBe("");
+    expect(refreshed.data.draft).toBe(true);
+  });
+
   test("prunes dest files removed upstream (mirror semantics)", () => {
     // First sync — dest now has every fixture file.
     expect(runSync(FIXTURE_SOURCE, dest).status).toBe(0);
@@ -219,6 +248,180 @@ describe("Integration: sync-vuepress-book script", () => {
     }
   });
 
+  test("imports a VuePress 1.x sidebar (title/path/collapsable, bare-string children, README promotion, SUMMARY drop)", () => {
+    // VP1 uses a different vocabulary than VP2: `title` instead of `text`,
+    // `collapsable` instead of `collapsible`, plain string paths as children,
+    // and sections that carry both `path` (the section's README) and
+    // `children` (sub-chapters). This fixture exercises all four variants
+    // plus the GitBook-style SUMMARY.md drop.
+    const vp1 = mkdtempSync(path.join(tmpdir(), "sync-vp1-"));
+    try {
+      const docs = path.join(vp1, "docs");
+      const vp = path.join(docs, ".vuepress");
+      mkdirSync(vp, { recursive: true });
+      writeFileSync(
+        path.join(vp, "config.js"),
+        `module.exports = {
+          title: 'VP1 Fixture',
+          themeConfig: {
+            sidebar: [
+              { title: '目录', collapsable: false, path: '/SUMMARY.md' },
+              {
+                title: 'Preface',
+                collapsable: false,
+                children: [
+                  '/intro/about-me',
+                  '/intro/about-book',
+                ],
+              },
+              {
+                title: 'Architecture',
+                collapsable: false,
+                children: [
+                  {
+                    title: 'History',
+                    path: '/arch/history/',
+                    collapsable: false,
+                    children: [
+                      '/arch/history/monolithic',
+                      '/arch/history/microservices',
+                    ],
+                  },
+                  '/arch/standalone-note',
+                ],
+              },
+              {
+                title: 'Misc',
+                collapsable: false,
+                children: [
+                  '/CHANGELOG.md',
+                ],
+              },
+            ],
+          },
+        };
+        `,
+      );
+      // Source files matching every sidebar reference. Titles come from
+      // frontmatter or H1 — the importer should pick them up for bare-string
+      // children that have no inline title.
+      writeFileSync(path.join(docs, "SUMMARY.md"), "# Summary\n- placeholder\n");
+      mkdirSync(path.join(docs, "intro"), { recursive: true });
+      writeFileSync(path.join(docs, "intro", "about-me.md"), "---\ntitle: About the Author\n---\n# About\n");
+      writeFileSync(path.join(docs, "intro", "about-book.md"), "# About this Book\n\nBody.\n");
+      mkdirSync(path.join(docs, "arch", "history"), { recursive: true });
+      writeFileSync(path.join(docs, "arch", "history", "README.md"), "# History of Architecture\n");
+      writeFileSync(path.join(docs, "arch", "history", "monolithic.md"), "# Monolithic\n");
+      writeFileSync(path.join(docs, "arch", "history", "microservices.md"), "# Microservices\n");
+      writeFileSync(path.join(docs, "arch", "standalone-note.md"), "# Standalone Note\n");
+      writeFileSync(path.join(docs, "CHANGELOG.md"), "# Changelog\n");
+
+      const res = runSync(docs, dest);
+      expect(res.status).toBe(0);
+
+      const { data } = matter(readFileSync(path.join(dest, "index.mdx"), "utf8")) as unknown as { data: Record<string, unknown> };
+      const chapters = data.chapters as Array<Record<string, unknown>>;
+
+      // SUMMARY.md dropped — TOC starts with the Preface section.
+      expect(chapters[0]).toMatchObject({ section: "Preface", collapsible: false });
+
+      // Bare-string children get their titles from the source files
+      // (frontmatter wins over first H1).
+      const prefaceItems = chapters[0].items as Array<Record<string, unknown>>;
+      expect(prefaceItems).toEqual([
+        { title: "About the Author", id: "intro/about-me" },
+        { title: "About this Book", id: "intro/about-book" },
+      ]);
+
+      // Architecture > History promotes the section's README as the first
+      // chapter (id `arch/history`, title from the README's H1), then
+      // appends the bare-string children.
+      const arch = chapters[1] as Record<string, unknown>;
+      expect(arch.section).toBe("Architecture");
+      const archItems = arch.items as Array<Record<string, unknown>>;
+      const history = archItems[0] as Record<string, unknown>;
+      expect(history.section).toBe("History");
+      expect(history.items).toEqual([
+        { title: "History of Architecture", id: "arch/history" },
+        { title: "Monolithic", id: "arch/history/monolithic" },
+        { title: "Microservices", id: "arch/history/microservices" },
+      ]);
+      // Standalone bare-string sibling of the History section.
+      expect(archItems[1]).toMatchObject({ title: "Standalone Note", id: "arch/standalone-note" });
+
+      // `/CHANGELOG.md` keeps its `.md` extension stripped — id is `CHANGELOG`.
+      const misc = chapters[2] as Record<string, unknown>;
+      expect((misc.items as Array<{ id: string }>)[0].id).toBe("CHANGELOG");
+
+      // SUMMARY drop is reported in stdout (same channel as the existing
+      // `contents` drop).
+      expect(res.stdout).toMatch(/SUMMARY/i);
+
+      // No "unsupported sidebar entries" warning — every VP1 shape was
+      // recognized.
+      expect(res.stderr).not.toMatch(/Skipped unsupported sidebar entries/);
+    } finally {
+      rmSync(vp1, { recursive: true, force: true });
+    }
+  });
+
+  test("skips common build manifests by default, honors --skip and --no-skip-common", () => {
+    // Set up a minimal VuePress book where the source root has package.json
+    // (junk), package-lock.json (junk), a custom .bak (skipped via --skip),
+    // and a Real.md (always copied).
+    const junky = mkdtempSync(path.join(tmpdir(), "sync-junky-"));
+    try {
+      const docs = path.join(junky, "docs");
+      const vp = path.join(docs, ".vuepress");
+      mkdirSync(vp, { recursive: true });
+      writeFileSync(
+        path.join(vp, "config.js"),
+        `export default {
+          title: 'Junky Book',
+          theme: { sidebar: [{ text: 'Real', link: '/real' }] },
+        }
+        `,
+      );
+      writeFileSync(path.join(docs, "real.md"), "---\ntitle: Real\n---\n# Real\n");
+      writeFileSync(path.join(docs, "package.json"), '{"name":"junky"}');
+      writeFileSync(path.join(docs, "package-lock.json"), '{"lockfileVersion":3}');
+      writeFileSync(path.join(docs, "bun.lockb"), "binary-ish");
+      writeFileSync(path.join(docs, "draft.bak"), "wip");
+
+      // 1. Defaults: --skip-common is on, --skip empty. Lockfiles dropped,
+      //    bak file kept (it matches no rule).
+      let res = runSync(docs, dest);
+      expect(res.status).toBe(0);
+      expect(existsSync(path.join(dest, "real.md"))).toBe(true);
+      expect(existsSync(path.join(dest, "package.json"))).toBe(false);
+      expect(existsSync(path.join(dest, "package-lock.json"))).toBe(false);
+      expect(existsSync(path.join(dest, "bun.lockb"))).toBe(false);
+      expect(existsSync(path.join(dest, "draft.bak"))).toBe(true);
+      // Skip summary is printed so the user knows what got dropped.
+      expect(res.stdout).toMatch(/Skipped \d+ files? matching skip rules/);
+
+      // 2. --skip '*.bak' adds the bak pattern to the defaults.
+      rmSync(dest, { recursive: true, force: true });
+      mkdirSync(dest, { recursive: true });
+      res = runSync(docs, dest, ["--skip", "*.bak"]);
+      expect(res.status).toBe(0);
+      expect(existsSync(path.join(dest, "real.md"))).toBe(true);
+      expect(existsSync(path.join(dest, "package.json"))).toBe(false);
+      expect(existsSync(path.join(dest, "draft.bak"))).toBe(false);
+
+      // 3. --no-skip-common disables the default list; lockfiles come back.
+      rmSync(dest, { recursive: true, force: true });
+      mkdirSync(dest, { recursive: true });
+      res = runSync(docs, dest, ["--no-skip-common"]);
+      expect(res.status).toBe(0);
+      expect(existsSync(path.join(dest, "package.json"))).toBe(true);
+      expect(existsSync(path.join(dest, "package-lock.json"))).toBe(true);
+      expect(existsSync(path.join(dest, "bun.lockb"))).toBe(true);
+    } finally {
+      rmSync(junky, { recursive: true, force: true });
+    }
+  });
+
   test("exits with an error when a sidebar leaf points to a missing source file", () => {
     // Create a corrupt config with a broken link.
     const broken = mkdtempSync(path.join(tmpdir(), "sync-broken-"));

package/tests/unit/immersive-reading-prefs.test.ts

@@ -0,0 +1,144 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  DEFAULT_PREFS,
+  STORAGE_KEY,
+  readStoredPrefs,
+  writeStoredPrefs,
+  type StoredPrefs,
+} from '../../src/lib/immersive-reading-prefs';
+
+// Minimal in-memory mock matching the Storage interface subsets the helpers
+// accept. Per-test instance keeps state isolated and avoids touching
+// globalThis.localStorage. Optional setItem override lets us simulate
+// private-browsing / quota-exceeded throws.
+function makeMockStorage(
+  initial?: Record<string, string>,
+  opts: { setItemThrows?: boolean } = {},
+) {
+  const store: Record<string, string> = { ...(initial ?? {}) };
+  return {
+    getItem(key: string): string | null {
+      return Object.prototype.hasOwnProperty.call(store, key) ? store[key] : null;
+    },
+    setItem(key: string, value: string): void {
+      if (opts.setItemThrows) throw new Error('quota exceeded');
+      store[key] = value;
+    },
+    _store: store,
+  };
+}
+
+describe('readStoredPrefs', () => {
+  test('returns defaults when storage is empty', () => {
+    expect(readStoredPrefs(makeMockStorage())).toEqual(DEFAULT_PREFS);
+  });
+
+  test('returns defaults when no storage is available', () => {
+    // Passing a storage whose getItem always returns null mirrors the
+    // "globalThis.localStorage missing" path. Production callers can also
+    // pass undefined and rely on the lazy default — that path is exercised
+    // by the provider in the browser, not by unit tests.
+    const empty = { getItem: () => null };
+    expect(readStoredPrefs(empty)).toEqual(DEFAULT_PREFS);
+  });
+
+  test('returns defaults when stored JSON is invalid', () => {
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: 'not-json{' }))).toEqual(DEFAULT_PREFS);
+  });
+
+  test('returns defaults when stored value is not an object', () => {
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: '"a string"' }))).toEqual(DEFAULT_PREFS);
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: 'null' }))).toEqual(DEFAULT_PREFS);
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: '42' }))).toEqual(DEFAULT_PREFS);
+  });
+
+  test('returns defaults when storage entry is missing for the key', () => {
+    expect(readStoredPrefs(makeMockStorage({ 'unrelated-key': 'whatever' }))).toEqual(DEFAULT_PREFS);
+  });
+
+  test('round-trips a fully valid prefs blob', () => {
+    const blob: StoredPrefs = {
+      fontSize: 'xl',
+      readingTheme: 'sepia',
+      columnWidth: 'narrow',
+      sidebarOpen: false,
+    };
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: JSON.stringify(blob) }))).toEqual(blob);
+  });
+
+  // The schema-drift case the helpers exist for: one corrupt key must not
+  // discard the whole blob — other valid keys still apply, the bad one
+  // falls back to its default.
+  test('per-key fallback: bad fontSize, others survive', () => {
+    const stored = JSON.stringify({
+      fontSize: 'banana',
+      readingTheme: 'dark',
+      columnWidth: 'full',
+      sidebarOpen: false,
+    });
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: stored }))).toEqual({
+      fontSize: DEFAULT_PREFS.fontSize, // fell back
+      readingTheme: 'dark',
+      columnWidth: 'full',
+      sidebarOpen: false,
+    });
+  });
+
+  test('per-key fallback: bad readingTheme + columnWidth, others survive', () => {
+    const stored = JSON.stringify({
+      fontSize: 's',
+      readingTheme: 'neon',
+      columnWidth: 'ultra-wide',
+      sidebarOpen: true,
+    });
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: stored }))).toEqual({
+      fontSize: 's',
+      readingTheme: DEFAULT_PREFS.readingTheme,
+      columnWidth: DEFAULT_PREFS.columnWidth,
+      sidebarOpen: true,
+    });
+  });
+
+  test('sidebarOpen is strict-boolean — string "true" does not count', () => {
+    const stored = JSON.stringify({
+      fontSize: 'm',
+      readingTheme: 'auto',
+      columnWidth: 'wide',
+      sidebarOpen: 'true',
+    });
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: stored })).sidebarOpen).toBe(
+      DEFAULT_PREFS.sidebarOpen,
+    );
+  });
+
+  test('returns defaults when all keys are missing from a valid object', () => {
+    expect(readStoredPrefs(makeMockStorage({ [STORAGE_KEY]: '{}' }))).toEqual(DEFAULT_PREFS);
+  });
+});
+
+describe('writeStoredPrefs', () => {
+  test('writes the full blob under STORAGE_KEY as JSON', () => {
+    const storage = makeMockStorage();
+    const blob: StoredPrefs = {
+      fontSize: 'l',
+      readingTheme: 'dark',
+      columnWidth: 'medium',
+      sidebarOpen: false,
+    };
+    writeStoredPrefs(blob, storage);
+    expect(JSON.parse(storage._store[STORAGE_KEY])).toEqual(blob);
+  });
+
+  test('swallows throws (private browsing / quota exceeded)', () => {
+    const storage = makeMockStorage(undefined, { setItemThrows: true });
+    // Must not crash — the production caller relies on this silence so the
+    // reader still works in private browsing.
+    expect(() => writeStoredPrefs(DEFAULT_PREFS, storage)).not.toThrow();
+  });
+
+  test('does nothing when no storage is available', () => {
+    // Same as above but exercising the no-storage path. The "no storage"
+    // call site in production happens during SSR.
+    expect(() => writeStoredPrefs(DEFAULT_PREFS, undefined)).not.toThrow();
+  });
+});

package/vercel.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "buildCommand": "bun run build",
+  "installCommand": "bun install --frozen-lockfile",
+  "outputDirectory": "out"
+}