@tribe-nest/forge 3.61.0 → 3.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.61.0",
+  "version": "3.63.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/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";