@tribe-nest/forge 3.61.0 → 3.64.0

package/src/seo/index.ts

@@ -0,0 +1,10 @@
+// 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";
+export * from "./markdown";

package/src/seo/markdown.ts

@@ -0,0 +1,76 @@
+import { normalizePathname } from "./resolve";
+import type { SeoLinkEntry, SeoRecord } from "./types";
+
+/**
+ * Readable copies for agents (docs/proposals/seo-initiative.md, section 5.4).
+ *
+ * The edge answers `Accept: text/markdown` or `?md` on a page with Markdown.
+ * These helpers decide which pages have such a copy, so a page only ever
+ * advertises one the edge will actually serve.
+ *
+ * KEEP IN STEP with `isMarkdownPath` in apps/dispatch-worker/src/markdown.ts.
+ * The dispatch Worker does not depend on Forge, so the rule is written twice;
+ * both specs run the same table of paths.
+ */
+
+/** Hosted families with a public page per item. Everything else under /i/ is private or transactional. */
+export const MARKDOWN_HOSTED_FAMILIES = [
+  "store",
+  "events",
+  "courses",
+  "coaching",
+  "blog",
+  "blog-category",
+  "podcasts",
+  "films",
+  "series",
+  "communities",
+] as const;
+
+/** Segments that mark a step in a flow, not a page about something. */
+const FLOW_SEGMENTS = new Set(["finalise", "library", "claim", "watch"]);
+
+/** Whether the edge serves a Markdown copy of this path. */
+export function isMarkdownPath(pathname: string): boolean {
+  const path = normalizePathname(pathname);
+  if (path.startsWith("/api/") || path.startsWith("/__tn/") || path.startsWith("/.well-known/")) return false;
+  const segments = path.split("/").filter(Boolean);
+  // A file, not a page: `/logo.png`, `/sw.js`, `/robots.txt`.
+  const last = segments[segments.length - 1] ?? "";
+  if (last.includes(".")) return false;
+  if (segments[0] !== "i") return true;
+
+  const [, family, ...rest] = segments;
+  if (!family || !(MARKDOWN_HOSTED_FAMILIES as readonly string[]).includes(family)) return false;
+  if (rest.some((s) => FLOW_SEGMENTS.has(s))) return false;
+  // The index and one item. A podcast episode is the one page a level deeper.
+  return rest.length <= (family === "podcasts" ? 2 : 1);
+}
+
+/**
+ * Where the Markdown copy of a page lives: the canonical with `md` added, when
+ * the canonical is one of this profile's websites (they all serve Markdown).
+ * A canonical pointing anywhere else may not, so the page's own URL is used.
+ */
+export function markdownAlternateHref(seo: SeoRecord, pathname: string, canonical?: string | null): string {
+  const own = [seo.origin, seo.defaultWebsiteOrigin].filter(Boolean).map((o) => o.replace(/\/+$/, ""));
+  const onOurs = !!canonical && own.some((o) => canonical === o || canonical.startsWith(`${o}/`));
+  const path = normalizePathname(pathname);
+  const base = onOurs ? canonical! : `${seo.origin.replace(/\/+$/, "")}${path === "/" ? "/" : path}`;
+  return `${base}${base.includes("?") ? "&" : "?"}md`;
+}
+
+/**
+ * The `<link rel="alternate" type="text/markdown">` for an indexable page, or
+ * null when there is no copy to point at (readable copies off, a noindex page,
+ * a path the edge does not convert).
+ */
+export function markdownAlternateLink(
+  seo: SeoRecord,
+  pathname: string,
+  options: { canonical?: string | null; noindex?: boolean },
+): SeoLinkEntry | null {
+  if (seo.markdownEnabled === false || options.noindex || seo.indexing === false) return null;
+  if (!isMarkdownPath(pathname)) return null;
+  return { rel: "alternate", type: "text/markdown", href: markdownAlternateHref(seo, pathname, options.canonical) };
+}

package/src/seo/resolve.ts

@@ -0,0 +1,254 @@
+import type { SeoHeadContext, SeoPageOverride, SeoPageType, SeoRecord } from "./types";
+
+// Pure resolution: one place decides what a page's SEO is, so the server render,
+// the hydrated page and an in-site navigation all compute the same tags from
+// the same serialized record.
+//
+// The order, field by field:
+//   1. the creator's approved override for this exact pathname,
+//   2. then the override for the route pattern ("/team/$slug"),
+//   3. then what the code passed in,
+//   4. then the page type's template,
+//   5. then the site defaults.
+
+export const DEFAULT_TITLE_TEMPLATE = "{title} | {site}";
+
+/** "/about/" and "/about" are one page. The root stays "/". */
+export function normalizePathname(pathname: string | undefined | null): string {
+  if (!pathname) return "/";
+  const bare = pathname.split(/[?#]/)[0] || "/";
+  const withSlash = bare.startsWith("/") ? bare : `/${bare}`;
+  return withSlash.length > 1 ? withSlash.replace(/\/+$/, "") || "/" : withSlash;
+}
+
+/** Hosted pages render centrally and emit their own canonical. */
+export function isHostedPath(pathname: string): boolean {
+  const p = normalizePathname(pathname);
+  return p === "/i" || p.startsWith("/i/");
+}
+
+/**
+ * The record a site's root loader returned, read from the root match.
+ *
+ * `undefined` and `null` both mean "no record": an old backend, a failed fetch,
+ * or a site whose root loader predates the field. Every caller degrades to the
+ * code's own values in that case.
+ */
+export function seoRecordFromContext(ctx: SeoHeadContext | undefined | null): SeoRecord | null {
+  const root = ctx?.matches?.[0]?.loaderData as { seo?: SeoRecord | null } | null | undefined;
+  const seo = root?.seo;
+  return seo && typeof seo === "object" && typeof seo.siteName === "string" ? seo : null;
+}
+
+/**
+ * Whether this render is a not-found page: a URL no route matches, or a route
+ * whose loader threw `notFound()`. TanStack marks the boundary match with
+ * `_notFound` and the throwing match with `status: "notFound"`.
+ */
+export function isNotFoundContext(ctx: SeoHeadContext | undefined | null): boolean {
+  const all = [...(ctx?.matches ?? []), ctx?.match];
+  return all.some((m) => !!m && (m._notFound === true || m.status === "notFound"));
+}
+
+/** The browser's own pathname, when there is a browser. Undefined on the server. */
+function locationPathname(): string | undefined {
+  const loc = (globalThis as { location?: { pathname?: unknown } }).location;
+  return typeof loc?.pathname === "string" && loc.pathname ? loc.pathname : undefined;
+}
+
+/**
+ * The pathname of the page being rendered: the leaf match's.
+ *
+ * A not-found render is the exception. A URL no route matches has only the
+ * root match left, whose pathname is "/", so the leaf would claim to be the
+ * home page. There the location is used when there is one (in the browser),
+ * and the leaf only when nothing better is known. Callers must not state a
+ * canonical for a not-found render whatever this returns (see siteSeoHead).
+ */
+export function pathnameFromContext(ctx: SeoHeadContext | undefined | null): string {
+  if (isNotFoundContext(ctx)) {
+    const fromLocation = locationPathname();
+    if (fromLocation) return normalizePathname(fromLocation);
+  }
+  const matches = ctx?.matches ?? [];
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const pathname = matches[i]?.pathname;
+    if (pathname) return normalizePathname(pathname);
+  }
+  return normalizePathname(ctx?.match?.pathname);
+}
+
+/** The route pattern of the match whose head() is running ("/team/$slug"). */
+export function routePatternFromContext(ctx: SeoHeadContext | undefined | null): string | undefined {
+  const match = ctx?.match;
+  const pattern = match?.fullPath ?? match?.routeId;
+  return pattern ? normalizePathname(pattern) : undefined;
+}
+
+/** The route pattern of the leaf match, for the root, which renders above it. */
+export function leafRoutePatternFromContext(ctx: SeoHeadContext | undefined | null): string | undefined {
+  const matches = ctx?.matches ?? [];
+  const leaf = matches[matches.length - 1];
+  const pattern = leaf?.fullPath ?? leaf?.routeId;
+  return pattern ? normalizePathname(pattern) : undefined;
+}
+
+const present = <T>(value: T | null | undefined): value is T =>
+  value !== null && value !== undefined && !(typeof value === "string" && value.trim() === "");
+
+/**
+ * The override for one page, merged field by field: the exact pathname wins,
+ * the route pattern fills what it leaves unset.
+ */
+export function findOverride(
+  seo: SeoRecord | null | undefined,
+  pathname: string,
+  routePattern?: string,
+): SeoPageOverride | null {
+  if (!seo?.pages) return null;
+  const exact = seo.pages[normalizePathname(pathname)];
+  const pattern = routePattern ? seo.pages[normalizePathname(routePattern)] : undefined;
+  if (!exact && !pattern) return null;
+  const merged: SeoPageOverride = {};
+  for (const key of ["title", "description", "image", "canonical", "noindex"] as const) {
+    const value = present(exact?.[key]) ? exact?.[key] : pattern?.[key];
+    if (present(value)) (merged as Record<string, unknown>)[key] = value;
+  }
+  return merged;
+}
+
+/** Fill `{title}` and `{site}` (or `{site.name}`) in a template. */
+export function fillTemplate(template: string, values: { title: string; site: string }): string {
+  return template
+    .replace(/\{title\}/g, values.title)
+    .replace(/\{site(?:\.name)?\}/g, values.site)
+    .trim();
+}
+
+/**
+ * Whether a stored title template can be used: it must say where the page's
+ * title goes. The API refuses one without `{title}`, but a record saved before
+ * that check (or by an older API) may still carry "%s | Clay Studio", which
+ * would otherwise become every page's literal title.
+ */
+export function isUsableTitleTemplate(template: string | null | undefined): template is string {
+  return typeof template === "string" && template.includes("{title}");
+}
+
+/**
+ * The document title for a code title.
+ *
+ * A template without `{title}` is ignored in favour of the default.
+ * The template is skipped when the title already names the site, so a code
+ * title of "Clay Studio | Pottery in Hackney" does not become
+ * "Clay Studio | Pottery in Hackney | Clay Studio".
+ */
+export function applyTitleTemplate(title: string, siteName: string, template?: string | null): string {
+  const site = siteName.trim();
+  const base = title.trim();
+  if (!site) return base;
+  if (!base) return site;
+  if (base.toLowerCase().includes(site.toLowerCase())) return base;
+  const usable = isUsableTitleTemplate(template?.trim()) ? template!.trim() : DEFAULT_TITLE_TEMPLATE;
+  const filled = fillTemplate(usable, { title: base, site });
+  return filled || base;
+}
+
+/** The canonical URL for a page: the override's, else origin + pathname. */
+export function canonicalFor(
+  seo: SeoRecord,
+  pathname: string,
+  override?: SeoPageOverride | null,
+  options?: { entity?: boolean },
+): string {
+  if (present(override?.canonical)) return override!.canonical!;
+  const origin = (options?.entity ? seo.defaultWebsiteOrigin || seo.origin : seo.origin).replace(/\/+$/, "");
+  const path = normalizePathname(pathname);
+  return path === "/" ? `${origin}/` : `${origin}${path}`;
+}
+
+export type ResolvedPageSeo = {
+  /** The document title, template applied. */
+  title: string;
+  /** The title for share cards, without the site suffix. */
+  shareTitle: string;
+  description: string;
+  image?: string;
+  noindex: boolean;
+  /** Null when there is no record, so no canonical can be stated. */
+  canonical: string | null;
+  /** True when a creator override supplied at least one field. */
+  overridden: boolean;
+};
+
+export type ResolveInput = {
+  pathname: string;
+  routePattern?: string;
+  type?: SeoPageType;
+  title?: string;
+  description?: string;
+  image?: string;
+  noindex?: boolean;
+  /** Entity pages canonicalize to the profile's default website. */
+  entity?: boolean;
+};
+
+export function resolvePageSeo(seo: SeoRecord | null | undefined, input: ResolveInput): ResolvedPageSeo {
+  const codeTitle = input.title?.trim() ?? "";
+
+  if (!seo) {
+    // No record: today's behaviour, exactly. The code's values stand as given.
+    const title = codeTitle;
+    return {
+      title,
+      shareTitle: title,
+      description: input.description || title,
+      image: input.image || undefined,
+      noindex: !!input.noindex,
+      canonical: null,
+      overridden: false,
+    };
+  }
+
+  const override = findOverride(seo, input.pathname, input.routePattern);
+  const typeTemplate = input.type ? seo.typeTemplates?.[input.type] : undefined;
+  const site = seo.siteName ?? "";
+
+  let title: string;
+  let shareTitle: string;
+  if (present(override?.title)) {
+    // An approved title is what the creator signed off on, so it is used
+    // verbatim: no template, no suffix.
+    title = override!.title!.trim();
+    shareTitle = title;
+  } else {
+    shareTitle = codeTitle || site;
+    // The page type's template, else the site's: whichever first says where the
+    // title goes. Neither usable means the default.
+    const template = [typeTemplate?.title, seo.titleTemplate].find(isUsableTitleTemplate);
+    title = applyTitleTemplate(shareTitle, site, template);
+  }
+
+  const description =
+    (present(override?.description) ? override!.description! : undefined) ||
+    input.description ||
+    (typeTemplate?.description ? fillTemplate(typeTemplate.description, { title: shareTitle, site }) : undefined) ||
+    seo.defaultDescription ||
+    shareTitle;
+
+  const image = (present(override?.image) ? override!.image! : undefined) || input.image || seo.defaultImage || undefined;
+
+  const noindex =
+    seo.indexing === false ||
+    (typeof override?.noindex === "boolean" ? override.noindex : !!input.noindex);
+
+  return {
+    title,
+    shareTitle,
+    description,
+    image,
+    noindex,
+    canonical: canonicalFor(seo, input.pathname, override, { entity: input.entity }),
+    overridden: !!override && Object.keys(override).length > 0,
+  };
+}

package/src/seo/seoHead.ts

@@ -0,0 +1,67 @@
+import {
+  isNotFoundContext,
+  pathnameFromContext,
+  resolvePageSeo,
+  routePatternFromContext,
+  seoRecordFromContext,
+  type ResolvedPageSeo,
+} from "./resolve";
+import type { SeoHeadContext, SeoHeadInput, SeoMetaEntry } from "./types";
+
+/** JSON-LD nodes as head() meta entries. TanStack renders each as a script tag. */
+export function jsonLdMeta(jsonLd?: object | object[] | null): SeoMetaEntry[] {
+  const nodes = Array.isArray(jsonLd) ? jsonLd : jsonLd ? [jsonLd] : [];
+  return nodes.filter((n) => !!n && typeof n === "object").map((n) => ({ "script:ld+json": n }));
+}
+
+/** The per-page share and robots tags for one resolved page. */
+export function pageMeta(resolved: ResolvedPageSeo, ogType = "website"): SeoMetaEntry[] {
+  const { title, shareTitle, description, image, noindex, canonical } = resolved;
+  return [
+    { title },
+    { name: "description", content: description },
+    { property: "og:title", content: shareTitle },
+    { property: "og:description", content: description },
+    { property: "og:type", content: ogType },
+    ...(canonical ? [{ property: "og:url", content: canonical }] : []),
+    ...(image ? [{ property: "og:image", content: image }] : []),
+    { name: "twitter:card", content: "summary_large_image" },
+    { name: "twitter:title", content: shareTitle },
+    { name: "twitter:description", content: description },
+    ...(image ? [{ name: "twitter:image", content: image }] : []),
+    ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
+  ];
+}
+
+/**
+ * A route's SEO, declared in code with the creator's edits resolved over it.
+ *
+ *   head: (ctx) => seoHead(ctx, { title: "About Clay Studio", description: "..." })
+ *
+ * Reads the site's SEO record from the root match (the root loader fetched it
+ * with `fetchSiteBootstrap`) and returns `{ meta }` ONLY. Never links: TanStack
+ * concatenates links across every match, so a canonical here would sit beside
+ * the root's and the page would carry two. The root's `siteSeoHead` is the one
+ * place a canonical comes from.
+ *
+ * With no record (an older backend, or a failed fetch) it emits what
+ * `buildHeadMeta` always did, minus the links.
+ */
+export function seoHead(ctx: SeoHeadContext | undefined | null, input: SeoHeadInput): { meta: SeoMetaEntry[] } {
+  const seo = seoRecordFromContext(ctx);
+  const resolved = resolvePageSeo(seo, {
+    pathname: pathnameFromContext(ctx),
+    routePattern: routePatternFromContext(ctx),
+    type: input.type ?? "page",
+    title: input.title,
+    description: input.description,
+    image: input.image,
+    noindex: input.noindex,
+  });
+  // A page whose loader threw notFound() renders the not-found page under its
+  // own URL. That is not a page to index or to share as itself.
+  if (isNotFoundContext(ctx)) {
+    return { meta: pageMeta({ ...resolved, noindex: true, canonical: null }) };
+  }
+  return { meta: [...pageMeta(resolved), ...jsonLdMeta(input.jsonLd)] };
+}

package/src/seo/siteSeoHead.ts

@@ -0,0 +1,114 @@
+import { buildIdentitySchema, buildWebSiteSchema, identitySchemaId } from "../utils/structuredData";
+import {
+  canonicalFor,
+  findOverride,
+  isHostedPath,
+  isNotFoundContext,
+  leafRoutePatternFromContext,
+  pathnameFromContext,
+  seoRecordFromContext,
+} from "./resolve";
+import { markdownAlternateLink } from "./markdown";
+import { jsonLdMeta } from "./seoHead";
+import type { SeoHeadContext, SeoLinkEntry, SeoMetaEntry } from "./types";
+
+export type SiteSeoFallback = {
+  /** Used when there is no SEO record, e.g. the site config's name. */
+  siteName?: string | null;
+  description?: string | null;
+  image?: string | null;
+};
+
+/**
+ * Site-wide head tags, for the ROOT route's `head()`.
+ *
+ *   head: (ctx) => siteSeoHead(ctx)
+ *
+ * Every tag here is a fallback a page can replace (TanStack keeps the deepest
+ * title and the deepest meta of each name), except two things only the root
+ * may emit:
+ *
+ *  - the canonical link, because links are concatenated across matches rather
+ *    than replaced. It is skipped under `/i/`, where the hosted page emits its
+ *    own (an entity's canonical is on the default website, which only that page
+ *    knows to say);
+ *  - the WebSite and identity JSON-LD, on "/" only;
+ *  - the `alternate` link to the page's Markdown copy, beside the canonical.
+ *
+ * `robots` is set here when the whole site is noindex or this path's override
+ * says so, so it holds even on a page whose code never calls `seoHead`.
+ *
+ * A not-found render states none of the three: no canonical, no Markdown copy
+ * and no site JSON-LD, and it is `noindex`. On a URL no route matches, the only
+ * match left is the root's, at "/", so without this every 404 would claim to
+ * be the home page.
+ */
+export function siteSeoHead(
+  ctx: SeoHeadContext | undefined | null,
+  fallback: SiteSeoFallback = {},
+): { meta: SeoMetaEntry[]; links: SeoLinkEntry[] } {
+  const seo = seoRecordFromContext(ctx);
+  const pathname = pathnameFromContext(ctx);
+
+  if (!seo) {
+    const name = fallback.siteName?.trim();
+    return {
+      meta: [
+        ...(name ? [{ title: name }, { property: "og:site_name", content: name }] : []),
+        ...(fallback.description ? [{ name: "description", content: fallback.description }] : []),
+        ...(fallback.image ? [{ property: "og:image", content: fallback.image }] : []),
+        { name: "twitter:card", content: "summary_large_image" },
+      ],
+      links: [],
+    };
+  }
+
+  const notFound = isNotFoundContext(ctx);
+  // A missing page has no override: one keyed to "/" or to the route pattern
+  // belongs to a page that exists.
+  const override = notFound ? null : findOverride(seo, pathname, leafRoutePatternFromContext(ctx));
+  const description = seo.defaultDescription || fallback.description || undefined;
+  const image = seo.defaultImage || fallback.image || undefined;
+  const noindex = notFound || seo.indexing === false || override?.noindex === true;
+
+  const meta: SeoMetaEntry[] = [
+    { title: seo.siteName },
+    ...(description ? [{ name: "description", content: description }] : []),
+    { property: "og:site_name", content: seo.siteName },
+    ...(image ? [{ property: "og:image", content: image }] : []),
+    { name: "twitter:card", content: "summary_large_image" },
+    ...(seo.verification?.google ? [{ name: "google-site-verification", content: seo.verification.google }] : []),
+    ...(seo.verification?.bing ? [{ name: "msvalidate.01", content: seo.verification.bing }] : []),
+    ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
+  ];
+
+  if (pathname === "/" && !notFound) {
+    const origin = seo.origin.replace(/\/+$/, "");
+    const identity = buildIdentitySchema(seo.identity, { origin });
+    meta.push(
+      ...jsonLdMeta(
+        [
+          buildWebSiteSchema({
+            name: seo.siteName,
+            url: `${origin}/`,
+            description: seo.defaultDescription,
+            publisherId: identity ? identitySchemaId(origin) : null,
+          }),
+          identity,
+        ].filter((n): n is Record<string, unknown> => !!n),
+      ),
+    );
+  }
+
+  const links: SeoLinkEntry[] = [];
+  if (!notFound && !isHostedPath(pathname)) {
+    const canonical = canonicalFor(seo, pathname, override);
+    links.push({ rel: "canonical", href: canonical });
+    // The page's readable copy for agents (section 5.4). A hosted page states
+    // its own, beside its own canonical (see applySeoToHead).
+    const markdown = markdownAlternateLink(seo, pathname, { canonical, noindex });
+    if (markdown) links.push(markdown);
+  }
+
+  return { meta, links };
+}

package/src/seo/types.ts

@@ -0,0 +1,113 @@
+// The SEO record, as `GET /public/websites/seo` returns it.
+//
+// The backend owns the data (settings, templates, the creator's approved page
+// overrides); code owns the defaults. These types are the seam between the two,
+// and the backend returns exactly this shape. Change one side, change both.
+
+export type SeoPageType =
+  | "page"
+  | "product"
+  | "event"
+  | "course"
+  | "coaching"
+  | "blog_post"
+  | "blog_category"
+  | "podcast"
+  | "podcast_episode"
+  | "community"
+  | "series"
+  | "film";
+
+export type SeoPageOverride = {
+  title?: string | null;
+  description?: string | null;
+  image?: string | null;
+  /** Absolute URL. */
+  canonical?: string | null;
+  noindex?: boolean | null;
+};
+
+export type SeoIdentity = {
+  kind: "person" | "organization" | "local_business";
+  name: string;
+  logo?: string | null;
+  sameAs: string[];
+  address?: { street?: string; locality?: string; region?: string; postalCode?: string; country?: string } | null;
+  phone?: string | null;
+};
+
+export type SeoRecord = {
+  websiteId: string;
+  /** "https://claystudio.com": the primary verified custom domain, else https://{subdomain}.{ROOT_DOMAIN}. */
+  origin: string;
+  isDefaultWebsite: boolean;
+  /** Origin of the profile's default website. Entity canonicals point here. */
+  defaultWebsiteOrigin: string;
+  siteName: string;
+  defaultDescription: string | null;
+  defaultImage: string | null;
+  /** Default "{title} | {site}". */
+  titleTemplate: string;
+  typeTemplates: Partial<Record<SeoPageType, { title?: string; description?: string }>>;
+  identity: SeoIdentity | null;
+  verification: { google?: string | null; bing?: string | null };
+  /** false = the whole site is noindex. */
+  indexing: boolean;
+  /**
+   * false = readable copies are off: the edge serves no Markdown and pages do
+   * not advertise one. Optional because an API older than Forge 3.64 omits it,
+   * which means on.
+   */
+  markdownEnabled?: boolean;
+  /**
+   * Key = exact pathname ("/about", "/i/store/mug") OR route pattern
+   * ("/team/$slug"). Entity overrides arrive already expanded to their /i/
+   * pathname.
+   */
+  pages: Record<string, SeoPageOverride>;
+  /** Max updatedAt of the inputs, ISO. */
+  version: string;
+};
+
+/** What a route's code says its SEO is, before any creator edit. */
+export type SeoHeadInput = {
+  title: string;
+  description?: string;
+  image?: string;
+  noindex?: boolean;
+  type?: SeoPageType;
+  jsonLd?: object | object[];
+};
+
+/**
+ * The part of TanStack's `head()` context Forge reads.
+ *
+ * Structural rather than imported, so Forge does not pin a router version and a
+ * site can pass `ctx` straight through.
+ */
+export type SeoMatchLike = {
+  pathname?: string;
+  routeId?: string;
+  fullPath?: string;
+  loaderData?: unknown;
+  /** "notFound" on the match whose loader threw `notFound()`. */
+  status?: string;
+  /**
+   * TanStack sets this on the match that renders the not-found boundary. On a
+   * URL no route matches, that is the ROOT match, whose pathname is "/": read
+   * without this flag, every unknown URL looks like the home page.
+   */
+  _notFound?: boolean;
+};
+
+export type SeoHeadContext = {
+  matches?: ReadonlyArray<SeoMatchLike | undefined>;
+  match?: SeoMatchLike;
+  params?: Record<string, string>;
+  loaderData?: unknown;
+};
+
+/** One `head()` meta entry. A JSON-LD node rides as `{ "script:ld+json": obj }`. */
+export type SeoMetaEntry = Record<string, unknown>;
+
+export type SeoLinkEntry = { rel: string; href: string; type?: string };

package/src/server/_tests/buildPwaHead.spec.ts

@@ -7,7 +7,7 @@
 //  - apple-touch-icon derive (icon192 preferred, icon512 fallback, absent → omit)
 //  - theme-color derivation + default fallback (bare + localized + no doc)
 //  - manifestHref override / default
-//  - apple-mobile-web-app-title fallback chain (shortName → name → siteName → "App")
+//  - apple-mobile-web-app-title fallback chain (shortName → name → SEO siteName → siteName → "App")
 //  - null/undefined siteConfig degradation (never throws)
 //  - the known client bug this fixes: apple-touch-icon is always emitted when an icon exists
 //
@@ -165,6 +165,23 @@ describe("buildPwaHead — apple-mobile-web-app-title fallback chain", () => {
     const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: null }) });
     expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("App");
   });
+
+  it("prefers the SEO record's site name over the site config's (the profile's)", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: { siteName: "Clay Studio" } });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Clay Studio");
+  });
+
+  it("keeps an explicit PWA name ahead of the SEO site name", () => {
+    const head = buildPwaHead({ siteConfig: siteConfig({ pwa: fullPwa({ shortName: "Nv" }) }), seo: { siteName: "Clay Studio" } });
+    expect(metaFor(head.metas, "apple-mobile-web-app-title")?.content).toBe("Nv");
+  });
+
+  it("ignores a blank SEO site name, and no record at all", () => {
+    const blank = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: { siteName: "  " } });
+    expect(metaFor(blank.metas, "apple-mobile-web-app-title")?.content).toBe("Ada Potter");
+    const none = buildPwaHead({ siteConfig: siteConfig({ pwa: null, siteName: "Ada Potter" }), seo: null });
+    expect(metaFor(none.metas, "apple-mobile-web-app-title")?.content).toBe("Ada Potter");
+  });
 });
 
 describe("buildPwaHead — degradation (never throws)", () => {