@decocms/apps-blog 8.0.0 → 8.1.0-next.0

package/README.md

@@ -0,0 +1,21 @@
+# `@decocms/apps-blog` (v7 only)
+
+This package is the v7 blog app. It has no next-major surface: the next major
+ships no blog package, and nothing new is added here.
+
+In the next major a blog is content plus code the site owns:
+
+| v7 (this package) | Next major |
+|---|---|
+| `BlogPost`, `Author`, `Category` and the other types | The blog template's own types. |
+| `getRecordsByPath` (reads the global decofile) | `client.list("post")`, `client.list("author")`, `client.list("category")` over saved blocks, with `where` / `sort` / `limit`. It reads the request's revision, so drafts work. |
+| `handlePosts` (filter, sort, paginate) | `client.list` options, or the template's own helper. |
+| `createBlogLoaders` and the `blog/loaders/*.ts` keys | Data-only blocks (`const post = (props: Post) => props`) in the template's block map. The `blog/loaders/*.ts` names stored by v7 content are registered as aliases, or as converter functions where the old shape differs, and loaders the site used are vendored under their old keys by the migration. |
+| `blog/sections/blocks/*.tsx` (post body blocks) | Data-only blocks plus a renderer in the template. |
+| `sections/Seo/SeoBlogPost*.tsx` | SEO helpers in the template. |
+| Ratings, reviews and view-count actions, and the `loaders/extensions/*` ratings/reviews loaders | Site code (see *Migrating from v7*, loaders and actions). |
+
+See the next-major docs: *Data-only blocks* (schema), `client.list` (API
+reference), *Pages and routing*, and *Migrating from v7*.
+
+Port notes for the v7 code are in [`src/README.md`](./src/README.md).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@decocms/apps-blog",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
-  "description": "Deco app: blog content and CMS integration",
+  "description": "v7 only: Deco blog app. The next major ships no blog package; blogs use data-only blocks and client.list in their template.",
   "repository": {
     "type": "git",
     "url": "https://github.com/decocms/blocks.git",
@@ -16,10 +16,19 @@
   "exports": {
     ".": "./src/index.ts",
     "./mod": "./src/mod.ts",
+    "./client": "./src/client.ts",
     "./types": "./src/types.ts",
+    "./manifest.gen": "./src/manifest.gen.ts",
     "./loaderMap": "./src/loaderMap.ts",
     "./loaders/*": "./src/loaders/*.ts",
+    "./loaders/extensions/*": "./src/loaders/extensions/*.ts",
+    "./actions/*": "./src/actions/*.ts",
     "./core/*": "./src/core/*.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./sections/*": "./src/sections/*.tsx",
+    "./sections/Seo/*": "./src/sections/Seo/*.tsx",
+    "./sections/blocks/*": "./src/sections/blocks/*.tsx",
+    "./static/*": "./src/static/*.ts",
     "./registry": "./src/registry.ts"
   },
   "scripts": {
@@ -29,9 +38,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
-    "@decocms/apps-commerce": "8.0.0",
-    "@decocms/apps-website": "8.0.0"
+    "@decocms/blocks": "8.1.0-next.0",
+    "@decocms/apps-commerce": "8.1.0-next.0",
+    "@decocms/apps-website": "8.1.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/README.md

@@ -0,0 +1,69 @@
+# `@decocms/apps-blog` — port status
+
+Source of truth: [`deco-cx/apps/blog`](https://github.com/deco-cx/apps/tree/main/blog).
+This package was originally copied from `apps-start`'s already-reduced blog port
+(Task 13 of `docs/apps-monorepo-migration-plan.md`), not from the Deno original,
+so a chunk of the upstream surface was missing. This file tracks what is now in
+sync and what deliberately isn't.
+
+## Ported
+
+| Upstream | Here | Notes |
+|---|---|---|
+| `types.ts` | `src/types.ts` | Full parity, incl. `PostStatus`, `isPublishedStatus`, `isLivePost`, `Publisher`, `Review`/`Rating`/`AggregateRating`, `Ignore`, `ImageCarousel`. `Section` is redeclared as the opaque `any` type — see the docstring, it's what triggers the admin's section picker. |
+| `utils/{date,constants,jsonLD,sanitizeHtml,hardSanitize,blocksToSections}.ts` | `src/utils/` | Near-literal; pure functions. |
+| `core/handlePosts.ts` | `src/core/handlePosts.ts` | Incl. `filterRoutablePosts` and UTC-pinned date sorting. |
+| `core/records.ts` | `src/core/records.ts` | `getRecordsByPath` uses `loadBlocks()` instead of `ctx.get(resolvables)`. Ratings/reviews go through the adapter (below). |
+| `loaders/*.ts` (9) | `src/loaders/` | `ctx` replaced by `src/client.ts`; `(props, req?)` signatures. |
+| `loaders/extensions/*/[ratings,reviews].ts` (6) | `src/loaders/extensions/` | — |
+| `actions/submit{Rating,Review,View}.ts` | `src/actions/` | Persistence via the adapter. |
+| `sections/Seo/*.tsx` (2) | `src/sections/Seo/` | Reuse `Seo`/`renderTemplateString`/`SEOSection` from `@decocms/apps-website/components/Seo`. |
+| `sections/Template.tsx` | `src/sections/Template.tsx` | `renderSection` replaced by `getSyncComponent` from `@decocms/blocks/cms/client`. |
+| `sections/blocks/*.tsx` (17) | `src/sections/blocks/` | `class` → `className`, SVG attrs camelCased; otherwise unchanged. |
+| `static/css.ts` | `src/static/css.ts` | Verbatim. |
+
+## Deliberately not ported
+
+| Upstream | Why |
+|---|---|
+| `db/schema.ts` | Drizzle/SQLite table definitions for the `records` app. Neither the app nor `drizzle-orm` exists in this monorepo, and pulling them in would make every site installing the blog carry a DB client. The table/column names now live on the site's side of `src/core/blogRecords.ts`. |
+| `loaders/extensions/{BlogpostList,BlogpostListing,BlogpostPage}.ts` | Three-line delegations to `website/loaders/extension.ts` — the *generic* extension-composition loader. That loader has not been ported into `@decocms/apps-website`; reimplementing it here would put a website-app concern in the wrong package. The 6 concrete ratings/reviews extensions are ported and callable directly. **Tracked gap: port `website/loaders/extension.ts` into `@decocms/apps-website`.** |
+| `manifest.gen.ts` (as generated) | `scripts/generate-manifests.ts` doesn't exist in this repo (deferred, `docs/apps-monorepo-migration-plan.md`). `src/manifest.gen.ts` is hand-maintained — add new loaders/actions/sections to it manually. |
+| `mod.ts`'s `preview` / `PreviewContainer` | `utils/preview.tsx` is Deno-app scaffolding with no equivalent here; `preview` is `undefined`, matching every other `apps-*` package. |
+
+## Ratings, reviews and view counts
+
+These three features need persistence. Upstream reaches the separate `records`
+app (`await ctx.invoke.records.loaders.drizzle()`); here the dependency is
+inverted, the same way `@decocms/blocks-admin` inverts KV via
+`setFastDeployKVGetter`:
+
+```ts
+import { setBlogRecordsAdapter } from "@decocms/apps-blog";
+
+setBlogRecordsAdapter({
+  listPostViews: () => db.select(...),
+  incrementPostView: (id) => ...,
+  // listRatings, upsertRating, listReviews, getReview, createReview, updateReview
+});
+```
+
+Every method is optional. With **no adapter registered**, reads return `[]`,
+writes return `null`, `submitView` returns `{ count: 0 }`, and `view_asc` /
+`view_desc` sorting falls back to date order — so a blog with no comments and no
+view counter works untouched. Note this differs from upstream on one point:
+the Deno app *threw* `"Deco Records not installed!"` on a view sort without the
+backend; degrading was chosen instead, since view sorting is an enhancement and
+a missing backend shouldn't blank a listing.
+
+## Divergences from upstream worth knowing
+
+- **Title and view sorts are inverted** — `title_asc` yields Z-A, and
+  `view_desc` puts the *least*-viewed post first. Both come from upstream's
+  comparator (`sortOrder === "desc" ? comparison : -comparison` over an `a - b`
+  difference); only the `date` branch, which compares `b - a`, reads the right
+  way round. Preserved on purpose so a site moving off the Deno app sees no
+  reordering — see the comments in `src/core/handlePosts.ts`. Fix upstream
+  first, then here.
+- **`sortPosts([])` throws** (it reads `blogPosts[0]`). Upstream does too;
+  `handlePosts` guards the empty case before calling it.

package/src/__tests__/blogRecords.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Scope: the injectable persistence port that replaces the Deno app's `records`
+ * dependency — that reads/writes route through the registered adapter, and that
+ * everything degrades safely when a site registers none (or a partial one).
+ *
+ * The degrade path is the important half: it is the default for any site that
+ * installs the blog app without a database, so a regression here breaks blogs
+ * that never asked for ratings at all.
+ *
+ * Deliberately not covered: any real database. The adapter boundary exists
+ * precisely so this package never needs one.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import submitRating from "../actions/submitRating";
+import submitReview from "../actions/submitReview";
+import submitView from "../actions/submitView";
+import {
+  type BlogRecordsAdapter,
+  type CreateReviewInput,
+  type ListReviewsOptions,
+  setBlogRecordsAdapter,
+  type UpdateReviewInput,
+} from "../core/blogRecords";
+import { sortPosts } from "../core/handlePosts";
+import { getRatings, getReviews, getReviewsBySlug } from "../core/records";
+import type { BlogPost, Review } from "../types";
+
+const G = globalThis as unknown as { __decoBlogRecordsAdapter?: BlogRecordsAdapter };
+
+const post = (slug: string, date = "2024-01-01"): BlogPost => ({
+  title: slug,
+  slug,
+  date,
+  excerpt: "",
+});
+
+const clearAdapter = () => {
+  delete G.__decoBlogRecordsAdapter;
+};
+
+beforeEach(clearAdapter);
+afterEach(clearAdapter);
+
+describe("with no adapter registered", () => {
+  it("getRatings yields a zeroed aggregate rather than throwing", async () => {
+    const result = await getRatings({ post: post("a") });
+    expect(result.aggregateRating).toEqual({
+      "@type": "AggregateRating",
+      ratingCount: 0,
+      ratingValue: 0,
+      bestRating: 5,
+      worstRating: 1,
+    });
+    expect(result.contentRating).toEqual([]);
+  });
+
+  it("getReviews yields an empty list and a zero count", async () => {
+    const result = await getReviews({ post: post("a") });
+    expect(result.review).toEqual([]);
+    expect(result.aggregateRating?.reviewCount).toBe(0);
+  });
+
+  it("write actions report failure instead of throwing", async () => {
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+    expect(await submitReview({ action: "create", reviewBody: "hi" })).toBeNull();
+    // A view beacon gets a well-formed response, not an error.
+    expect(await submitView({ id: "a" })).toEqual({ count: 0 });
+  });
+
+  it("view sorting falls back to date order instead of throwing", async () => {
+    // Upstream threw "Deco Records not installed!" here; degrading is the
+    // deliberate difference — see this package's README.
+    const posts = [post("old", "2024-01-01"), post("new", "2024-03-01")];
+    const sorted = await sortPosts(posts, "view_desc");
+    expect(sorted.map((p) => p.slug)).toEqual(["new", "old"]);
+  });
+});
+
+describe("with an adapter registered", () => {
+  it("getRatings aggregates the adapter's rows and stamps the scale", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => [
+        { "@type": "Rating", ratingValue: 5 },
+        { "@type": "Rating", ratingValue: 3 },
+      ],
+    });
+
+    const result = await getRatings({ post: post("a") });
+    expect(result.aggregateRating).toMatchObject({ ratingCount: 2, ratingValue: 4 });
+    // bestRating/worstRating are a property of this app's UI, not of the row.
+    expect(result.contentRating?.[0]).toMatchObject({ bestRating: 5, worstRating: 1 });
+  });
+
+  it("getRatings honours ignoreRatings when computing the aggregate", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => [
+        { "@type": "Rating", ratingValue: 5 },
+        { "@type": "Rating", ratingValue: 1, additionalType: "spam" },
+      ],
+    });
+
+    const result = await getRatings({
+      post: post("a"),
+      ignoreRatings: { active: true, markedAs: ["spam"] },
+    });
+    expect(result.aggregateRating).toMatchObject({ ratingCount: 1, ratingValue: 5 });
+  });
+
+  it("onlyAggregate omits the per-rating list", async () => {
+    setBlogRecordsAdapter({ listRatings: async () => [{ "@type": "Rating", ratingValue: 4 }] });
+    const result = await getRatings({ post: post("a"), onlyAggregate: true });
+    expect(result.contentRating).toBeUndefined();
+    expect(result.aggregateRating?.ratingValue).toBe(4);
+  });
+
+  it("translates an active ignoreReviews into excludeAdditionalTypes", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+
+    await getReviewsBySlug({
+      slug: "a",
+      ignoreReviews: { active: true, markedAs: ["pending"] },
+      orderBy: "date_asc",
+    });
+    expect(listReviews).toHaveBeenCalledWith({
+      slug: "a",
+      excludeAdditionalTypes: ["pending"],
+      orderBy: "date_asc",
+    });
+  });
+
+  it("leaves excludeAdditionalTypes unset when ignoreReviews is inactive or empty", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+
+    await getReviewsBySlug({ slug: "a", ignoreReviews: { active: false, markedAs: ["x"] } });
+    await getReviewsBySlug({ slug: "a", ignoreReviews: { active: true, markedAs: [] } });
+    for (const call of listReviews.mock.calls) {
+      expect(call[0]).toMatchObject({ excludeAdditionalTypes: undefined });
+    }
+  });
+
+  it("defaults review ordering to date_desc", async () => {
+    const listReviews = vi.fn(async (_opts: ListReviewsOptions): Promise<Review[]> => []);
+    setBlogRecordsAdapter({ listReviews });
+    await getReviewsBySlug({ slug: "a" });
+    expect(listReviews).toHaveBeenCalledWith(expect.objectContaining({ orderBy: "date_desc" }));
+  });
+
+  it("stamps view counts onto posts and sorts by them (inverted, per upstream)", async () => {
+    setBlogRecordsAdapter({
+      listPostViews: async () => [
+        { id: "low", userInteractionCount: 2 },
+        { id: "high", userInteractionCount: 90 },
+      ],
+    });
+
+    const posts = [post("low"), post("high")];
+    // `view_desc` yields least-viewed-first: upstream's comparator is `a - b`
+    // under `desc`. Preserved deliberately — see the comment in handlePosts.ts.
+    expect((await sortPosts(posts, "view_desc")).map((p) => p.slug)).toEqual(["low", "high"]);
+    expect((await sortPosts(posts, "view_asc")).map((p) => p.slug)).toEqual(["high", "low"]);
+    // Either way the counts are attached to the posts, which is what the SEO
+    // JSON-LD reads as interactionStatistic.
+    expect(posts.find((p) => p.slug === "high")?.interactionStatistic).toEqual({
+      "@type": "InteractionCounter",
+      userInteractionCount: 90,
+    });
+  });
+
+  it("increments a view through the adapter", async () => {
+    setBlogRecordsAdapter({ incrementPostView: async () => ({ count: 7 }) });
+    expect(await submitView({ id: "a" })).toEqual({ count: 7 });
+  });
+
+  it("swallows an adapter failure on read and returns the empty shape", async () => {
+    setBlogRecordsAdapter({
+      listRatings: async () => {
+        throw new Error("db down");
+      },
+    });
+    const result = await getRatings({ post: post("a") });
+    expect(result.contentRating).toEqual([]);
+    expect(result.aggregateRating?.ratingCount).toBe(0);
+  });
+
+  it("swallows an adapter failure on write and reports it as null", async () => {
+    setBlogRecordsAdapter({
+      upsertRating: async () => {
+        throw new Error("db down");
+      },
+    });
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+  });
+
+  it("refuses to update a review that does not exist", async () => {
+    setBlogRecordsAdapter({
+      getReview: async () => null,
+      updateReview: async () => null,
+    });
+    expect(await submitReview({ action: "update", id: "missing", reviewBody: "x" })).toBeNull();
+  });
+
+  it("patches an update over the stored review, preserving untouched fields", async () => {
+    const updateReview = vi.fn(
+      async (_id: string, _patch: UpdateReviewInput): Promise<Review | null> => null,
+    );
+    setBlogRecordsAdapter({
+      getReview: async () => ({
+        "@type": "Review",
+        id: "r1",
+        itemReviewed: "a",
+        reviewBody: "old body",
+        reviewHeadline: "old headline",
+        additionalType: "approved",
+        datePublished: "2024-01-01T00:00:00.000Z",
+        author: { name: "Ana" },
+      }),
+      updateReview,
+    });
+
+    const result = await submitReview({ action: "update", id: "r1", reviewBody: "new body" });
+
+    // Only the sent field changes; headline/status/author/datePublished survive.
+    expect(updateReview).toHaveBeenCalledWith(
+      "r1",
+      expect.objectContaining({
+        reviewBody: "new body",
+        reviewHeadline: "old headline",
+        additionalType: "approved",
+      }),
+    );
+    expect(result).toMatchObject({
+      "@type": "Review",
+      id: "r1",
+      reviewBody: "new body",
+      datePublished: "2024-01-01T00:00:00.000Z",
+      author: { name: "Ana" },
+    });
+  });
+
+  it("creates a review with both timestamps set", async () => {
+    const createReview = vi.fn(async (_input: CreateReviewInput): Promise<Review | null> => null);
+    setBlogRecordsAdapter({ createReview });
+
+    const result = await submitReview({
+      action: "create",
+      itemReviewed: "a",
+      reviewBody: "great",
+    });
+
+    const arg = createReview.mock.calls[0][0];
+    expect(arg.datePublished).toBe(arg.dateModified);
+    expect(result).toMatchObject({ "@type": "Review", reviewBody: "great" });
+  });
+
+  it("returns null when the adapter implements only part of the port", async () => {
+    // A site that wants view counts and nothing else.
+    setBlogRecordsAdapter({ incrementPostView: async () => ({ count: 1 }) });
+    expect(await submitReview({ action: "create", reviewBody: "x" })).toBeNull();
+    expect(
+      await submitRating({ itemReviewed: "a", author: { email: "a@b.com" }, ratingValue: 5 }),
+    ).toBeNull();
+  });
+});

package/src/__tests__/categoryTree.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+import {
+  ancestorsOf,
+  categoryPathname,
+  childrenOf,
+  descendantSlugs,
+  indexCategories,
+  MAX_CATEGORY_DEPTH,
+  withCategoryPath,
+} from "../core/categoryTree";
+import type { Category } from "../types";
+
+/**
+ * Categories come from a decofile a human types into, so every walk over
+ * `parentSlug` has to survive garbage: a slug pointing at nothing, at itself,
+ * or around a cycle. None of these may hang a request.
+ */
+const cat = (slug: string, parentSlug?: string): Category => ({
+  name: slug.toUpperCase(),
+  slug,
+  ...(parentSlug ? { parentSlug } : {}),
+});
+
+const slugsOf = (chain: Category[] | null) => chain?.map((c) => c.slug) ?? null;
+
+// ---------------------------------------------------------------------------
+// ancestorsOf / indexCategories
+// ---------------------------------------------------------------------------
+describe("ancestorsOf", () => {
+  it("returns the chain root first", () => {
+    const categories = [cat("root"), cat("mid", "root"), cat("leaf", "mid")];
+    const chain = ancestorsOf("leaf", indexCategories(categories));
+
+    expect(slugsOf(chain)).toEqual(["root", "mid", "leaf"]);
+    expect(categoryPathname(chain as Category[])).toEqual("root/mid/leaf");
+  });
+
+  it("returns null for an unknown slug", () => {
+    expect(ancestorsOf("ghost", indexCategories([cat("root")]))).toEqual(null);
+  });
+
+  it("yields no chain on a cycle instead of looping", () => {
+    const categories = [cat("a", "b"), cat("b", "a")];
+    // Walking up from `a` reaches `b`, whose parent is `a` again. The visited set
+    // stops the walk; the chain is reported as unusable rather than truncated,
+    // because a truncated one would name a canonical URL missing its top.
+    expect(ancestorsOf("a", indexCategories(categories))).toEqual(null);
+  });
+
+  it("treats a self-referencing category as a root", () => {
+    expect(slugsOf(ancestorsOf("a", indexCategories([cat("a", "a")])))).toEqual(["a"]);
+  });
+
+  it("stops the walk on a dangling parentSlug", () => {
+    const categories = [cat("leaf", "does-not-exist")];
+    expect(slugsOf(ancestorsOf("leaf", indexCategories(categories)))).toEqual(["leaf"]);
+  });
+
+  it("rejects a chain deeper than MAX_CATEGORY_DEPTH", () => {
+    const chainOf = (length: number) =>
+      Array.from({ length }, (_, i) => cat(`c${i}`, i === 0 ? undefined : `c${i - 1}`));
+
+    const deepest = chainOf(MAX_CATEGORY_DEPTH);
+    expect(ancestorsOf(`c${MAX_CATEGORY_DEPTH - 1}`, indexCategories(deepest))?.length).toEqual(
+      MAX_CATEGORY_DEPTH,
+    );
+
+    // One level past the ceiling: reporting the truncated chain would hand the
+    // canonical URL a path missing its topmost segments, so it reports nothing.
+    const tooDeep = chainOf(MAX_CATEGORY_DEPTH + 1);
+    expect(ancestorsOf(`c${MAX_CATEGORY_DEPTH}`, indexCategories(tooDeep))).toEqual(null);
+  });
+});
+
+describe("indexCategories", () => {
+  it("resolves duplicated slugs to the first record", () => {
+    const first: Category = { name: "First", slug: "dup" };
+    const second: Category = { name: "Second", slug: "dup", parentSlug: "dup" };
+    const index = indexCategories([first, second]);
+
+    expect(index.get("dup")?.name).toEqual("First");
+    expect(index.size).toEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// descendantSlugs / childrenOf
+// ---------------------------------------------------------------------------
+describe("descendantSlugs", () => {
+  it("collects the whole subtree, itself included", () => {
+    const categories = [
+      cat("root"),
+      cat("a", "root"),
+      cat("b", "root"),
+      cat("a1", "a"),
+      cat("other"),
+    ];
+
+    expect(descendantSlugs("root", categories).sort()).toEqual(["a", "a1", "b", "root"]);
+  });
+
+  it("stays finite over a cycle", () => {
+    const categories = [cat("a", "b"), cat("b", "a")];
+    expect(descendantSlugs("a", categories).sort()).toEqual(["a", "b"]);
+  });
+
+  it("of an unknown slug is just the slug", () => {
+    expect(descendantSlugs("ghost", [cat("root")])).toEqual(["ghost"]);
+  });
+});
+
+describe("childrenOf", () => {
+  it("returns direct children, name sorted", () => {
+    const categories = [
+      cat("root"),
+      cat("zeta", "root"),
+      cat("alpha", "root"),
+      cat("deep", "alpha"),
+    ];
+
+    expect(childrenOf("root", categories).map((c) => c.slug)).toEqual(["alpha", "zeta"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// withCategoryPath
+// ---------------------------------------------------------------------------
+describe("withCategoryPath", () => {
+  it("rewrites the requested path with the real chain", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+
+    // A request that reached the child through a flat path still gets the one
+    // canonical URL, so Google consolidates instead of seeing duplicates.
+    expect(
+      withCategoryPath("https://x.com/blog/leaf?page=2", chain, { requested: ["leaf"] }),
+    ).toEqual("https://x.com/blog/root/leaf");
+    expect(
+      withCategoryPath("https://x.com/blog/wrong/leaf", chain, { requested: ["wrong", "leaf"] }),
+    ).toEqual("https://x.com/blog/root/leaf");
+  });
+
+  it("declines when the slug isn't in the path", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+
+    // A listing hardcoded to a category on a plain /blog route: the pathname has
+    // no category segment, so rewriting it would strip the route prefix and
+    // point the canonical at a page that doesn't exist.
+    expect(withCategoryPath("https://x.com/blog", chain, { requested: ["leaf"] })).toEqual(null);
+    expect(withCategoryPath("https://x.com/blog/other", chain, { requested: ["leaf"] })).toEqual(
+      null,
+    );
+    expect(withCategoryPath("https://x.com/blog/leaf", chain, {})).toEqual(null);
+  });
+
+  it("keeps a trailing post slug", () => {
+    const chain = [cat("root"), cat("leaf", "root")];
+    const knownSlugs = new Set(["root", "leaf"]);
+
+    expect(
+      withCategoryPath("https://x.com/blog/leaf/my-post", chain, {
+        knownSlugs,
+        trailing: "my-post",
+      }),
+    ).toEqual("https://x.com/blog/root/leaf/my-post");
+    // A post route with no category segment keeps its own URL: injecting the
+    // chain would canonicalize to a path the site never serves.
+    expect(
+      withCategoryPath("https://x.com/blog/my-post", chain, { knownSlugs, trailing: "my-post" }),
+    ).toEqual(null);
+    // The categories collection failed to load, so nothing is a known slug —
+    // same outcome, rather than doubling the segment already in the path.
+    expect(
+      withCategoryPath("https://x.com/blog/leaf/my-post", chain, {
+        knownSlugs: new Set<string>(),
+        trailing: "my-post",
+      }),
+    ).toEqual(null);
+  });
+
+  it("keeps the route prefix when a category slug collides with it", () => {
+    // Category slugged "blog" on a /blog route. An unbounded strip of trailing
+    // known slugs would eat the prefix too and canonicalize to /blog/my-post,
+    // a path the site never serves.
+    const chain = [cat("blog")];
+
+    expect(
+      withCategoryPath("https://x.com/blog/blog/my-post", chain, {
+        knownSlugs: new Set(["blog"]),
+        trailing: "my-post",
+      }),
+    ).toEqual("https://x.com/blog/blog/my-post");
+  });
+
+  it("encodes each slug as one path segment", () => {
+    // Slugs are hand-authored; a stray "?" would otherwise turn the rest of the
+    // canonical into a query string pointing at a different page.
+    const chain = [cat("a?b"), cat("c/d", "a?b")];
+
+    expect(withCategoryPath("https://x.com/blog/leaf", chain, { requested: ["leaf"] })).toEqual(
+      "https://x.com/blog/a%3Fb/c%2Fd",
+    );
+  });
+
+  it("rewrites nothing with an empty chain", () => {
+    expect(withCategoryPath("https://x.com/blog/leaf?page=2", [], { requested: ["leaf"] })).toEqual(
+      null,
+    );
+  });
+});