@tribe-nest/forge 3.61.0 → 3.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.61.0",
+  "version": "3.64.0",
   "publishConfig": {
     "access": "public"
   },
@@ -10,6 +10,7 @@
     "./ui": "./src/ui/index.ts",
     "./ui/headless": "./src/ui/headless/index.ts",
     "./server": "./src/server/index.ts",
+    "./seo": "./src/seo/index.ts",
     "./media": "./src/ui/media/index.ts",
     "./forge-utilities.css": "./src/ui/styled/forge-utilities.css"
   },
@@ -41,7 +42,8 @@
     "react-hook-form": "^7.60.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
-    "socket.io-client": "^4.8.1"
+    "socket.io-client": "^4.8.1",
+    "web-vitals": "^6.2.2"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/index.ts

@@ -208,6 +208,9 @@ export * from "./utils/bookingSecret";
 // app can use them without inheriting the fan-site route tree, and so a fix
 // reaches existing sites through the normal Forge publish.
 export * from "./utils/headMeta";
+// SEO: seoHead per route, siteSeoHead in the root, applySeoToHead for hosted
+// pages. Also importable on its own from `@tribe-nest/forge/seo`.
+export * from "./seo";
 export * from "./utils/formatDateTime";
 // The ONE membership access predicate + the messaging that is deliberately
 // separate from it. Every surface that gates on a membership imports from here.

package/src/runtime/pages.ts

@@ -108,6 +108,8 @@ export const INTERNAL_PAGES = [
   "live",
   "live/$broadcastId",
   "login",
+  // SEO step 7, lane S2: a customer connects their assistant to the site MCP.
+  "oauth/authorize",
   "payment-link/$paymentLinkId",
   "payment-link/$paymentLinkId/finalise",
   "podcasts",

package/src/seo/_tests/seo.spec.ts

@@ -0,0 +1,522 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  applySeoToHead,
+  applyTitleTemplate,
+  findOverride,
+  isMarkdownPath,
+  isNotFoundContext,
+  markdownAlternateHref,
+  normalizePathname,
+  pathnameFromContext,
+  resolvePageSeo,
+  seoHead,
+  siteSeoHead,
+  type SeoHeadContext,
+  type SeoRecord,
+} from "../index";
+import { buildHeadMeta } from "../../utils/headMeta";
+
+const RECORD: SeoRecord = {
+  websiteId: "w1",
+  origin: "https://claystudio.com",
+  isDefaultWebsite: true,
+  defaultWebsiteOrigin: "https://claystudio.com",
+  siteName: "Clay Studio",
+  defaultDescription: "A small pottery studio in Hackney.",
+  defaultImage: "https://cdn.example/share.jpg",
+  titleTemplate: "{title} | {site}",
+  typeTemplates: {},
+  identity: {
+    kind: "local_business",
+    name: "Clay Studio",
+    logo: "https://cdn.example/logo.png",
+    sameAs: ["https://instagram.com/claystudio", "not a url"],
+    address: { street: "1 Mare St", locality: "London", postalCode: "E8 1AA", country: "GB" },
+    phone: "+44 20 0000 0000",
+  },
+  verification: { google: "g-token", bing: "b-token" },
+  indexing: true,
+  pages: {},
+  version: "2026-10-01T00:00:00.000Z",
+};
+
+const record = (patch: Partial<SeoRecord> = {}): SeoRecord => ({ ...RECORD, ...patch });
+
+/** The readable-copy link a page states beside its canonical. */
+const md = (url: string) => ({ rel: "alternate", type: "text/markdown", href: `${url}?md` });
+
+/** A head() context shaped like TanStack's: root match first, leaf last. */
+function ctx(pathname: string, seo: SeoRecord | null | undefined, fullPath = pathname): SeoHeadContext {
+  const leaf = { pathname, fullPath, routeId: fullPath, loaderData: {} };
+  return {
+    matches: [{ pathname: "/", fullPath: "/", routeId: "__root__", loaderData: { seo } }, leaf],
+    match: leaf,
+    params: {},
+  };
+}
+
+/** Title + every name/property entry, flattened for assertions. */
+function tags(meta: Record<string, unknown>[]) {
+  const out: Record<string, unknown> = {};
+  for (const m of meta) {
+    if (typeof m.title === "string") out.title = m.title;
+    const key = (m.name ?? m.property) as string | undefined;
+    if (key) out[key] = m.content;
+  }
+  return out;
+}
+const jsonLd = (meta: Record<string, unknown>[]) =>
+  meta.filter((m) => "script:ld+json" in m).map((m) => m["script:ld+json"] as Record<string, unknown>);
+
+describe("normalizePathname", () => {
+  it("treats a trailing slash, a query and a missing slash as the same page", () => {
+    expect(normalizePathname("/about/")).toBe("/about");
+    expect(normalizePathname("/about?x=1")).toBe("/about");
+    expect(normalizePathname("about")).toBe("/about");
+    expect(normalizePathname("/")).toBe("/");
+    expect(normalizePathname("")).toBe("/");
+  });
+});
+
+describe("applyTitleTemplate", () => {
+  it("applies the template", () => {
+    expect(applyTitleTemplate("About", "Clay Studio", "{title} | {site}")).toBe("About | Clay Studio");
+  });
+  it("accepts {site.name} as well as {site}", () => {
+    expect(applyTitleTemplate("About", "Clay Studio", "{site.name}: {title}")).toBe("Clay Studio: About");
+  });
+  it("skips the template when the title already names the site, in any case", () => {
+    expect(applyTitleTemplate("clay studio, Hackney", "Clay Studio", "{title} | {site}")).toBe("clay studio, Hackney");
+  });
+  it("falls back to the default template when the record's is blank", () => {
+    expect(applyTitleTemplate("About", "Clay Studio", "  ")).toBe("About | Clay Studio");
+  });
+});
+
+describe("a stored title template without {title}", () => {
+  it("is ignored for the default rather than printed", () => {
+    expect(applyTitleTemplate("About", "Clay Studio", "%s | Clay Studio")).toBe("About | Clay Studio");
+    expect(applyTitleTemplate("About", "Clay Studio", "Clay Studio")).toBe("About | Clay Studio");
+    // A usable one still applies, with either site placeholder.
+    expect(applyTitleTemplate("About", "Clay Studio", "{site.name}: {title}")).toBe("Clay Studio: About");
+  });
+
+  it("on the site falls back to the default, and on a page type falls back to the site's", () => {
+    const broken = resolvePageSeo(record({ titleTemplate: "%s | Clay Studio" }), { pathname: "/about", title: "About" });
+    expect(broken.title).toBe("About | Clay Studio");
+
+    const seo = record({ titleTemplate: "{title} - {site}", typeTemplates: { product: { title: "Shop" } } });
+    expect(resolvePageSeo(seo, { pathname: "/i/store/mug", type: "product", title: "Mug" }).title).toBe("Mug - Clay Studio");
+    const good = record({ typeTemplates: { product: { title: "{title} | Shop | {site}" } } });
+    expect(resolvePageSeo(good, { pathname: "/i/store/mug", type: "product", title: "Mug" }).title).toBe("Mug | Shop | Clay Studio");
+  });
+
+  it("never reaches a page's document title through seoHead", () => {
+    const t = tags(seoHead(ctx("/about", record({ titleTemplate: "%s | Clay Studio" })), { title: "About" }).meta);
+    expect(t.title).toBe("About | Clay Studio");
+    expect(t.title).not.toContain("%s");
+  });
+});
+
+describe("findOverride", () => {
+  it("prefers the exact pathname and fills gaps from the route pattern", () => {
+    const seo = record({
+      pages: {
+        "/team/ada": { title: "Ada, head potter" },
+        "/team/$slug": { title: "Team member", description: "Pattern description", noindex: true },
+      },
+    });
+    expect(findOverride(seo, "/team/ada/", "/team/$slug")).toEqual({
+      title: "Ada, head potter",
+      description: "Pattern description",
+      noindex: true,
+    });
+  });
+
+  it("ignores blank strings so an emptied field does not erase the code's value", () => {
+    const seo = record({ pages: { "/about": { title: "  ", description: null } } });
+    expect(findOverride(seo, "/about")).toEqual({});
+  });
+});
+
+describe("resolvePageSeo", () => {
+  it("with no record, behaves exactly like the code's own values", () => {
+    expect(resolvePageSeo(null, { pathname: "/about", title: "About" })).toEqual({
+      title: "About",
+      shareTitle: "About",
+      description: "About",
+      image: undefined,
+      noindex: false,
+      canonical: null,
+      overridden: false,
+    });
+  });
+
+  it("uses a type template over the site template, and its description when the code has none", () => {
+    const seo = record({
+      typeTemplates: { event: { title: "{title} tickets | {site}", description: "Book {title} at {site}." } },
+    });
+    const r = resolvePageSeo(seo, { pathname: "/i/events/gig", title: "Late Show", type: "event", entity: true });
+    expect(r.title).toBe("Late Show tickets | Clay Studio");
+    expect(r.shareTitle).toBe("Late Show");
+    expect(r.description).toBe("Book Late Show at Clay Studio.");
+  });
+
+  it("falls back to site defaults for description and image", () => {
+    const r = resolvePageSeo(record(), { pathname: "/about", title: "About" });
+    expect(r.description).toBe(RECORD.defaultDescription);
+    expect(r.image).toBe(RECORD.defaultImage);
+  });
+
+  it("canonicalizes entities to the default website and pages to their own origin", () => {
+    const seo = record({ origin: "https://shop.example", defaultWebsiteOrigin: "https://claystudio.com" });
+    expect(resolvePageSeo(seo, { pathname: "/i/store/mug", title: "Mug", entity: true }).canonical).toBe(
+      "https://claystudio.com/i/store/mug",
+    );
+    expect(resolvePageSeo(seo, { pathname: "/about", title: "About" }).canonical).toBe("https://shop.example/about");
+  });
+
+  it("noindexes everything when the site is not indexing, whatever the code says", () => {
+    expect(resolvePageSeo(record({ indexing: false }), { pathname: "/", title: "Home" }).noindex).toBe(true);
+  });
+
+  it("lets an override's noindex:false beat the code's noindex", () => {
+    const seo = record({ pages: { "/thanks": { noindex: false } } });
+    expect(resolvePageSeo(seo, { pathname: "/thanks", title: "Thanks", noindex: true }).noindex).toBe(false);
+  });
+});
+
+describe("seoHead", () => {
+  it("with no record, emits today's buildHeadMeta tags and never links", () => {
+    const out = seoHead(ctx("/about", undefined), { title: "About", description: "Who we are", image: "https://x/i.jpg" });
+    expect(out).not.toHaveProperty("links");
+    const legacy = buildHeadMeta({ title: "About", description: "Who we are", image: "https://x/i.jpg" });
+    expect(tags(out.meta)).toEqual(tags(legacy.meta));
+  });
+
+  it("applies the title template to the code title", () => {
+    const out = seoHead(ctx("/about", RECORD), { title: "About", description: "Who we are" });
+    const t = tags(out.meta);
+    expect(t.title).toBe("About | Clay Studio");
+    expect(t["og:title"]).toBe("About");
+    expect(t.description).toBe("Who we are");
+    expect(t["og:url"]).toBe("https://claystudio.com/about");
+    expect(t.robots).toBeUndefined();
+  });
+
+  it("uses an override for the exact pathname, verbatim", () => {
+    const seo = record({ pages: { "/about": { title: "Our story", description: "Since 2019." } } });
+    const t = tags(seoHead(ctx("/about", seo), { title: "About", description: "Who we are" }).meta);
+    expect(t.title).toBe("Our story");
+    expect(t.description).toBe("Since 2019.");
+  });
+
+  it("uses an override keyed by the route pattern for a dynamic route", () => {
+    const seo = record({ pages: { "/team/$slug": { description: "One of our potters." } } });
+    const t = tags(seoHead(ctx("/team/ada", seo, "/team/$slug"), { title: "Ada" }).meta);
+    expect(t.title).toBe("Ada | Clay Studio");
+    expect(t.description).toBe("One of our potters.");
+  });
+
+  it("emits robots noindex from the code, from an override, and from a non-indexing site", () => {
+    expect(tags(seoHead(ctx("/x", RECORD), { title: "X", noindex: true }).meta).robots).toBe("noindex, nofollow");
+    const seo = record({ pages: { "/x": { noindex: true } } });
+    expect(tags(seoHead(ctx("/x", seo), { title: "X" }).meta).robots).toBe("noindex, nofollow");
+    expect(tags(seoHead(ctx("/x", record({ indexing: false })), { title: "X" }).meta).robots).toBe("noindex, nofollow");
+  });
+
+  it("emits each jsonLd node as a script:ld+json meta entry", () => {
+    const nodes = [{ "@type": "Thing", name: "a" }, { "@type": "Thing", name: "b" }];
+    expect(jsonLd(seoHead(ctx("/x", RECORD), { title: "X", jsonLd: nodes }).meta)).toEqual(nodes);
+    expect(jsonLd(seoHead(ctx("/x", RECORD), { title: "X", jsonLd: nodes[0] }).meta)).toEqual([nodes[0]]);
+  });
+});
+
+describe("siteSeoHead", () => {
+  it("emits the site fallbacks, verification and a canonical for the leaf path", () => {
+    const out = siteSeoHead(ctx("/about/", RECORD));
+    const t = tags(out.meta);
+    expect(t).toMatchObject({
+      title: "Clay Studio",
+      description: RECORD.defaultDescription,
+      "og:site_name": "Clay Studio",
+      "og:image": RECORD.defaultImage,
+      "twitter:card": "summary_large_image",
+      "google-site-verification": "g-token",
+      "msvalidate.01": "b-token",
+    });
+    expect(t.robots).toBeUndefined();
+    expect(out.links).toEqual([
+      { rel: "canonical", href: "https://claystudio.com/about" },
+      md("https://claystudio.com/about"),
+    ]);
+  });
+
+  it("uses an override canonical", () => {
+    const seo = record({ pages: { "/about": { canonical: "https://claystudio.com/story" } } });
+    expect(siteSeoHead(ctx("/about", seo)).links).toEqual([
+      { rel: "canonical", href: "https://claystudio.com/story" },
+      md("https://claystudio.com/story"),
+    ]);
+  });
+
+  it("emits no canonical under /i/, where the hosted page emits its own", () => {
+    expect(siteSeoHead(ctx("/i/store/mug", RECORD)).links).toEqual([]);
+    expect(siteSeoHead(ctx("/i", RECORD)).links).toEqual([]);
+    // A creator page that merely starts with "i" is not hosted.
+    expect(siteSeoHead(ctx("/ideas", RECORD)).links).toHaveLength(2);
+  });
+
+  it("noindexes when the site is not indexing or the path's override says so", () => {
+    expect(tags(siteSeoHead(ctx("/", record({ indexing: false }))).meta).robots).toBe("noindex, nofollow");
+    const seo = record({ pages: { "/team/$slug": { noindex: true } } });
+    expect(tags(siteSeoHead(ctx("/team/ada", seo, "/team/$slug")).meta).robots).toBe("noindex, nofollow");
+  });
+
+  it("emits WebSite and identity JSON-LD on / only", () => {
+    const home = jsonLd(siteSeoHead(ctx("/", RECORD)).meta);
+    expect(home.map((n) => n["@type"])).toEqual(["WebSite", "LocalBusiness"]);
+    expect(home[0]).toMatchObject({
+      name: "Clay Studio",
+      url: "https://claystudio.com/",
+      publisher: { "@id": "https://claystudio.com/#identity" },
+    });
+    expect(home[1]).toMatchObject({
+      "@id": "https://claystudio.com/#identity",
+      telephone: "+44 20 0000 0000",
+      sameAs: ["https://instagram.com/claystudio"],
+      address: { "@type": "PostalAddress", streetAddress: "1 Mare St", addressCountry: "GB" },
+    });
+    expect(jsonLd(siteSeoHead(ctx("/about", RECORD)).meta)).toEqual([]);
+  });
+
+  it("emits WebSite alone when there is no identity", () => {
+    const home = jsonLd(siteSeoHead(ctx("/", record({ identity: null }))).meta);
+    expect(home).toHaveLength(1);
+    expect(home[0]).not.toHaveProperty("publisher");
+  });
+
+  it("with no record, emits only the fallback it was given and no canonical", () => {
+    const out = siteSeoHead(ctx("/about", null), { siteName: "Clay" });
+    expect(out.links).toEqual([]);
+    expect(tags(out.meta)).toEqual({ title: "Clay", "og:site_name": "Clay", "twitter:card": "summary_large_image" });
+    expect(tags(siteSeoHead(ctx("/", undefined)).meta)).toEqual({ "twitter:card": "summary_large_image" });
+  });
+});
+
+/**
+ * A not-found render, shaped as TanStack builds it.
+ *
+ * A URL no route matches leaves ONLY the root match, at "/", marked
+ * `_notFound`. A route whose loader threw `notFound()` keeps its own match with
+ * `status: "notFound"`, and the boundary above it carries `_notFound`.
+ */
+function globalNotFoundCtx(seo: SeoRecord | null | undefined): SeoHeadContext {
+  const root = { pathname: "/", fullPath: "/", routeId: "__root__", loaderData: { seo }, _notFound: true, status: "success" };
+  return { matches: [root], match: root, params: {} };
+}
+function thrownNotFoundCtx(pathname: string, seo: SeoRecord | null | undefined, fullPath = pathname): SeoHeadContext {
+  const leaf = { pathname, fullPath, routeId: fullPath, loaderData: undefined, status: "notFound", _notFound: true };
+  return {
+    matches: [{ pathname: "/", fullPath: "/", routeId: "__root__", loaderData: { seo }, status: "success" }, leaf],
+    match: leaf,
+    params: {},
+  };
+}
+
+describe("a not-found render", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("is recognised from either TanStack marker, and a normal render is not", () => {
+    expect(isNotFoundContext(globalNotFoundCtx(RECORD))).toBe(true);
+    expect(isNotFoundContext(thrownNotFoundCtx("/blog/gone", RECORD))).toBe(true);
+    expect(isNotFoundContext(ctx("/", RECORD))).toBe(false);
+    expect(isNotFoundContext(ctx("/about", RECORD))).toBe(false);
+    expect(isNotFoundContext(undefined)).toBe(false);
+  });
+
+  it("reads its pathname from the location, not the root match's \"/\"", () => {
+    vi.stubGlobal("location", { pathname: "/no-such-page/" });
+    expect(pathnameFromContext(globalNotFoundCtx(RECORD))).toBe("/no-such-page");
+    // A page that exists keeps its leaf, whatever the location says.
+    expect(pathnameFromContext(ctx("/about", RECORD))).toBe("/about");
+  });
+
+  it("on an unmatched URL states no canonical, no Markdown copy and no site JSON-LD, and is noindex", () => {
+    const out = siteSeoHead(globalNotFoundCtx(RECORD));
+    expect(out.links).toEqual([]);
+    expect(jsonLd(out.meta)).toEqual([]);
+    const t = tags(out.meta);
+    expect(t.robots).toBe("noindex, nofollow");
+    // The site-wide fallbacks still hold, so the page is not bare.
+    expect(t.title).toBe("Clay Studio");
+    expect(t["og:site_name"]).toBe("Clay Studio");
+    expect(t["google-site-verification"]).toBe("g-token");
+  });
+
+  it("does the same in the browser, where the location is known", () => {
+    vi.stubGlobal("location", { pathname: "/no-such-page" });
+    const out = siteSeoHead(globalNotFoundCtx(RECORD));
+    expect(out.links).toEqual([]);
+    expect(jsonLd(out.meta)).toEqual([]);
+    expect(tags(out.meta).robots).toBe("noindex, nofollow");
+  });
+
+  it("ignores an override for \"/\" that would otherwise apply to the root match", () => {
+    const seo = record({ pages: { "/": { canonical: "https://claystudio.com/home" } } });
+    expect(siteSeoHead(globalNotFoundCtx(seo)).links).toEqual([]);
+  });
+
+  it("when a loader threw notFound(), the root and the page both say noindex and state no URL", () => {
+    const root = siteSeoHead(thrownNotFoundCtx("/blog/gone", RECORD, "/blog/$slug"));
+    expect(root.links).toEqual([]);
+    expect(tags(root.meta).robots).toBe("noindex, nofollow");
+
+    const page = seoHead(thrownNotFoundCtx("/blog/gone", RECORD, "/blog/$slug"), {
+      title: "Gone",
+      jsonLd: { "@type": "BlogPosting" },
+    });
+    const t = tags(page.meta);
+    expect(t.robots).toBe("noindex, nofollow");
+    expect(t["og:url"]).toBeUndefined();
+    expect(jsonLd(page.meta)).toEqual([]);
+  });
+
+  it("leaves the home page exactly as it was", () => {
+    const home = siteSeoHead(ctx("/", RECORD));
+    expect(home.links[0]).toEqual({ rel: "canonical", href: "https://claystudio.com/" });
+    expect(jsonLd(home.meta).map((n) => n["@type"])).toEqual(["WebSite", "LocalBusiness"]);
+    expect(tags(home.meta).robots).toBeUndefined();
+  });
+});
+
+describe("applySeoToHead", () => {
+  const productHead = () => ({
+    ...buildHeadMeta({ title: "Mug", description: "A mug.", image: "https://cdn.example/mug.jpg", ogType: "product" }),
+    scripts: [{ type: "application/ld+json", children: "{}" }],
+  });
+
+  it("returns the head untouched with no record", () => {
+    const head = productHead();
+    expect(applySeoToHead(head, null, "/i/store/mug", "product")).toBe(head);
+  });
+
+  it("templates the title, keeps the page's own tags and adds the entity canonical", () => {
+    const seo = record({ origin: "https://shop.example", defaultWebsiteOrigin: "https://claystudio.com" });
+    const out = applySeoToHead(productHead(), seo, "/i/store/mug", "product", "/i/store/$slug");
+    const t = tags(out.meta!);
+    expect(t.title).toBe("Mug | Clay Studio");
+    expect(t["og:title"]).toBe("Mug");
+    expect(t["og:type"]).toBe("product");
+    expect(t["og:site_name"]).toBe("Clay Studio");
+    expect(t["og:url"]).toBe("https://claystudio.com/i/store/mug");
+    expect(out.links).toEqual([
+      { rel: "canonical", href: "https://claystudio.com/i/store/mug" },
+      md("https://claystudio.com/i/store/mug"),
+    ]);
+    expect(out.scripts).toEqual([{ type: "application/ld+json", children: "{}" }]);
+    // Exactly one of each: the old entries were replaced, not appended to.
+    expect(out.meta!.filter((m) => m.name === "description")).toHaveLength(1);
+    expect(out.meta!.filter((m) => typeof m.title === "string")).toHaveLength(1);
+  });
+
+  it("canonicalizes an index page to its own website", () => {
+    const seo = record({ origin: "https://shop.example", defaultWebsiteOrigin: "https://claystudio.com" });
+    const out = applySeoToHead(buildHeadMeta({ title: "Store" }), seo, "/i/store", "page");
+    expect(out.links).toEqual([{ rel: "canonical", href: "https://shop.example/i/store" }, md("https://shop.example/i/store")]);
+  });
+
+  it("applies overrides by pathname and by pattern", () => {
+    const seo = record({
+      pages: {
+        "/i/store/mug": { title: "The best mug" },
+        "/i/store/$slug": { description: "Handmade in Hackney.", image: "https://cdn.example/o.jpg" },
+      },
+    });
+    const t = tags(applySeoToHead(productHead(), seo, "/i/store/mug", "product", "/i/store/$slug").meta!);
+    expect(t.title).toBe("The best mug");
+    expect(t.description).toBe("Handmade in Hackney.");
+    expect(t["og:image"]).toBe("https://cdn.example/o.jpg");
+    expect(t["twitter:image"]).toBe("https://cdn.example/o.jpg");
+  });
+
+  it("does not let buildHeadMeta's title-as-description beat the site default", () => {
+    const t = tags(applySeoToHead(buildHeadMeta({ title: "Events" }), RECORD, "/i/events", "page").meta!);
+    expect(t.description).toBe(RECORD.defaultDescription);
+  });
+
+  it("keeps a page's noindex and then states no canonical", () => {
+    const out = applySeoToHead(buildHeadMeta({ title: "Login", noindex: true }), RECORD, "/i/login", "page");
+    expect(tags(out.meta!).robots).toBe("noindex, nofollow");
+    expect(out.links).toEqual([]);
+  });
+});
+
+describe("Markdown alternate (section 5.4)", () => {
+  /** The same table as apps/dispatch-worker/src/_tests/markdown.spec.ts: the two rules must agree. */
+  it.each([
+    ["/", true],
+    ["/about", true],
+    ["/team/ada/", true],
+    ["/i/store", true],
+    ["/i/store/mug", true],
+    ["/i/events/launch-night", true],
+    ["/i/podcasts/show/episode-1", true],
+    ["/i/communities/potters", true],
+    ["/i/store/mug/extra", false],
+    ["/i/events/launch-night/finalise", false],
+    ["/i/films/library", false],
+    ["/i/films/doc/watch/e1", false],
+    ["/i/account", false],
+    ["/i/account/orders", false],
+    ["/i/checkout", false],
+    ["/i/login", false],
+    ["/i/downloads/tok", false],
+    ["/i/app", false],
+    ["/i", false],
+    ["/api/things", false],
+    ["/__tn/unlock", false],
+    ["/.well-known/mcp", false],
+    ["/logo.png", false],
+    ["/sitemap.xml", false],
+  ])("isMarkdownPath(%s) is %s", (path, expected) => {
+    expect(isMarkdownPath(path)).toBe(expected);
+  });
+
+  it("is left out when readable copies are off, the page is noindex or the site is not indexing", () => {
+    const off = (seo: SeoRecord, path = "/about") =>
+      (siteSeoHead(ctx(path, seo)).links as Array<{ rel: string }>).filter((l) => l.rel === "alternate");
+    expect(off(record({ markdownEnabled: false }))).toEqual([]);
+    expect(off(record({ indexing: false }))).toEqual([]);
+    expect(off(record({ pages: { "/about": { noindex: true } } }))).toEqual([]);
+    // Absent means on: an API older than the field.
+    expect(off(record({ markdownEnabled: undefined }))).toHaveLength(1);
+  });
+
+  it("is left out of a hosted page that is noindex or private", () => {
+    const head = buildHeadMeta({ title: "Orders" });
+    expect(applySeoToHead(head, RECORD, "/i/account/orders").links).toEqual([
+      { rel: "canonical", href: "https://claystudio.com/i/account/orders" },
+    ]);
+    const off = applySeoToHead(buildHeadMeta({ title: "Mug" }), record({ markdownEnabled: false }), "/i/store/mug", "product");
+    expect(off.links).toEqual([{ rel: "canonical", href: "https://claystudio.com/i/store/mug" }]);
+  });
+
+  it("replaces a markdown link the page already had rather than adding a second", () => {
+    const head = { ...buildHeadMeta({ title: "Mug" }), links: [{ rel: "alternate", type: "text/markdown", href: "/old" }] };
+    const out = applySeoToHead(head, RECORD, "/i/store/mug", "product");
+    expect(out.links!.filter((l) => l.rel === "alternate")).toEqual([md("https://claystudio.com/i/store/mug")]);
+  });
+
+  it("points at this site when the canonical is somewhere else, and appends to a canonical with a query", () => {
+    expect(markdownAlternateHref(RECORD, "/about", "https://elsewhere.example/about")).toBe(
+      "https://claystudio.com/about?md",
+    );
+    expect(markdownAlternateHref(RECORD, "/about", "https://claystudio.com/about?lang=en")).toBe(
+      "https://claystudio.com/about?lang=en&md",
+    );
+    expect(markdownAlternateHref(RECORD, "/", null)).toBe("https://claystudio.com/?md");
+  });
+});

package/src/seo/applySeoToHead.ts

@@ -0,0 +1,104 @@
+import { markdownAlternateLink } from "./markdown";
+import { normalizePathname, resolvePageSeo } from "./resolve";
+import type { SeoPageType, SeoRecord } from "./types";
+
+type HeadEntry = Record<string, string | undefined>;
+
+/** The `{ meta, links, scripts }` shape a hosted page's `head()` returns. */
+export type HeadTags = {
+  meta?: HeadEntry[];
+  links?: HeadEntry[];
+  scripts?: HeadEntry[];
+};
+
+/**
+ * Meta this function owns and rewrites. Anything else a page set (`og:type`,
+ * `og:video`, a custom tag) passes through untouched.
+ */
+const OWNED_META = new Set([
+  "description",
+  "robots",
+  "og:title",
+  "og:description",
+  "og:image",
+  "og:url",
+  "og:site_name",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+]);
+
+const metaKey = (m: HeadEntry) => m.name ?? m.property;
+
+/**
+ * Resolve the SEO record over a hosted `/i/` page's own head.
+ *
+ * The page's `head()` says what its code defaults are (title, description,
+ * image, noindex), exactly as before. This applies, on top of them, the
+ * creator's override for the pathname or pattern, the page type's template,
+ * the site defaults and the canonical.
+ *
+ * The canonical is emitted HERE, not by the site's root, because only the page
+ * knows it is an entity: a product, event or post canonicalizes to the
+ * profile's DEFAULT website (`defaultWebsiteOrigin`), so the same product shown
+ * on three websites is one result, not three. An index page (`/i/store`)
+ * belongs to the website it is on.
+ *
+ * With no record, the head is returned unchanged.
+ */
+export function applySeoToHead<T extends HeadTags>(
+  head: T,
+  seo: SeoRecord | null | undefined,
+  pathname: string,
+  type: SeoPageType = "page",
+  routePattern?: string,
+): T {
+  if (!seo) return head;
+
+  const meta = head.meta ?? [];
+  const find = (key: string) => meta.find((m) => metaKey(m) === key)?.content;
+  const codeTitle = meta.find((m) => typeof m.title === "string")?.title ?? "";
+  const codeNoindex = /noindex/i.test(find("robots") ?? "");
+
+  const path = normalizePathname(pathname);
+  const resolved = resolvePageSeo(seo, {
+    pathname: path,
+    routePattern,
+    type,
+    title: codeTitle,
+    // `buildHeadMeta` falls back to the title when a page has no description.
+    // That fallback is not a description the code chose, so it must not beat
+    // the type template or the site default.
+    description: find("description") && find("description") !== codeTitle ? find("description") : undefined,
+    image: find("og:image"),
+    noindex: codeNoindex,
+    entity: type !== "page",
+  });
+
+  const kept = meta.filter((m) => typeof m.title !== "string" && !OWNED_META.has(metaKey(m) ?? ""));
+  const nextMeta: HeadEntry[] = [
+    { title: resolved.title },
+    { name: "description", content: resolved.description },
+    { property: "og:title", content: resolved.shareTitle },
+    { property: "og:description", content: resolved.description },
+    { property: "og:site_name", content: seo.siteName },
+    ...(resolved.canonical && !resolved.noindex ? [{ property: "og:url", content: resolved.canonical }] : []),
+    ...(resolved.image ? [{ property: "og:image", content: resolved.image }] : []),
+    ...kept,
+    { name: "twitter:title", content: resolved.shareTitle },
+    { name: "twitter:description", content: resolved.description },
+    ...(resolved.image ? [{ name: "twitter:image", content: resolved.image }] : []),
+    ...(resolved.noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
+  ];
+
+  // A noindex page states no canonical: there is no indexed copy to point at.
+  const links = (head.links ?? []).filter(
+    (l) => l.rel !== "canonical" && !(l.rel === "alternate" && l.type === "text/markdown"),
+  );
+  if (resolved.canonical && !resolved.noindex) links.push({ rel: "canonical", href: resolved.canonical });
+  // The readable copy for agents, on the same terms as the canonical.
+  const markdown = markdownAlternateLink(seo, path, { canonical: resolved.canonical, noindex: resolved.noindex });
+  if (markdown) links.push({ ...markdown });
+
+  return { ...head, meta: nextMeta, links };
+}