@hutusi/amytis 1.13.0 → 1.15.0

package/tests/integration/collections.test.ts

@@ -44,6 +44,21 @@ describe("Integration: Collections", () => {
     expect(slugs).toContain("understanding-react-hooks");
   });
 
+  test("getCollectionPosts resolves namespaced post entries properly", () => {
+    // The modern-web-dev collection uses the "posts/asynchronous-javascript" syntax.
+    // This test ensures that the namespaced resolution logic successfully found it.
+    const posts = getCollectionPosts("modern-web-dev");
+    const foundPost = posts.find(p => p.slug === "asynchronous-javascript");
+    expect(foundPost).toBeDefined();
+    // Because the namespace was "posts/", its series should be undefined
+    expect(foundPost!.series).toBeUndefined();
+
+    // Also verify series-based namespace
+    const seriesPost = posts.find(p => p.slug === "02-architecture");
+    expect(seriesPost).toBeDefined();
+    expect(seriesPost!.series).toBe("digital-garden");
+  });
+
   test("getCollectionPosts includes posts from referenced series", () => {
     const posts = getCollectionPosts("modern-web-dev");
     const slugs = posts.map((p) => p.slug);
@@ -108,8 +123,8 @@ describe("Integration: Collections", () => {
   test("getAllSeries includes collection with correct post count", () => {
     const all = getAllSeries();
     expect(all).toHaveProperty("modern-web-dev");
-    // modern-web-dev has 2 standalone posts + 2 from nextjs-deep-dive
-    expect(all["modern-web-dev"].length).toBe(4);
+    // modern-web-dev has 2 standalone posts + 4 from nextjs-deep-dive
+    expect(all["modern-web-dev"].length).toBe(6);
   });
 
   test("getAllSeries collection posts are sorted by date descending", () => {

package/tests/integration/feed-utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { getFeedItems } from "../../src/lib/feed-utils";
 import { getAllPosts, getAllFlows } from "../../src/lib/markdown";
+import { getPostUrl, getFlowUrl } from "../../src/lib/urls";
 import { siteConfig } from "../../site.config";
 
 describe("Integration: Feed Utils", () => {
@@ -44,6 +45,19 @@ describe("Integration: Feed Utils", () => {
     }
   });
 
+  test("feed items have valid dates", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems();
+      items.forEach((item) => {
+        expect(Number.isNaN(item.date.getTime())).toBe(false);
+      });
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
   test("maxItems = 0 returns all posts", () => {
     const originalMaxItems = siteConfig.feed.maxItems;
     const originalIncludeFlows = siteConfig.feed.includeFlows;
@@ -142,4 +156,55 @@ describe("Integration: Feed Utils", () => {
       }
     });
   });
+
+  test("feedType 'posts' returns only post items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('posts');
+      const allPosts = getAllPosts();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.length).toBe(allPosts.length);
+      expect(items.map((item) => item.url).sort()).toEqual(
+        allPosts.map((post) => `${baseUrl}${getPostUrl(post)}`).sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("feedType 'flows' returns only flow items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('flows');
+      const allFlows = getAllFlows();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.length).toBe(allFlows.length);
+      expect(items.map((item) => item.url).sort()).toEqual(
+        allFlows.map((flow) => `${baseUrl}${getFlowUrl(flow.slug)}`).sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("feedType 'all' returns both post and flow items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('all');
+      const allPosts = getAllPosts();
+      const allFlows = getAllFlows();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.map((item) => item.url).sort()).toEqual(
+        [
+          ...allPosts.map((post) => `${baseUrl}${getPostUrl(post)}`),
+          ...allFlows.map((flow) => `${baseUrl}${getFlowUrl(flow.slug)}`),
+        ].sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
 });

package/tests/integration/flow-title.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { getFlowBySlug, getAllFlows } from "../../src/lib/markdown";
+
+describe("Integration: Flow Title Resolution", () => {
+  test("frontmatter title takes priority over H1 and date", () => {
+    // content/flows/2026/03/05.md has `title: 'JSDoc type comments'` in frontmatter
+    const flow = getFlowBySlug("2026/03/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("JSDoc type comments");
+  });
+
+  test("H1 heading is extracted as title when no frontmatter title", () => {
+    // content/flows/2026/03/07.md has no frontmatter title but has `# Using Claude Code`
+    const flow = getFlowBySlug("2026/03/07");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("Using Claude Code");
+  });
+
+  test("date is used as fallback when no frontmatter title or H1", () => {
+    // content/flows/2026/02/05.md has no title and no H1
+    const flow = getFlowBySlug("2026/02/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("2026-02-05");
+  });
+
+  test("H1 heading is stripped from content body", () => {
+    const flow = getFlowBySlug("2026/03/07");
+    expect(flow).not.toBeNull();
+    // The H1 should be extracted as title but removed from content
+    expect(flow!.content).not.toMatch(/^#\s+Using Claude Code/m);
+    // The body content should still be present
+    expect(flow!.content).toContain("Claude Code");
+  });
+
+  test("every flow has a non-empty title", () => {
+    const flows = getAllFlows();
+    expect(flows.length).toBeGreaterThan(0);
+    flows.forEach((flow) => {
+      expect(flow.title).toBeTruthy();
+      expect(flow.title.trim().length).toBeGreaterThan(0);
+    });
+  });
+
+  test("flow with frontmatter title preserves content H1 independently", () => {
+    // content/flows/2026/03/05.md has frontmatter title — any H1 in content
+    // should still be stripped, but title comes from frontmatter
+    const flow = getFlowBySlug("2026/03/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("JSDoc type comments");
+    // Content should not start with an H1
+    expect(flow!.content).not.toMatch(/^\s*#\s+/);
+  });
+});

package/tests/integration/reading-time-headings.test.ts

@@ -50,16 +50,12 @@ describe("Integration: Reading Time & Headings", () => {
   });
 
   test("short posts have 1 min read", () => {
-    const posts = getAllPosts();
-    // Find a short post (content < 200 words)
-    const shortPost = posts.find((p) => {
-      const wordCount = p.content.split(/\s+/).length;
-      return wordCount < 200;
-    });
-
-    if (shortPost) {
-      expect(shortPost.readingTime).toBe("1 min read");
+    const shortPost = getPostBySlug("legacy-markdown");
+    expect(shortPost).toBeDefined();
+    if (!shortPost) {
+      throw new Error("fixture 'legacy-markdown' not found");
     }
+    expect(shortPost.readingTime).toBe("1 min read");
   });
 
   test("multilingual post has headings with correct IDs", () => {

package/tests/integration/series-draft.test.ts

@@ -1,6 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import { getSeriesData, getAllSeries } from "../../src/lib/markdown";
 
+function restoreEnvVar(key: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}
+
 describe("Integration: Series Draft Support", () => {
   test("all series are included when NODE_ENV is not production", () => {
     // In test environment NODE_ENV is typically 'test'
@@ -18,20 +26,25 @@ describe("Integration: Series Draft Support", () => {
 
   test("draft filtering code path runs without error in production mode", () => {
     const originalEnv = process.env.NODE_ENV;
+    const originalPythonRst = process.env.AMYTIS_ENABLE_PYTHON_RST;
     try {
       process.env.NODE_ENV = "production";
+      process.env.AMYTIS_ENABLE_PYTHON_RST = "0";
       // This should not throw; draft series are simply excluded
       const series = getAllSeries();
       expect(typeof series).toBe("object");
     } finally {
-      process.env.NODE_ENV = originalEnv;
+      restoreEnvVar("NODE_ENV", originalEnv);
+      restoreEnvVar("AMYTIS_ENABLE_PYTHON_RST", originalPythonRst);
     }
   });
 
   test("draft series are excluded in production mode", () => {
     const originalEnv = process.env.NODE_ENV;
+    const originalPythonRst = process.env.AMYTIS_ENABLE_PYTHON_RST;
     try {
       process.env.NODE_ENV = "production";
+      process.env.AMYTIS_ENABLE_PYTHON_RST = "0";
       const allSeries = getAllSeries();
       
       // Verify that every series returned has draft: false (or undefined which defaults to false)
@@ -40,7 +53,8 @@ describe("Integration: Series Draft Support", () => {
         expect(seriesData?.draft).not.toBe(true);
       });
     } finally {
-      process.env.NODE_ENV = originalEnv;
+      restoreEnvVar("NODE_ENV", originalEnv);
+      restoreEnvVar("AMYTIS_ENABLE_PYTHON_RST", originalPythonRst);
     }
   });
 });

package/tests/integration/series.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { parseRstDocument, RstParseError } from "../../src/lib/rst";
 import {
   getAllSeries,
+  getAdjacentPosts,
   getSeriesData,
+  getSeriesLatestPostDate,
   getSeriesPosts,
   getFeaturedPosts,
   getFeaturedSeries,
@@ -13,6 +16,10 @@ describe("Integration: Series", () => {
     expect(Object.keys(series).length).toBeGreaterThan(0);
     expect(series).toHaveProperty("nextjs-deep-dive");
     expect(series).toHaveProperty("digital-garden");
+    expect(series).toHaveProperty("rst-legacy");
+    expect(series).toHaveProperty("rst-readme");
+    expect(series).toHaveProperty("rst-toctree");
+    expect(series).toHaveProperty("rst-toctree-precedence");
   });
 
   test("getSeriesData returns metadata with correct fields", () => {
@@ -30,6 +37,49 @@ describe("Integration: Series", () => {
     expect(data).toBeNull();
   });
 
+  test("getSeriesData loads rST series metadata", () => {
+    const data = getSeriesData("rst-legacy");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst Legacy Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.sort).toBe("manual");
+    expect(data!.posts).toEqual(["getting-started", "deeper-notes"]);
+  });
+
+  test("getSeriesData accepts README.rst as the series index", () => {
+    const data = getSeriesData("rst-readme");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst README Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.posts).toEqual(["readme-index-post"]);
+  });
+
+  test("getSeriesData derives manual order from rST toctree when posts metadata is absent", () => {
+    const data = getSeriesData("rst-toctree");
+    expect(data).not.toBeNull();
+    expect(data!.title).toBe("Rst Toctree Series");
+    expect(data!.sourceFormat).toBe("rst");
+    expect(data!.sort).toBe("manual");
+    expect(data!.posts).toEqual(["second-post", "first-post"]);
+  });
+
+  test("getSeriesData rejects unsafe series slugs", () => {
+    expect(() => getSeriesData("../etc/passwd")).toThrow();
+    expect(() => getSeriesData("nested/slug")).toThrow();
+  });
+
+  test("rST series indexes reject impossible dates", () => {
+    expect(() => parseRstDocument([
+      "Broken rST Series",
+      "=================",
+      "",
+      ":date: 2021-16-15",
+      "",
+      "Body.",
+      "",
+    ].join("\n"))).toThrow(RstParseError);
+  });
+
   test("getSeriesPosts returns posts in manual order for manual series", () => {
     const seriesData = getSeriesData("nextjs-deep-dive");
     expect(seriesData?.sort).toBe("manual");
@@ -62,6 +112,49 @@ describe("Integration: Series", () => {
     expect(posts).toEqual([]);
   });
 
+  test("getSeriesPosts returns rST posts in manual order", () => {
+    const posts = getSeriesPosts("rst-legacy");
+    expect(posts.map(post => post.slug)).toEqual(["getting-started", "deeper-notes"]);
+    expect(posts.every(post => post.sourceFormat === "rst")).toBe(true);
+  });
+
+  test("getSeriesPosts loads posts for README.rst-based series", () => {
+    const posts = getSeriesPosts("rst-readme");
+    expect(posts.map(post => post.slug)).toEqual(["readme-index-post"]);
+    expect(posts[0]?.sourceFormat).toBe("rst");
+  });
+
+  test("getSeriesPosts follows rST toctree order when posts metadata is absent", () => {
+    const posts = getSeriesPosts("rst-toctree");
+    expect(posts.map(post => post.slug)).toEqual(["second-post", "first-post"]);
+    expect(posts.every(post => post.sourceFormat === "rst")).toBe(true);
+  });
+
+  test("getSeriesLatestPostDate uses the newest post date instead of manual series order", () => {
+    expect(getSeriesData("nextjs-deep-dive")?.sort).toBe("manual");
+    expect(getSeriesPosts("nextjs-deep-dive").map(post => post.date)).toEqual(["2026-01-30", "2026-01-31"]);
+    expect(getSeriesLatestPostDate("nextjs-deep-dive")).toBe("2026-01-31");
+  });
+
+  test("getAdjacentPosts follows rST series order instead of global post date order", () => {
+    const first = getAdjacentPosts("getting-started");
+    expect(first.prev?.slug ?? null).toBeNull();
+    expect(first.next?.slug).toBe("deeper-notes");
+
+    const second = getAdjacentPosts("deeper-notes");
+    expect(second.prev?.slug).toBe("getting-started");
+    expect(second.next?.slug ?? null).toBeNull();
+  });
+
+  test("explicit rST posts metadata takes precedence over toctree order", () => {
+    const data = getSeriesData("rst-toctree-precedence");
+    expect(data).not.toBeNull();
+    expect(data!.posts).toEqual(["first-post", "second-post"]);
+
+    const posts = getSeriesPosts("rst-toctree-precedence");
+    expect(posts.map(post => post.slug)).toEqual(["first-post", "second-post"]);
+  });
+
   test("getFeaturedPosts returns only posts with featured: true", () => {
     const featured = getFeaturedPosts();
     featured.forEach((post) => {

package/tests/tooling/build-pagefind.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import {
+  collectHtmlFileHashes,
+  getPagefindManifestPathForTests,
+  shouldSkipPagefindBuild,
+} from "../../scripts/build-pagefind";
+
+const createdDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of createdDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  fs.rmSync(path.join(process.cwd(), ".cache", "pagefind"), { recursive: true, force: true });
+});
+
+function makeTempDir(prefix: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  createdDirs.push(dir);
+  return dir;
+}
+
+describe("Tooling: build-pagefind", () => {
+  test("collectHtmlFileHashes hashes HTML files by relative path", () => {
+    const siteDir = makeTempDir("amytis-pagefind-site-");
+    fs.mkdirSync(path.join(siteDir, "posts"), { recursive: true });
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Home</body></html>", "utf8");
+    fs.writeFileSync(path.join(siteDir, "posts", "hello.html"), "<html><body>Hello</body></html>", "utf8");
+    fs.writeFileSync(path.join(siteDir, "notes.txt"), "ignore", "utf8");
+
+    const hashes = collectHtmlFileHashes(siteDir);
+
+    expect(Object.keys(hashes)).toEqual(["index.html", "posts/hello.html"]);
+    expect(hashes["index.html"]).toBeTruthy();
+    expect(hashes["posts/hello.html"]).toBeTruthy();
+  });
+
+  test("skips Pagefind when HTML hashes and output path are unchanged", () => {
+    const siteDir = makeTempDir("amytis-pagefind-site-");
+    const outputDir = makeTempDir("amytis-pagefind-out-");
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Home</body></html>", "utf8");
+    fs.writeFileSync(path.join(outputDir, "pagefind.js"), "stub", "utf8");
+
+    const hashes = collectHtmlFileHashes(siteDir);
+    const manifestPath = getPagefindManifestPathForTests(siteDir, outputDir);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(
+      manifestPath,
+      JSON.stringify({
+        version: "1",
+        sitePath: path.resolve(siteDir),
+        outputPath: path.resolve(outputDir),
+        files: hashes,
+      }),
+      "utf8",
+    );
+
+    expect(shouldSkipPagefindBuild(siteDir, outputDir, hashes)).toBe(true);
+
+    fs.writeFileSync(path.join(siteDir, "index.html"), "<html><body>Changed</body></html>", "utf8");
+    expect(shouldSkipPagefindBuild(siteDir, outputDir, collectHtmlFileHashes(siteDir))).toBe(false);
+  });
+});

package/tests/unit/static-params.test.ts

@@ -131,6 +131,7 @@ beforeAll(() => {
     getSeriesData: (slug: string) => mockedSeriesData[slug] ?? null,
     getSeriesPosts: () => [],
     getSeriesAuthors: () => [],
+    getCollectionsForPost: () => [],
 
     getAuthorSlug: (name: string) =>
       name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
@@ -254,11 +255,101 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).toContainEqual({ slug: 'old-name' });
     });
 
+    test('series/[slug] includes raw and encoded Unicode slug in non-production', async () => {
+      mockedSeries = { '软件构架设计': [] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计' });
+      expect(params).toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1' });
+    });
+
+    test('series/[slug] includes only raw Unicode slug in production', async () => {
+      mockedSeries = { '软件构架设计': [] };
+      process.env.NODE_ENV = 'production';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计' });
+      expect(params).not.toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1' });
+    });
+
     test('series/[slug]/page/[page] returns [{ slug: "_", page: "2" }]', async () => {
       const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
       const params = await generateStaticParams();
       expect(params).toEqual([{ slug: '_', page: '2' }]);
     });
+
+    test('series/[slug]/page/[page] includes encoded Unicode slug in non-production', async () => {
+      mockedSeries = { '软件构架设计': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', page: '2' });
+      expect(params).toContainEqual({ slug: '%E8%BD%AF%E4%BB%B6%E6%9E%84%E6%9E%B6%E8%AE%BE%E8%AE%A1', page: '2' });
+    });
+
+    test('series/[slug]/page/[page] includes redirectFrom slug when series is renamed', async () => {
+      mockedSeries = { 'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = { 'new-name': { redirectFrom: ['/series/old-name'], title: 'New Series' } };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: 'new-name', page: '2' });
+      expect(params).toContainEqual({ slug: 'old-name', page: '2' });
+    });
+
+    test('series/[slug]/page/[page] redirects old alias slugs to the canonical paginated path', async () => {
+      mockedSeries = { 'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = { 'new-name': { redirectFrom: ['/series/old-name'], title: 'New Series' } };
+      const page = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(page.default({
+        params: Promise.resolve({ slug: 'old-name', page: '2' }),
+      })).resolves.toBeDefined();
+    });
+
+    test('series routes match percent-encoded redirectFrom aliases after normalization', async () => {
+      mockedSeries = { '软件构架设计': Array.from({ length: 6 }, (_, i) => ({ slug: `p${i + 1}` })) };
+      mockedSeriesData = {
+        '软件构架设计': {
+          redirectFrom: ['/series/%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1'],
+          title: '软件构架设计',
+        },
+      };
+
+      const seriesPage = await import('../../src/app/series/[slug]/page');
+      await expect(seriesPage.default({
+        params: Promise.resolve({ slug: '%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1' }),
+      })).resolves.toBeDefined();
+
+      const paginatedPage = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(paginatedPage.default({
+        params: Promise.resolve({ slug: '%E8%BD%AF%E4%BB%B6%E8%AE%BE%E8%AE%A1', page: '2' }),
+      })).resolves.toBeDefined();
+    });
+
+    test('series/[slug]/page/[page] throws when redirectFrom alias conflicts with an existing series slug', async () => {
+      mockedSeries = {
+        'existing-slug': Array.from({ length: 6 }, (_, i) => ({ slug: `a${i + 1}` })),
+        'new-name': Array.from({ length: 6 }, (_, i) => ({ slug: `b${i + 1}` })),
+      };
+      mockedSeriesData = {
+        'new-name': { redirectFrom: ['/series/existing-slug'], title: 'New Series' },
+      };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(generateStaticParams()).rejects.toThrow(/conflicts with an existing series slug/i);
+    });
+
+    test('series/[slug]/page/[page] throws when two series claim the same redirectFrom alias', async () => {
+      mockedSeries = {
+        'first-series': Array.from({ length: 6 }, (_, i) => ({ slug: `a${i + 1}` })),
+        'second-series': Array.from({ length: 6 }, (_, i) => ({ slug: `b${i + 1}` })),
+      };
+      mockedSeriesData = {
+        'first-series': { redirectFrom: ['/series/old-name'], title: 'First' },
+        'second-series': { redirectFrom: ['/series/old-name'], title: 'Second' },
+      };
+      const { generateStaticParams } = await import('../../src/app/series/[slug]/page/[page]/page');
+      await expect(generateStaticParams()).rejects.toThrow(/claimed by both/i);
+    });
   });
 
   describe('posts routes', () => {
@@ -504,6 +595,26 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).toContainEqual({ slug: 'old-prefix', postSlug: encodeURIComponent('中文文章') });
     });
 
+    test('[slug]/[postSlug] includes encoded Unicode prefix variants in non-production', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: 'architecture-post' }] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/[slug]/[postSlug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: 'architecture-post' });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: 'architecture-post' });
+    });
+
+    test('[slug]/[postSlug] includes encoded Unicode prefix and postSlug variants together in non-production', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: '中文文章' }] };
+      process.env.NODE_ENV = 'development';
+      const { generateStaticParams } = await import('../../src/app/[slug]/[postSlug]/page');
+      const params = await generateStaticParams();
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: '中文文章' });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: '中文文章' });
+      expect(params).toContainEqual({ slug: '软件构架设计', postSlug: encodeURIComponent('中文文章') });
+      expect(params).toContainEqual({ slug: encodeURIComponent('软件构架设计'), postSlug: encodeURIComponent('中文文章') });
+    });
+
     test('[slug]/[postSlug] does not include encoded Unicode postSlug variants in production', async () => {
       mockedPosts = [{ slug: 'my-post', redirectFrom: ['/old-prefix/中文文章'] }];
       process.env.NODE_ENV = 'production';
@@ -513,6 +624,35 @@ describe('generateStaticParams — placeholder when content is empty', () => {
       expect(params).not.toContainEqual({ slug: 'old-prefix', postSlug: encodeURIComponent('中文文章') });
     });
 
+    test('[slug]/[postSlug] page resolves encoded Unicode series prefix without notFound', async () => {
+      mockedSeries = { '软件构架设计': [{ slug: 'my-post' }] };
+      mockedSeriesData = { '软件构架设计': { title: '软件构架设计' } };
+      mockedPosts = [{
+        slug: 'my-post',
+        title: 'My Post',
+        excerpt: 'Excerpt',
+        date: '2026-01-01',
+        authors: ['Author'],
+        series: '软件构架设计',
+        redirectFrom: ['/软件构架设计/my-post'],
+        layout: 'post',
+        content: 'Body',
+        headings: [],
+        imageBaseSlug: 'posts',
+        category: 'Test',
+        tags: [],
+        readingTime: '1 min read',
+      }];
+
+      const page = await import('../../src/app/[slug]/[postSlug]/page');
+      await expect(page.default({
+        params: Promise.resolve({
+          slug: encodeURIComponent('软件构架设计'),
+          postSlug: 'my-post',
+        }),
+      })).resolves.toBeDefined();
+    });
+
     test('[slug]/page/[page]/page returns placeholder when no custom paths', async () => {
       const { generateStaticParams } = await import('../../src/app/[slug]/page/[page]/page');
       const params = await generateStaticParams();