@tribe-nest/forge 3.63.0 → 3.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.63.0",
+  "version": "3.64.0",
   "publishConfig": {
     "access": "public"
   },

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

@@ -1,9 +1,13 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   applySeoToHead,
   applyTitleTemplate,
   findOverride,
+  isMarkdownPath,
+  isNotFoundContext,
+  markdownAlternateHref,
   normalizePathname,
+  pathnameFromContext,
   resolvePageSeo,
   seoHead,
   siteSeoHead,
@@ -38,6 +42,9 @@ const RECORD: SeoRecord = {
 
 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: {} };
@@ -86,6 +93,31 @@ describe("applyTitleTemplate", () => {
   });
 });
 
+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({
@@ -214,19 +246,25 @@ describe("siteSeoHead", () => {
       "msvalidate.01": "b-token",
     });
     expect(t.robots).toBeUndefined();
-    expect(out.links).toEqual([{ rel: "canonical", href: "https://claystudio.com/about" }]);
+    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" }]);
+    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(1);
+    expect(siteSeoHead(ctx("/ideas", RECORD)).links).toHaveLength(2);
   });
 
   it("noindexes when the site is not indexing or the path's override says so", () => {
@@ -266,6 +304,94 @@ describe("siteSeoHead", () => {
   });
 });
 
+/**
+ * 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" }),
@@ -286,7 +412,10 @@ describe("applySeoToHead", () => {
     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.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);
@@ -296,7 +425,7 @@ describe("applySeoToHead", () => {
   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" }]);
+    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", () => {
@@ -324,3 +453,70 @@ describe("applySeoToHead", () => {
     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

@@ -1,3 +1,4 @@
+import { markdownAlternateLink } from "./markdown";
 import { normalizePathname, resolvePageSeo } from "./resolve";
 import type { SeoPageType, SeoRecord } from "./types";
 
@@ -91,8 +92,13 @@ export function applySeoToHead<T extends HeadTags>(
   ];
 
   // A noindex page states no canonical: there is no indexed copy to point at.
-  const links = (head.links ?? []).filter((l) => l.rel !== "canonical");
+  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 };
 }

package/src/seo/index.ts

@@ -7,3 +7,4 @@ 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

@@ -40,8 +40,36 @@ export function seoRecordFromContext(ctx: SeoHeadContext | undefined | null): Se
   return seo && typeof seo === "object" && typeof seo.siteName === "string" ? seo : null;
 }
 
-/** The leaf pathname: the last match is the page being rendered. */
+/**
+ * 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;
@@ -97,9 +125,20 @@ export function fillTemplate(template: string, values: { title: string; site: st
     .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".
@@ -110,7 +149,8 @@ export function applyTitleTemplate(title: string, siteName: string, template?: s
   if (!site) return base;
   if (!base) return site;
   if (base.toLowerCase().includes(site.toLowerCase())) return base;
-  const filled = fillTemplate(template?.trim() || DEFAULT_TITLE_TEMPLATE, { title: base, site });
+  const usable = isUsableTitleTemplate(template?.trim()) ? template!.trim() : DEFAULT_TITLE_TEMPLATE;
+  const filled = fillTemplate(usable, { title: base, site });
   return filled || base;
 }
 
@@ -183,7 +223,10 @@ export function resolvePageSeo(seo: SeoRecord | null | undefined, input: Resolve
     shareTitle = title;
   } else {
     shareTitle = codeTitle || site;
-    title = applyTitleTemplate(shareTitle, site, typeTemplate?.title || seo.titleTemplate);
+    // 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 =

package/src/seo/seoHead.ts

@@ -1,4 +1,5 @@
 import {
+  isNotFoundContext,
   pathnameFromContext,
   resolvePageSeo,
   routePatternFromContext,
@@ -57,5 +58,10 @@ export function seoHead(ctx: SeoHeadContext | undefined | null, input: SeoHeadIn
     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

@@ -3,10 +3,12 @@ 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";
 
@@ -30,10 +32,16 @@ export type SiteSeoFallback = {
  *    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 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,
@@ -55,10 +63,13 @@ export function siteSeoHead(
     };
   }
 
-  const override = findOverride(seo, pathname, leafRoutePatternFromContext(ctx));
+  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 = seo.indexing === false || override?.noindex === true;
+  const noindex = notFound || seo.indexing === false || override?.noindex === true;
 
   const meta: SeoMetaEntry[] = [
     { title: seo.siteName },
@@ -71,7 +82,7 @@ export function siteSeoHead(
     ...(noindex ? [{ name: "robots", content: "noindex, nofollow" }] : []),
   ];
 
-  if (pathname === "/") {
+  if (pathname === "/" && !notFound) {
     const origin = seo.origin.replace(/\/+$/, "");
     const identity = buildIdentitySchema(seo.identity, { origin });
     meta.push(
@@ -89,9 +100,15 @@ export function siteSeoHead(
     );
   }
 
-  const links: SeoLinkEntry[] = isHostedPath(pathname)
-    ? []
-    : [{ rel: "canonical", href: canonicalFor(seo, pathname, override) }];
+  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

@@ -53,6 +53,12 @@ export type SeoRecord = {
   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/
@@ -84,6 +90,14 @@ export type SeoMatchLike = {
   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 = {
@@ -96,4 +110,4 @@ export type SeoHeadContext = {
 /** 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 };
+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)", () => {

package/src/server/pwa.ts

@@ -178,6 +178,13 @@ export interface BuildPwaHeadOptions {
   contentDoc?: ContentDocument | null;
   /** Where the manifest route lives (default `/manifest.webmanifest`). */
   manifestHref?: string;
+  /**
+   * The website's SEO record, as the root loader returned it. Its `siteName` is
+   * what the creator calls the site in search, so the Home Screen label uses it
+   * ahead of the site config's name (the profile's). A PWA name the creator set
+   * explicitly still wins: that is the app's own label.
+   */
+  seo?: { siteName?: string | null } | null;
 }
 
 /** A TanStack `head()`-shaped link entry. */
@@ -219,7 +226,15 @@ export function buildPwaHead(opts: BuildPwaHeadOptions): PwaHead {
     { name: "mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-status-bar-style", content: "default" },
-    { name: "apple-mobile-web-app-title", content: siteConfig?.pwa?.shortName || siteConfig?.pwa?.name || siteConfig?.siteName || "App" },
+    {
+      name: "apple-mobile-web-app-title",
+      content:
+        siteConfig?.pwa?.shortName ||
+        siteConfig?.pwa?.name ||
+        opts.seo?.siteName?.trim() ||
+        siteConfig?.siteName ||
+        "App",
+    },
   ];
   return { links, metas };
 }

package/src/utils/_tests/structuredDataSeo.spec.ts

@@ -2,11 +2,17 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   buildBlogPostingSchema,
   buildBreadcrumbSchema,
+  buildCourseSchema,
   buildEventSchema,
+  buildFilmSchema,
   buildIdentitySchema,
   buildPodcastEpisodeSchema,
   buildPodcastSeriesSchema,
+  buildProductSchema,
+  buildServiceSchema,
   buildWebSiteSchema,
+  seoBrandName,
+  withSeoBrand,
   type EventSchemaSource,
 } from "../structuredData";
 
@@ -245,3 +251,33 @@ describe("site schemas", () => {
     expect(buildBreadcrumbSchema([{ name: "Clay", url: "https://clay.com/" }])).toBeNull();
   });
 });
+
+describe("the business name in structured data", () => {
+  it("is the SEO identity's name, then the SEO site name, then the profile's", () => {
+    const seo = { identity: { name: " Clay Studio Ltd " }, siteName: "Clay Studio" };
+    expect(seoBrandName(seo, "Ada Potter")).toBe("Clay Studio Ltd");
+    expect(seoBrandName({ identity: null, siteName: "Clay Studio" }, "Ada Potter")).toBe("Clay Studio");
+    expect(seoBrandName({ identity: { name: "  " }, siteName: "" }, "Ada Potter")).toBe("Ada Potter");
+    expect(seoBrandName(null, "Ada Potter")).toBe("Ada Potter");
+    expect(seoBrandName(null, null)).toBeUndefined();
+  });
+
+  it("names Product brand and Course, Service and Film provider the same way", () => {
+    const context = withSeoBrand({ currency: "GBP", brand: "Ada Potter" }, { identity: { name: "Clay Studio Ltd" }, siteName: "Clay Studio" });
+    expect(context).toEqual({ currency: "GBP", brand: "Clay Studio Ltd" });
+
+    const product = buildProductSchema({ title: "Mug", variants: [] } as never, context);
+    expect(product?.brand).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const course = buildCourseSchema({ title: "Wheel basics" } as never, context);
+    expect(course?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const service = buildServiceSchema({ title: "Studio hour" } as never, context);
+    expect(service?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+    const film = buildFilmSchema({ title: "Throwing", kind: "film" } as never, context);
+    expect(film?.provider).toEqual({ "@type": "Organization", name: "Clay Studio Ltd" });
+  });
+
+  it("keeps the profile name when there is no SEO record", () => {
+    expect(withSeoBrand({ currency: "GBP", brand: "Ada Potter" }, null)).toEqual({ currency: "GBP", brand: "Ada Potter" });
+    expect(withSeoBrand(null, null)).toEqual({ brand: undefined });
+  });
+});

package/src/utils/structuredData.ts

@@ -299,6 +299,30 @@ export function seoContextFromSiteConfig(
   return { currency: config.currency || undefined, brand: config.siteName || undefined };
 }
 
+/**
+ * The name structured data gives the business behind a page: the SEO
+ * identity's name when the creator set one, else the SEO site name, else
+ * `fallback` (the site config's name, which is the profile's).
+ *
+ * One rule for every node that names the business (Product `brand`, Course,
+ * Service and Film `provider`, Event `organizer`), so a product page and an
+ * event page never disagree about who sells them.
+ */
+export function seoBrandName(
+  seo?: { identity?: { name?: string | null } | null; siteName?: string | null } | null,
+  fallback?: string | null,
+): string | undefined {
+  return seo?.identity?.name?.trim() || seo?.siteName?.trim() || fallback?.trim() || undefined;
+}
+
+/** A route's `SiteSeoContext` with its `brand` named by the SEO record (see `seoBrandName`). */
+export function withSeoBrand(
+  context: SiteSeoContext | null | undefined,
+  seo?: { identity?: { name?: string | null } | null; siteName?: string | null } | null,
+): SiteSeoContext {
+  return { ...context, brand: seoBrandName(seo, context?.brand) };
+}
+
 /**
  * The offer for a product, derived from its variants.
  *