@tribe-nest/forge 3.60.0 → 3.63.0

package/src/index.ts

@@ -138,12 +138,16 @@ export * from "./data/queries/useEngagement";
 export * from "./data/queries/usePaymentFlow";
 export * from "./data/queries/useOrders";
 export * from "./data/queries/useAuthActions";
+// Email-first sign-in (`/public/sessions/email/*`): start, verify, complete.
+export * from "./data/queries/useEmailSignIn";
 export * from "./data/queries/useCoupons";
 export * from "./data/queries/useAccountSettings";
 export * from "./data/queries/useDonations";
 export * from "./data/queries/useOffers";
 export * from "./data/queries/useShipping";
 export * from "./data/queries/useWebsite";
+// The site app's settings for this host, and the Home rule (`useAppHomeHref`).
+export * from "./data/queries/useSiteApp";
 export * from "./data/queries/useWebsiteAgent";
 export * from "./data/queries/useCurrencies";
 export * from "./data/queries/useChat";
@@ -151,6 +155,18 @@ export * from "./data/queries/useCallChat";
 export * from "./data/queries/useCallBreakouts";
 export * from "./data/queries/useAnalytics";
 export * from "./data/queries/useCommunity";
+// The community AI on the member side: its info, DM, thumbs, "catch me up".
+export * from "./data/queries/useCommunityAgent";
+// Moderation from the site: the queue, the log, and the moderator actions.
+export * from "./data/queries/useCommunityModeration";
+// The community wiki as members and visitors read it.
+export * from "./data/queries/useCommunityWiki";
+// The member directory and map.
+export * from "./data/queries/useCommunityMembers";
+// The classroom tab: the courses a community's tiers include.
+export * from "./data/queries/useCommunityClassroom";
+// The community calendar: calls, promoted events and going / not going.
+export * from "./data/queries/useCommunityCalendar";
 // Communities: the list, one community, the viewer's state in it, invites,
 // upgrades and the fan's memberships across communities.
 export * from "./data/queries/useCommunities";
@@ -176,6 +192,7 @@ export * from "./content";
 export * from "./utils/attribution";
 export * from "./utils/landing";
 export * from "./utils/metaPixel";
+export * from "./utils/metaEvents";
 export * from "./utils/cookieConsent";
 export * from "./utils/structuredData";
 // Paystack inline checkout: the ONE implementation of the popup, exported so a
@@ -191,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.spec.ts

@@ -47,15 +47,20 @@ describe("internal page links", () => {
       "communities/$slug/home",
       "communities/$slug/home/calendar",
       "communities/$slug/home/chat",
+      "communities/$slug/home/classroom",
       "communities/$slug/home/collections",
       "communities/$slug/home/collections/$collectionId",
       "communities/$slug/home/leaderboard",
+      "communities/$slug/home/members",
+      "communities/$slug/home/moderation",
       "communities/$slug/home/notifications",
       "communities/$slug/home/posts",
       "communities/$slug/home/profile/$accountId",
       "communities/$slug/home/spaces",
       "communities/$slug/home/spaces/$spaceId",
       "communities/$slug/home/spaces/posts/$postId",
+      "communities/$slug/home/wiki",
+      "communities/$slug/home/wiki/$page",
     ]);
     const removed = INTERNAL_PAGES.filter((page) => /^(membership|members|community|chat)(\/|$)/.test(page));
     expect(removed).toEqual([]);

package/src/runtime/pages.ts

@@ -9,12 +9,16 @@
  *
  * The page list is the CONTRACT between a site and the hosted pages, so it
  * normally only grows: removing a page breaks links on sites already published.
- * The one deliberate exception is Communities (2026-09-27). A profile can now
+ * The first deliberate exception is Communities (2026-09-27). A profile can now
  * run several communities, so the single-community member pages (`membership`,
  * `members/*`, `community/*`, `chat`) were removed with no redirects, because
  * nobody used them yet and there is no one community they could redirect to.
  * Every member page now lives under `communities/$slug`.
  *
+ * The second is the client portal (2026-10-01). `work/*` and the `?tab=` form
+ * of `account` folded into one portal under `account/*`, with no redirects:
+ * every producer of those links moved in the same change.
+ *
  *     <Link {...internalLink("store/$slug", { slug: product.slug })}>Buy</Link>
  *     navigate(internalLink("checkout"))
  *     const href = internalPath("events/$slug", { slug });
@@ -29,6 +33,27 @@ export const INTERNAL_ROUTE = "/i/$" as const;
 /** Every hosted page, by its path pattern. Generated from the route table. */
 export const INTERNAL_PAGES = [
   "account",
+  "account/activity",
+  "account/bookings",
+  "account/courses",
+  "account/documents",
+  "account/files",
+  "account/films",
+  "account/invite",
+  "account/invoices",
+  "account/memberships",
+  "account/messages",
+  "account/notifications",
+  "account/orders",
+  "account/projects",
+  "account/projects/$projectId",
+  "account/projects/$projectId/tasks/$taskId",
+  "account/saved",
+  "account/settings",
+  "account/tickets",
+  "account/time-report/$token",
+  "account/waitlist",
+  "app",
   "blog",
   "blog-category/$slug",
   "blog/$slug",
@@ -45,15 +70,20 @@ export const INTERNAL_PAGES = [
   "communities/$slug/home",
   "communities/$slug/home/calendar",
   "communities/$slug/home/chat",
+  "communities/$slug/home/classroom",
   "communities/$slug/home/collections",
   "communities/$slug/home/collections/$collectionId",
   "communities/$slug/home/leaderboard",
+  "communities/$slug/home/members",
+  "communities/$slug/home/moderation",
   "communities/$slug/home/notifications",
   "communities/$slug/home/posts",
   "communities/$slug/home/profile/$accountId",
   "communities/$slug/home/spaces",
   "communities/$slug/home/spaces/$spaceId",
   "communities/$slug/home/spaces/posts/$postId",
+  "communities/$slug/home/wiki",
+  "communities/$slug/home/wiki/$page",
   "confirm-subscription",
   "course-access/$accessId",
   "courses",
@@ -62,6 +92,7 @@ export const INTERNAL_PAGES = [
   "courses/claim",
   "documents/$token",
   "donation",
+  "downloads/$token",
   "events",
   "events/$slug",
   "events/$slug/finalise",
@@ -91,11 +122,6 @@ export const INTERNAL_PAGES = [
   "store/$slug",
   "tickets/claim",
   "video-calls/$callId",
-  "work",
-  "work/accept-invite",
-  "work/projects/$projectId",
-  "work/projects/$projectId/tasks/$taskId",
-  "work/time-report/$token",
 ] as const;
 
 export type InternalPage = (typeof INTERNAL_PAGES)[number];

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

@@ -0,0 +1,326 @@
+import { describe, expect, it } from "vitest";
+import {
+  applySeoToHead,
+  applyTitleTemplate,
+  findOverride,
+  normalizePathname,
+  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 });
+
+/** 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("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" }]);
+  });
+
+  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" }]);
+  });
+
+  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(1);
+  });
+
+  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" });
+  });
+});
+
+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" }]);
+    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" }]);
+  });
+
+  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([]);
+  });
+});

package/src/seo/applySeoToHead.ts

@@ -0,0 +1,98 @@
+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");
+  if (resolved.canonical && !resolved.noindex) links.push({ rel: "canonical", href: resolved.canonical });
+
+  return { ...head, meta: nextMeta, links };
+}

package/src/seo/index.ts

@@ -0,0 +1,9 @@
+// SEO for code sites and hosted pages: code declares the defaults, the
+// creator's approved edits live in the SEO record, and these functions resolve
+// one over the other. Pure, React-free, so it is safe on the server entry and in
+// a route's head().
+export * from "./types";
+export * from "./resolve";
+export * from "./seoHead";
+export * from "./siteSeoHead";
+export * from "./applySeoToHead";