@tokenoftrust/storefront-runner 2.4.74 → 2.4.75

package/apps/storefront/src/components/Breadcrumbs.astro

@@ -14,6 +14,7 @@
  * `class` adds a hook for the page's own styles (`breadcrumbs` on the blog templates).
  */
 import { withBase } from "@/lib/basePath";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 import type { Crumb } from "@/lib/breadcrumbs";
 
 interface Props {
@@ -22,7 +23,7 @@ interface Props {
 }
 
 const { crumbs, class: className } = Astro.props;
-const { basePath } = Astro.locals;
+const { basePath, tenant } = Astro.locals;
 ---
 
 <nav aria-label="Breadcrumb" class:list={["text-sm text-muted", className]}>
@@ -43,7 +44,7 @@ const { basePath } = Astro.locals;
               </span>
             ) : (
               <a
-                href={withBase(basePath, crumb.href)}
+                href={withBase(basePath, pageUrlForm(crumb.href, tenant.seo))}
                 class="inline-flex min-h-11 items-center transition-colors hover:text-primary"
               >
                 {crumb.label}

package/apps/storefront/src/components/CollectionCard.astro

@@ -7,6 +7,7 @@
 import type { CatalogCollection } from "@tot/public-runtime";
 import Img from "@/components/Img.astro";
 import { withBase } from "@/lib/basePath";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 
 interface Props {
   collection: CatalogCollection;
@@ -14,12 +15,12 @@ interface Props {
 }
 
 const { collection, productCount } = Astro.props;
-const { basePath } = Astro.locals;
+const { basePath, tenant } = Astro.locals;
 const image = collection.image;
 ---
 
 <a
-  href={withBase(basePath, `/collections/${collection.handle}`)}
+  href={withBase(basePath, pageUrlForm(`/collections/${collection.handle}`, tenant.seo))}
   data-astro-prefetch
   class="group relative block aspect-[3/2] overflow-hidden rounded-md bg-border"
   data-reveal

package/apps/storefront/src/components/ProductCard.astro

@@ -15,6 +15,7 @@ import Badge from "@/components/Badge.astro";
 import PriceDisplay from "@/components/commerce/PriceDisplay.astro";
 import RatingStars from "@/components/commerce/RatingStars.astro";
 import { withBase } from "@/lib/basePath";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 
 interface Props {
   product: CatalogProduct;
@@ -189,7 +190,7 @@ const quickview = {
       {/* `py-3` on an inline box raises the tap target to the 44px minimum
           without changing the line box, so the card layout is untouched. */}
       <a
-        href={withBase(basePath, `/products/${product.handle}`)}
+        href={withBase(basePath, pageUrlForm(`/products/${product.handle}`, tenant.seo))}
         data-astro-prefetch
         class="py-3 after:absolute after:inset-0 after:z-0 transition-colors motion-safe:group-hover:text-primary"
       >

package/apps/storefront/src/components/Seo.astro

@@ -7,6 +7,7 @@ import { articleSeoMetaTags, resolveOgImage, type ArticleMeta } from "@/lib/seo/
 import { withXDefault, type Alternate } from "@/lib/seo/alternates.js";
 import { safeJsonScriptContent } from "@/lib/jsonScript";
 import { documentTitle } from "@/lib/seo/documentTitle";
+import { canonicalUrl } from "@/lib/seo/urlForm";
 
 interface JsonLd {
   [key: string]: unknown;
@@ -19,7 +20,8 @@ interface Props {
    *  Absent ⇒ `title`, suffixed with the store's display name. */
   seoTitle?: string;
   description?: string;
-  /** Path-only canonical, e.g. /products/foo. Joined to tenant canonical base. */
+  /** Path-only canonical, e.g. /products/foo. Joined to tenant canonical base, in the
+   *  tenant's declared URL form (`seo.trailingSlash`). */
   path: string;
   ogType?: "website" | "product" | "article";
   ogImage?: string;
@@ -73,7 +75,7 @@ const {
 
 const { tenant, canonicalBase } = Astro.locals;
 const canonical =
-  canonicalOverride ?? new URL(path, canonicalBase + "/").toString();
+  canonicalOverride ?? canonicalUrl(path, canonicalBase, tenant.seo);
 const fullTitle = documentTitle(title, seoTitle, tenant.displayName);
 const image = resolveOgImage({
   ogImage, themeOgImage: tenant.theme_tokens?.brand?.ogImage ?? null, canonicalBase,
@@ -91,8 +93,8 @@ const articleMeta = articleSeoMetaTags({
 const graphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
 const alternateLinks = withXDefault(alternates);
 const paginationLinks = [
-  ...(pagination?.prev ? [{ rel: "prev", href: new URL(pagination.prev, canonicalBase + "/").toString() }] : []),
-  ...(pagination?.next ? [{ rel: "next", href: new URL(pagination.next, canonicalBase + "/").toString() }] : []),
+  ...(pagination?.prev ? [{ rel: "prev", href: canonicalUrl(pagination.prev, canonicalBase, tenant.seo) }] : []),
+  ...(pagination?.next ? [{ rel: "next", href: canonicalUrl(pagination.next, canonicalBase, tenant.seo) }] : []),
 ];
 ---
 

package/apps/storefront/src/components/blog/BlogIndexView.astro

@@ -60,6 +60,7 @@ const itemList = {
   path={path}
   fullBleed
   jsonLd={itemList}
+  structuredData={{ pageType: "collection" }}
   pagination={pagination}
 >
   <header class:list={["blog-hero", { "blog-hero--plain": !presentation.hero }]}>

package/apps/storefront/src/components/blog/BlogPostArticle.astro

@@ -32,6 +32,16 @@ const {
   ogImage={post.featuredImage?.src}
   noindex={post.status === "unlisted"}
   jsonLd={[crumbs, articleLd]}
+  structuredData={{
+    pageType: "post",
+    headline: post.title,
+    description: post.description,
+    datePublished: post.publishedAt,
+    dateModified: post.modifiedAt,
+    image: post.featuredImage?.src,
+    author: author ? { name: author, url: authorUrl } : null,
+    crumbs: trail,
+  }}
   article={{
     publishedTime: post.publishedAt,
     modifiedTime: post.modifiedAt,

package/apps/storefront/src/components/home/Hero.astro

@@ -23,6 +23,7 @@ import type { HeroBlock } from "@/lib/storyblok/content-model";
 import type { CatalogProduct } from "@tot/public-runtime";
 import Img from "@/components/Img.astro";
 import { withBase } from "@/lib/basePath";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 import { heroSlideshowView } from "@/lib/heroSlideshow";
 
 interface Props {
@@ -261,7 +262,7 @@ const notice = block.notice?.trim();
               />
             </div>
             <a
-              href={withBase(basePath, `/products/${featureProduct.handle}`)}
+              href={withBase(basePath, pageUrlForm(`/products/${featureProduct.handle}`, Astro.locals.tenant?.seo))}
               class="absolute bottom-4 left-4 right-4 flex items-center justify-between rounded-[var(--radius-md)] bg-[var(--color-surface)]/95 px-4 py-3 text-[var(--color-text)] backdrop-blur"
             >
               <span class="font-display text-sm font-medium">{featureProduct.title}</span>

package/apps/storefront/src/components/marketing/Faq.astro

@@ -2,11 +2,14 @@
 /**
  * <Faq> — a no-JS accordion of question/answer pairs using native
  * <details>/<summary>. Emits FAQPage JSON-LD so answers are eligible for rich
- * results. Answers are plain text (auto-escaped).
+ * results — unless the tenant declares a structured-data profile, which owns every
+ * JSON-LD node on the page (lib/seo/structuredData.ts). Answers are plain text
+ * (auto-escaped).
  */
 import Section from "@/components/Section.astro";
 import type { FaqBlock } from "@/lib/storyblok/content-model";
 import { safeJsonScriptContent } from "@/lib/jsonScript";
+import { structuredDataProfile } from "@/lib/seo/structuredData";
 interface Props {
   block: FaqBlock;
 }
@@ -22,6 +25,8 @@ const faqLd = {
   })),
 };
 const faqJsonLd = safeJsonScriptContent(faqLd);
+// A declared structured-data profile owns every JSON-LD node on the page.
+const emitsJsonLd = !structuredDataProfile(Astro.locals.tenant);
 ---
 <Section eyebrow={block.eyebrow} title={block.title} tone="surface" widget="marketing-faq">
   {block.lede && (
@@ -41,4 +46,4 @@ const faqJsonLd = safeJsonScriptContent(faqLd);
     ))}
   </div>
 </Section>
-<script type="application/ld+json" set:html={faqJsonLd} is:inline />
+{emitsJsonLd && <script type="application/ld+json" set:html={faqJsonLd} is:inline />}

package/apps/storefront/src/layouts/Layout.astro

@@ -25,6 +25,9 @@ import AuthBadge from "@/components/auth/AuthBadge.astro";
 import { referenceTheme } from "@/themes/reference";
 import { mergeTheme } from "@/themes/schema";
 import { organizationLd, websiteLd } from "@/lib/jsonld";
+import { composeStructuredData, structuredDataProfile, type StructuredDataPage } from "@/lib/seo/structuredData";
+import { canonicalUrl } from "@/lib/seo/urlForm";
+import { documentTitle } from "@/lib/seo/documentTitle";
 import { nonceInlineTags, prefixApiFormActions, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
 import { CHROME_BEHAVIOR_JS, CHROME_HEAD_JS, sanitizeSharedChromeFragment } from "@/lib/rawChrome";
 import { ASYNC_CSS_SWAP_JS } from "@/lib/asyncCss";
@@ -49,6 +52,12 @@ interface Props {
   ogImage?: string;
   noindex?: boolean;
   jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /**
+   * What the page knows about itself for the tenant's declared structured-data profile
+   * (lib/seo/structuredData.ts). When the profile declares a graph for `pageType`, that graph
+   * is the page's ONLY JSON-LD and `jsonLd` is not emitted.
+   */
+  structuredData?: StructuredDataPage;
   /** Alternate RSS/Atom feeds this page advertises (threaded to <Seo>). */
   feeds?: { title: string; href: string }[];
   /** A paginated collection's prev/next siblings (threaded to <Seo>). */
@@ -92,6 +101,7 @@ const {
   ogImage,
   noindex,
   jsonLd,
+  structuredData,
   feeds,
   pagination,
   article,
@@ -123,12 +133,22 @@ const integrationPhases = renderIntegrationPhases(
 
 // Organization JSON-LD is emitted site-wide (brief §8); pages add their own
 // graphs (Product, BreadcrumbList…) via the jsonLd prop.
+// A tenant that declares a graph for this page type gets exactly that graph instead.
 const pageGraphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
-const allJsonLd = [
-  organizationLd(tenant, canonicalBase),
-  websiteLd(tenant, canonicalBase),
-  ...pageGraphs,
-];
+const profile = structuredDataProfile(tenant);
+const declaredGraph = profile && structuredData
+  ? composeStructuredData({
+      profile,
+      page: structuredData,
+      tenant,
+      canonicalBase,
+      canonical: canonicalOverride ?? canonicalUrl(path, canonicalBase, tenant.seo),
+      documentTitle: documentTitle(title, seoTitle, tenant.displayName),
+    })
+  : null;
+const allJsonLd = declaredGraph
+  ? [declaredGraph]
+  : [organizationLd(tenant, canonicalBase), websiteLd(tenant, canonicalBase), ...pageGraphs];
 
 const theme = mergeTheme(referenceTheme, tenant.theme_tokens);
 

package/apps/storefront/src/lib/seo/faqItems.ts

@@ -0,0 +1,63 @@
+/**
+ * The question/answer pairs a page visibly carries, for a declared FAQPage node
+ * (lib/seo/structuredData.ts). Derived from the rendered content itself, so the markup can never
+ * claim an answer the page does not show: a heading phrased as a question, answered by the text
+ * up to the next heading. Fewer than two pairs is not an FAQ.
+ */
+import type { ProseSection } from "@/lib/content/prose";
+import { plainText } from "@/lib/content/richtext";
+
+export interface FaqItem {
+  q: string;
+  a: string;
+}
+
+const MIN_PAIRS = 2;
+
+const isQuestion = (text: string) => text.trim().endsWith("?");
+
+function decode(text: string): string {
+  return text
+    .replace(/ /g, " ").replace(/"/g, '"').replace(/&#0?39;|’|’/g, "'")
+    .replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+const textOf = (html: string) => decode(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+
+function atLeastTwo(items: FaqItem[]): FaqItem[] {
+  const answered = items.filter((it) => it.q && it.a);
+  return answered.length >= MIN_PAIRS ? answered : [];
+}
+
+/** FAQ pairs from sanitized body HTML: each question-phrased h2–h4 and the text after it. */
+export function faqFromHtml(html: string | undefined): FaqItem[] {
+  if (!html) return [];
+  const parts = html.split(/(<h[2-4][^>]*>[\s\S]*?<\/h[2-4]>)/i);
+  const items: FaqItem[] = [];
+  for (let i = 1; i < parts.length; i += 2) {
+    const q = textOf(parts[i]!);
+    if (isQuestion(q)) items.push({ q, a: textOf(parts[i + 1] ?? "") });
+  }
+  return atLeastTwo(items);
+}
+
+/** FAQ pairs from structured prose: each question-phrased heading and the paragraphs/lists after it. */
+export function faqFromSections(sections: ProseSection[] | undefined): FaqItem[] {
+  const items: FaqItem[] = [];
+  let current: FaqItem | null = null;
+  for (const section of sections ?? []) {
+    if (section.kind === "heading") {
+      current = isQuestion(section.text) ? { q: section.text.trim(), a: "" } : null;
+      if (current) items.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const text = section.kind === "paragraph"
+      ? plainText(section.text)
+      : section.kind === "list"
+        ? section.items.map(plainText).join(" ")
+        : "";
+    if (text) current.a = current.a ? `${current.a} ${text}` : text;
+  }
+  return atLeastTwo(items);
+}

package/apps/storefront/src/lib/seo/structuredData.ts

@@ -0,0 +1,267 @@
+/**
+ * The declared structured-data profile (`seo.structuredData` in `.tot/config.json`): per page
+ * type, exactly which JSON-LD nodes the page emits, in one `@graph`. A migrated store keeps the
+ * graph its rankings were earned under — the same node types, ids linking them, and the key
+ * fields (name, url, sku, price) a parity check compares — instead of whatever the platform
+ * default happens to emit.
+ *
+ * When a tenant declares a graph for a page type, `composeStructuredData` is the ONLY JSON-LD
+ * that page emits: Layout drops the platform defaults and the page's own graphs, and widget
+ * emitters (Faq.astro) defer to it. A node whose data the page lacks is omitted, never invented.
+ * Pure: pages hand it the data, Layout hands it the tenant and the canonical.
+ */
+import type {
+  CatalogProduct,
+  StructuredDataNodeToken,
+  StructuredDataPageType,
+  TenantConfig,
+} from "@tot/public-runtime";
+import { productLd } from "../jsonld.js";
+import { pageUrlForm } from "./urlForm.js";
+
+type Node = Record<string, unknown>;
+type Profile = NonNullable<NonNullable<TenantConfig["seo"]>["structuredData"]>;
+
+/** What a page knows about itself, for the nodes that describe it. Every field is optional. */
+export interface StructuredDataPage {
+  pageType: StructuredDataPageType;
+  /** The page's primary image, site-relative or absolute. */
+  image?: string | null;
+  author?: { name: string; url?: string } | null;
+  /** The entity's own title (a post or page heading). */
+  headline?: string;
+  description?: string;
+  datePublished?: string;
+  dateModified?: string;
+  product?: CatalogProduct;
+  /** Real sourced `aggregateRating` / `review` (reviewLd output); emitted only when declared. */
+  reviews?: Record<string, unknown>;
+  faq?: { q: string; a: string }[];
+  crumbs?: { label: string; href: string }[];
+  items?: { title: string; url: string }[];
+}
+
+/** The tenant's declared profile, or null when it declares none. */
+export function structuredDataProfile(tenant: Pick<TenantConfig, "seo"> | undefined): Profile | null {
+  return tenant?.seo?.structuredData ?? null;
+}
+
+/**
+ * A product with more than one variant is a `productGroup` when the profile declares that graph;
+ * every other page type maps to itself.
+ */
+export function productPageType(profile: Profile | null, product: CatalogProduct): StructuredDataPageType {
+  return product.variants.length > 1 && profile?.graphs.productGroup ? "productGroup" : "product";
+}
+
+/** The declared node list for a page type; `productGroup` falls back to `product`. */
+export function graphFor(profile: Profile | null, pageType: StructuredDataPageType): StructuredDataNodeToken[] | null {
+  if (!profile) return null;
+  return profile.graphs[pageType] ?? (pageType === "productGroup" ? profile.graphs.product ?? null : null);
+}
+
+const SITE_TOKENS = new Set<StructuredDataNodeToken>(["Organization", "Person", "Organization+Person"]);
+const PAGE_ENTITY_TOKENS = new Set<StructuredDataNodeToken>(["WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage"]);
+
+function absolute(value: string, canonicalBase: string): string {
+  return new URL(value, canonicalBase + "/").toString();
+}
+
+export interface ComposeInput {
+  profile: Profile;
+  page: StructuredDataPage;
+  tenant: TenantConfig;
+  canonicalBase: string;
+  /** The page's absolute canonical URL, already in the declared URL form. */
+  canonical: string;
+  /** The page's full `<title>`. */
+  documentTitle: string;
+}
+
+/** One `@graph` holding exactly the declared nodes the page has data for, or null when the page type declares none. */
+export function composeStructuredData(input: ComposeInput): Node | null {
+  const { profile, page, tenant, canonicalBase, canonical, documentTitle } = input;
+  const tokens = graphFor(profile, page.pageType);
+  if (!tokens) return null;
+  const base = canonicalBase.replace(/\/$/, "");
+  const lang = tenant.locale || "en";
+  const nameOf = (type: "Product" | "ProductGroup" | "Article" | "BlogPosting", own: string | undefined, fallback: "documentTitle" | "title") =>
+    (profile.names?.[type] ?? fallback) === "documentTitle" ? documentTitle : own || documentTitle;
+
+  const siteToken = tokens.find((t) => SITE_TOKENS.has(t));
+  const siteTypes = siteToken ? siteToken.split("+") : [];
+  const siteId = `${base}/#${siteTypes.includes("Person") ? "person" : "organization"}`;
+  const imageUrl = page.image ? absolute(page.image, canonicalBase) : null;
+  const imageId = imageUrl ?? undefined;
+  const pageToken = tokens.find((t) => PAGE_ENTITY_TOKENS.has(t));
+  const pageId = `${canonical}#webpage`;
+  const authorId = page.author ? `${page.author.url ? absolute(page.author.url, canonicalBase) : canonical}#author` : undefined;
+  const ref = (id: string | undefined) => (id ? { "@id": id } : undefined);
+  const pageUrl = (href: string) => pageUrlForm(absolute(href, canonicalBase), tenant.seo);
+
+  const nodes: Node[] = [];
+  for (const token of tokens) {
+    const node = buildNode(token);
+    if (node) nodes.push(node);
+  }
+  return { "@context": "https://schema.org", "@graph": nodes };
+
+  function buildNode(token: StructuredDataNodeToken): Node | null {
+    if (SITE_TOKENS.has(token)) {
+      const logo = tenant.theme_tokens?.brand?.logoLight ?? tenant.theme_tokens?.brand?.ogImage;
+      return {
+        "@type": siteTypes.length > 1 ? siteTypes : siteTypes[0],
+        "@id": siteId,
+        name: tenant.displayName,
+        url: base,
+        ...(logo && siteTypes.includes("Organization") ? { logo: { "@type": "ImageObject", url: absolute(logo, canonicalBase) } } : {}),
+      };
+    }
+    if (PAGE_ENTITY_TOKENS.has(token)) {
+      return {
+        "@type": token,
+        "@id": pageId,
+        url: canonical,
+        name: documentTitle,
+        ...(page.description ? { description: page.description } : {}),
+        isPartOf: { "@id": `${base}/#website` },
+        ...(imageId ? { primaryImageOfPage: { "@id": imageId } } : {}),
+        ...(page.datePublished ? { datePublished: page.datePublished } : {}),
+        ...(page.dateModified ? { dateModified: page.dateModified } : {}),
+        inLanguage: lang,
+      };
+    }
+    switch (token) {
+      case "WebSite":
+        return {
+          "@type": "WebSite",
+          "@id": `${base}/#website`,
+          url: base,
+          name: tenant.displayName,
+          ...(siteToken ? { publisher: { "@id": siteId } } : {}),
+          inLanguage: lang,
+        };
+      case "ImageObject":
+        return imageUrl ? { "@type": "ImageObject", "@id": imageUrl, url: imageUrl, inLanguage: lang } : null;
+      case "Person:author":
+        return page.author
+          ? {
+              "@type": "Person",
+              "@id": authorId,
+              name: page.author.name,
+              ...(page.author.url ? { url: pageUrl(page.author.url) } : {}),
+            }
+          : null;
+      case "Article":
+      case "BlogPosting": {
+        const name = nameOf(token, page.headline, token === "Article" ? "documentTitle" : "title");
+        return {
+          "@type": token,
+          "@id": `${canonical}#richSnippet`,
+          headline: page.headline || name,
+          name,
+          ...(page.description ? { description: page.description } : {}),
+          ...(page.datePublished ? { datePublished: page.datePublished } : {}),
+          ...(page.dateModified ? { dateModified: page.dateModified } : {}),
+          ...(authorId ? { author: { "@id": authorId, name: page.author!.name } } : {}),
+          ...(siteToken ? { publisher: { "@id": siteId } } : {}),
+          ...(imageId ? { image: { "@id": imageId } } : {}),
+          ...(pageToken ? { isPartOf: { "@id": pageId }, mainEntityOfPage: { "@id": pageId } } : {}),
+          inLanguage: lang,
+        };
+      }
+      case "Product":
+        return page.product ? productNode(page.product) : null;
+      case "ProductGroup":
+        return page.product ? productGroupNode(page.product) : null;
+      case "FAQPage":
+        return page.faq?.length
+          ? {
+              "@type": "FAQPage",
+              "@id": `${canonical}#faq`,
+              mainEntity: page.faq.map((it) => ({
+                "@type": "Question",
+                name: it.q,
+                acceptedAnswer: { "@type": "Answer", text: it.a },
+              })),
+            }
+          : null;
+      case "BreadcrumbList":
+        return page.crumbs?.length
+          ? {
+              "@type": "BreadcrumbList",
+              "@id": `${canonical}#breadcrumb`,
+              itemListElement: page.crumbs.map((c, i) => ({
+                "@type": "ListItem",
+                position: i + 1,
+                name: c.label,
+                item: pageUrl(c.href),
+              })),
+            }
+          : null;
+      case "ItemList":
+        return page.items?.length
+          ? {
+              "@type": "ItemList",
+              numberOfItems: page.items.length,
+              itemListElement: page.items.map((it, i) => ({
+                "@type": "ListItem",
+                position: i + 1,
+                name: it.title,
+                url: pageUrlForm(it.url, tenant.seo),
+              })),
+            }
+          : null;
+      default:
+        return null;
+    }
+  }
+
+  function offer(v: CatalogProduct["variants"][number]): Node {
+    return {
+      "@type": "Offer",
+      ...(v.sku ? { sku: v.sku } : {}),
+      price: v.price.toFixed(2),
+      priceCurrency: v.currency,
+      availability: v.inventory.available ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+      url: canonical,
+      ...(siteToken ? { seller: { "@id": siteId } } : {}),
+    };
+  }
+
+  function productNode(p: CatalogProduct): Node {
+    const { "@context": _context, ...ld } = productLd(p, tenant, canonicalBase) as Node;
+    const single = p.variants.length === 1 ? p.variants[0] : undefined;
+    return {
+      ...ld,
+      "@id": `${canonical}#product`,
+      name: nameOf("Product", p.title, "title"),
+      url: canonical,
+      ...(pageToken ? { mainEntityOfPage: { "@id": pageId } } : {}),
+      ...(single ? { offers: offer(single) } : {}),
+      ...(profile.reviews ? page.reviews ?? {} : {}),
+    };
+  }
+
+  function productGroupNode(p: CatalogProduct): Node {
+    const name = nameOf("ProductGroup", p.title, "title");
+    return {
+      "@type": "ProductGroup",
+      "@id": `${canonical}#product`,
+      name,
+      url: canonical,
+      productGroupID: p.handle,
+      ...(p.seo.description || p.description_text ? { description: p.seo.description || p.description_text.slice(0, 300) } : {}),
+      ...(p.vendor ? { brand: { "@type": "Brand", name: p.vendor } } : {}),
+      ...(p.options.length ? { variesBy: p.options.map((o) => o.name) } : {}),
+      ...(pageToken ? { mainEntityOfPage: { "@id": pageId } } : {}),
+      hasVariant: p.variants.map((v) => ({
+        "@type": "Product",
+        name: `${p.title} - ${v.title}`,
+        ...(v.sku ? { sku: v.sku } : {}),
+        offers: offer(v),
+      })),
+      ...(profile.reviews ? page.reviews ?? {} : {}),
+    };
+  }
+}

package/apps/storefront/src/lib/seo/urlForm.ts

@@ -0,0 +1,40 @@
+/**
+ * The tenant's declared URL form (`seo.trailingSlash` in `.tot/config.json`). A migrated store
+ * keeps the URL shape its rankings were earned under: canonicals, og:url, JSON-LD urls, sitemap
+ * locs and platform-generated page links all take the same form. Both forms serve the same
+ * directory-index file on every substrate, so this changes what we ADVERTISE, never what resolves.
+ */
+import type { SeoDeclaration } from "@tot/public-runtime";
+
+/** A last segment with a file extension names a file (`/sitemap.xml`), never a page. */
+const FILE_SEGMENT = /\.[a-z0-9]{1,8}$/i;
+
+function slashPathname(pathname: string): string {
+  if (pathname === "" || pathname.endsWith("/")) return pathname || "/";
+  const last = pathname.slice(pathname.lastIndexOf("/") + 1);
+  return FILE_SEGMENT.test(last) ? pathname : `${pathname}/`;
+}
+
+/**
+ * A page path or absolute page URL in the tenant's declared form. Without `trailingSlash` the
+ * value is returned unchanged. Query and fragment are kept; non-page values (files, `#x`, `?x`,
+ * `mailto:`, protocol-relative) pass through.
+ */
+export function pageUrlForm(value: string, seo: SeoDeclaration | undefined): string {
+  if (!seo?.trailingSlash || !value) return value;
+  if (/^https?:\/\//i.test(value)) {
+    const url = new URL(value);
+    url.pathname = slashPathname(url.pathname);
+    return url.toString();
+  }
+  if (!value.startsWith("/") || value.startsWith("//")) return value;
+  const cut = value.search(/[?#]/);
+  const path = cut < 0 ? value : value.slice(0, cut);
+  const rest = cut < 0 ? "" : value.slice(cut);
+  return slashPathname(path) + rest;
+}
+
+/** The absolute canonical URL for a path-only page path, in the declared form. */
+export function canonicalUrl(path: string, canonicalBase: string, seo: SeoDeclaration | undefined): string {
+  return pageUrlForm(new URL(path, canonicalBase + "/").toString(), seo);
+}

package/apps/storefront/src/lib/storyblok/content-model.ts

@@ -304,6 +304,9 @@ export interface HomeContent {
   /** SEO + social. */
   seoTitle?: string;
   seoDescription?: string;
+  /** The home page's byline author and primary image, for its structured data. */
+  author?: { name: string; url?: string };
+  image?: string;
   /** Commerce home blocks OR marketing blocks — the page branches on tenant
    * siteType/features and renders the matching set. */
   blocks: (HomeBlock | MarketingBlock)[];
@@ -344,6 +347,10 @@ export interface EditorialPage {
   updated?: string;
   /** When true, listed in the footer policy column. */
   isPolicy?: boolean;
+  /** The page's byline author, named by its structured data (a profile's `Person:author`). */
+  author?: { name: string; url?: string };
+  /** The page's primary image, site-relative or absolute (a profile's `ImageObject`). */
+  image?: string;
 }
 
 // Site chrome (header/footer) is the ONE consolidated schema in

package/apps/storefront/src/lib/storyblok/provider.ts

@@ -472,6 +472,8 @@ function mapHome(content: Record<string, any>): HomeContent {
   return {
     seoTitle: content.seoTitle ?? content.seo_title,
     seoDescription: content.seoDescription ?? content.seo_description,
+    author: content.author,
+    image: content.image,
     blocks: blocks as HomeContent["blocks"],
   };
 }
@@ -497,6 +499,8 @@ function mapPage(content: Record<string, any>, slug: string): EditorialPage {
     intro: content.intro,
     updated: content.updated,
     isPolicy: !!content.isPolicy,
+    author: content.author,
+    image: content.image,
   };
 }
 

package/apps/storefront/src/pages/[...slug].astro

@@ -12,6 +12,7 @@ import ProseSections from "@/components/content/ProseSections.astro";
 import ProseToc from "@/components/content/ProseToc.astro";
 import { breadcrumbLd } from "@/lib/jsonld";
 import { truncate } from "@/lib/format";
+import { faqFromHtml, faqFromSections } from "@/lib/seo/faqItems";
 import { rawHtmlPolicy, rawHtmlResponse, rawPageCanonicalUrl } from "@/lib/rawMarketingHtml";
 import { renderRawComplianceTop, renderRawComplianceBottom } from "@/lib/compliance/rawComplianceNotices";
 import { styleGuideAliasRewrite } from "@/lib/styleGuidePaths";
@@ -48,6 +49,10 @@ if (styleGuideTarget !== undefined) {
 // individual posts at the site root — a single-segment slug tries the blog collection
 // before falling through to a raw marketing page or a CMS page. Multi-segment slugs are
 // never posts, so this never shadows a nested marketing/CMS path.
+// A renamed root post's 308 is the same declared blog redirect the publication composition
+// materializes for the blog collection (blog/[slug].astro declares the same source).
+export const MATERIALIZED_REDIRECT_SOURCE = "content/blog/redirects.json";
+
 let blogPostProps: BlogPostViewPropsV1 | null = null;
 if (!slug.includes("/")) {
   const blogSettings = await getBlogSettings(tenant.tenant_id, content);
@@ -140,6 +145,16 @@ const updatedLabel = page?.updated
     path={`/${page!.slug}`}
     ogType="article"
     jsonLd={breadcrumbLd(crumbs, canonicalBase)}
+    structuredData={{
+      pageType: "page",
+      headline: page!.title,
+      image: page!.image,
+      author: page!.author,
+      description,
+      dateModified: page!.updated,
+      faq: structured ? faqFromSections(page!.sections) : faqFromHtml(page!.body_html),
+      crumbs,
+    }}
   >
     <div class="container-prose pt-6">
       <Breadcrumbs crumbs={crumbs} />

package/apps/storefront/src/pages/blog/author/[author].astro

@@ -70,6 +70,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={blogPaths.author(slug)}
   fullBleed
   jsonLd={[crumbs, profileLd, itemListLd]}
+  structuredData={{ pageType: "collection" }}
 >
   <header class:list={["author-hero", { "author-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/blog/category/[category].astro

@@ -48,6 +48,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={path}
   fullBleed
   jsonLd={[crumbs, itemList]}
+  structuredData={{ pageType: "collection" }}
 >
   <header class:list={["blog-hero", { "blog-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/blog/tag/[tag].astro

@@ -46,6 +46,7 @@ const crumbs = breadcrumbLd(trail, canonicalBase);
   path={path}
   fullBleed
   jsonLd={[crumbs, itemList]}
+  structuredData={{ pageType: "collection" }}
 >
   <header class:list={["blog-hero", { "blog-hero--plain": !presentation.hero }]}>
     <div class="blog-shell">

package/apps/storefront/src/pages/collections/[handle].astro

@@ -18,6 +18,7 @@ import Img from "@/components/Img.astro";
 import { parseQuery, buildQueryString } from "@/lib/url";
 import { breadcrumbLd, itemListLd } from "@/lib/jsonld";
 import { truncate } from "@/lib/format";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 import { withBase } from "@/lib/basePath";
 import { isBlankDescriptionHtml, sanitizeDescriptionHtml } from "@/lib/content/sanitizeDescriptionHtml";
 
@@ -43,7 +44,7 @@ const { products, page, pageSize, total, facets } = await tot.listProducts(query
 // sitemap + directory too. Detect it via the UNFILTERED membership total.
 const { total: memberTotal } = await tot.listProducts({ collection: handle, pageSize: 1 });
 const isEmptyCollection = memberTotal === 0;
-const basePath = `/collections/${handle}`;
+const basePath = pageUrlForm(`/collections/${handle}`, tenant.seo);
 // Tenant-prefixed page path for facet/sort/pagination, which build links by
 // string-concatenating onto this base (so they stay inside a path-routed
 // tenant). `basePath` itself stays unprefixed for the SEO canonical `path`,
@@ -97,6 +98,12 @@ if (query.priceMin != null || query.priceMax != null) {
     breadcrumbLd(crumbs, canonicalBase),
     itemListLd(products, canonicalBase, (page - 1) * pageSize),
   ]}
+  structuredData={{
+    pageType: "collection",
+    description: collection.seo.description || undefined,
+    crumbs,
+    items: products.map((p) => ({ title: p.title, url: new URL(`/products/${p.handle}`, canonicalBase + "/").toString() })),
+  }}
 >
   {/* Collection hero */}
   <header class="bg-[var(--color-primary)] text-[var(--color-primary-contrast)]">

package/apps/storefront/src/pages/collections/index.astro

@@ -34,6 +34,7 @@ const crumbs = siteTrail(
   description={`Browse every collection at ${tenant.displayName}.`}
   path="/collections"
   jsonLd={breadcrumbLd(crumbs, canonicalBase)}
+  structuredData={{ pageType: "collection" }}
 >
   <div class="container-prose pt-6">
     <Breadcrumbs crumbs={crumbs} />

package/apps/storefront/src/pages/index.astro

@@ -182,6 +182,14 @@ const homeSectionWidgets = marketing
   path="/"
   ogType="website"
   fullBleed={marketing}
+  structuredData={{
+    pageType: "home",
+    headline: home.seoTitle ?? tenant.displayName,
+    description: home.seoDescription,
+    image: home.image,
+    author: home.author,
+    faq: home.blocks.flatMap((block) => (block.component === "faq" ? block.items : [])),
+  }}
 >
   {marketing && <MarketingBlocks blocks={marketingBlocks} basePath={basePath} />}
   {

package/apps/storefront/src/pages/products/[handle].astro

@@ -45,6 +45,8 @@ import { truncate } from "@/lib/format";
 import { productLd, breadcrumbLd, reviewLd } from "@/lib/jsonld";
 import { isUsableImageUrl } from "@/lib/placeholder";
 import { withBase } from "@/lib/basePath";
+import { productPageType, structuredDataProfile } from "@/lib/seo/structuredData";
+import { pageUrlForm } from "@/lib/seo/urlForm";
 import { shippingPolicyPath } from "@/lib/commerce/shippingPolicy";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
 import { getRegistryService } from "@/lib/apps/registryAccess.js";
@@ -155,7 +157,7 @@ const flavorTags = (product.tags ?? [])
   .map((t) => ({
     label: t.slice(3).trim(),
     href: flavorCollection
-      ? `/collections/${flavorCollection}?tag=${encodeURIComponent(t)}`
+      ? pageUrlForm(`/collections/${flavorCollection}?tag=${encodeURIComponent(t)}`, tenant.seo)
       : undefined,
   }))
   .filter((f) => f.label);
@@ -299,6 +301,13 @@ const productJsonLd: Record<string, unknown> = {
   ...reviewLd(reviewAvg, reviewCount, reviews),
 };
 const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
+const structuredData = {
+  pageType: productPageType(structuredDataProfile(tenant), product),
+  image: ogPrimary && isUsableImageUrl(ogPrimary.url, ogPrimary.rehosted) ? ogPrimary.url : null,
+  product,
+  reviews: reviewLd(reviewAvg, reviewCount, reviews),
+  crumbs,
+};
 ---
 
 <Layout
@@ -309,6 +318,7 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
   ogImage={ogImage}
   noindex={isDraft}
   jsonLd={jsonLd}
+  structuredData={structuredData}
 >
   <div class="container-prose pt-6">
     <Breadcrumbs crumbs={crumbs} />

package/apps/storefront/src/pages/sitemap.xml.ts

@@ -25,6 +25,7 @@ import {
   rootOwnsDiscoveryPathV1,
 } from "@/lib/publication/mountedDiscovery.js";
 import { collectionPathsV1, blogPathOptsV1 } from "@/lib/blog/collectionPaths.js";
+import { pageUrlForm } from "@/lib/seo/urlForm.js";
 
 interface SitemapUrl {
   loc: string;
@@ -154,7 +155,7 @@ export async function GET(context: APIContext): Promise<Response> {
 ${urls
   .map(
     (u) =>
-      `  <url>\n    <loc>${escapeXml(u.loc)}</loc>${
+      `  <url>\n    <loc>${escapeXml(pageUrlForm(u.loc, tenant.seo))}</loc>${
         u.lastmod ? `\n    <lastmod>${escapeXml(u.lastmod)}</lastmod>` : ""
       }\n  </url>`,
   )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.74",
+  "version": "2.4.75",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/declared-config.mjs

@@ -17,7 +17,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -30,6 +30,115 @@ export const FEATURE_KEYS = [
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** Every `seo` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SEO_KEYS = Object.freeze(["trailingSlash", "structuredData"]);
+
+/** Every `seo.structuredData` key. */
+export const STRUCTURED_DATA_KEYS = Object.freeze(["graphs", "names", "reviews"]);
+
+/**
+ * The page types a structured-data profile declares a graph for. `productGroup` is a product
+ * with more than one variant; without its own graph it renders the `product` graph.
+ * `collection` covers every archive: a catalog collection, the collections index, and the
+ * blog index and its category/tag/author archives.
+ */
+export const STRUCTURED_DATA_PAGE_TYPES = Object.freeze([
+  "home", "product", "productGroup", "collection", "post", "page",
+]);
+
+/**
+ * The JSON-LD nodes a profile may list, as the `@type` each emits (a multi-type node joins its
+ * sorted types with `+`, the key a parity snapshot records). `Person:author` is the page's
+ * author; every other Organization/Person token is the site entity.
+ */
+export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
+  "Organization", "Person", "Organization+Person",
+  "WebSite", "ImageObject",
+  "WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage",
+  "Person:author",
+  "Article", "BlogPosting",
+  "Product", "ProductGroup",
+  "FAQPage", "BreadcrumbList", "ItemList",
+]);
+
+/** Node types whose `name` a profile may source, and the sources. */
+export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
+export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * What is wrong with a declared `seo` value, one sentence per problem; `[]` when it is valid.
+ * A profile that names a node or page type the renderer does not build is refused whole: a
+ * partly-applied profile emits a graph nobody declared.
+ *
+ * @param {unknown} seo
+ * @returns {string[]}
+ */
+export function seoDeclarationProblems(seo) {
+  if (!isPlainObject(seo)) return ["`seo` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (seo);
+  for (const key of Object.keys(source)) {
+    if (!SEO_KEYS.includes(key)) problems.push(`\`seo.${key}\` is not a seo key (${SEO_KEYS.join(", ")})`);
+  }
+  if (source.trailingSlash !== undefined && typeof source.trailingSlash !== "boolean") {
+    problems.push("`seo.trailingSlash` must be true or false");
+  }
+  const sd = source.structuredData;
+  if (sd === undefined) return problems;
+  if (!isPlainObject(sd)) return [...problems, "`seo.structuredData` must be an object"];
+  const data = /** @type {Record<string, unknown>} */ (sd);
+  for (const key of Object.keys(data)) {
+    if (!STRUCTURED_DATA_KEYS.includes(key)) {
+      problems.push(`\`seo.structuredData.${key}\` is not a structuredData key (${STRUCTURED_DATA_KEYS.join(", ")})`);
+    }
+  }
+  if (!isPlainObject(data.graphs) || Object.keys(/** @type {object} */ (data.graphs)).length === 0) {
+    problems.push("`seo.structuredData.graphs` must map at least one page type to its node list");
+  } else {
+    for (const [pageType, tokens] of Object.entries(/** @type {Record<string, unknown>} */ (data.graphs))) {
+      const at = `seo.structuredData.graphs.${pageType}`;
+      if (!STRUCTURED_DATA_PAGE_TYPES.includes(pageType)) {
+        problems.push(`\`${at}\`: unknown page type (${STRUCTURED_DATA_PAGE_TYPES.join(", ")})`);
+        continue;
+      }
+      if (!Array.isArray(tokens) || tokens.length === 0) {
+        problems.push(`\`${at}\` must be a non-empty array of node types`);
+        continue;
+      }
+      const seen = new Set();
+      for (const token of tokens) {
+        if (typeof token !== "string" || !STRUCTURED_DATA_NODE_TOKENS.includes(token)) {
+          problems.push(`\`${at}\`: ${JSON.stringify(token)} is not a node type the renderer builds (${STRUCTURED_DATA_NODE_TOKENS.join(", ")})`);
+        } else if (seen.has(token)) {
+          problems.push(`\`${at}\` lists ${token} twice`);
+        }
+        seen.add(token);
+      }
+    }
+  }
+  if (data.names !== undefined) {
+    if (!isPlainObject(data.names)) {
+      problems.push("`seo.structuredData.names` must map a node type to documentTitle or title");
+    } else {
+      for (const [type, from] of Object.entries(/** @type {Record<string, unknown>} */ (data.names))) {
+        if (!STRUCTURED_DATA_NAMED_TYPES.includes(type)) {
+          problems.push(`\`seo.structuredData.names.${type}\`: only ${STRUCTURED_DATA_NAMED_TYPES.join(", ")} take a declared name`);
+        } else if (typeof from !== "string" || !STRUCTURED_DATA_NAME_SOURCES.includes(from)) {
+          problems.push(`\`seo.structuredData.names.${type}\` must be one of ${STRUCTURED_DATA_NAME_SOURCES.join(", ")}`);
+        }
+      }
+    }
+  }
+  if (data.reviews !== undefined && typeof data.reviews !== "boolean") {
+    problems.push("`seo.structuredData.reviews` must be true or false");
+  }
+  return problems;
+}
+
+
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
   ruleProfile: "checkout compliance rules",
@@ -361,6 +470,11 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
     out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
   }
+  if (config.seo !== undefined) {
+    for (const problem of seoDeclarationProblems(config.seo)) {
+      out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
+    }
+  }
   return out;
 }
 

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -1,7 +1,7 @@
 /** Types for the dependency-free declared-tenant-config module (declared-tenant-config.mjs). */
 import type { TenantConfig } from "./tenant.js";
 
-export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds";
+export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds" | "seo";
 export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
 
 export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];
@@ -9,6 +9,13 @@ export const TOT_CONFIG_KEYS: readonly string[];
 export const COMPLIANCE_KEYS: readonly string[];
 export const FEATURE_KEYS: readonly string[];
 export const SITE_TYPES_LIST: readonly string[];
+export const SEO_KEYS: readonly string[];
+export const STRUCTURED_DATA_KEYS: readonly string[];
+export const STRUCTURED_DATA_PAGE_TYPES: readonly import("./tenant.js").StructuredDataPageType[];
+export const STRUCTURED_DATA_NODE_TOKENS: readonly import("./tenant.js").StructuredDataNodeToken[];
+export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
+export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
+export function seoDeclarationProblems(seo: unknown): string[];
 export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
 export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;
 export function applyDeclaredTenantConfig<T extends Partial<Pick<TenantConfig, DeclaredTenantConfigField>>>(

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -25,6 +25,7 @@ export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
   "capabilities",
   "features",
   "embeds",
+  "seo",
 ]);
 
 /**
@@ -73,11 +74,116 @@ export const FEATURE_KEYS = Object.freeze([
 /** Every `siteType` value (SiteType, tenant.ts). */
 export const SITE_TYPES_LIST = Object.freeze(["commerce", "marketing"]);
 
+/** Every `seo` key (SeoDeclaration, tenant.ts). */
+export const SEO_KEYS = Object.freeze(["trailingSlash", "structuredData"]);
+
+/** Every `seo.structuredData` key. */
+export const STRUCTURED_DATA_KEYS = Object.freeze(["graphs", "names", "reviews"]);
+
+/**
+ * The page types a structured-data profile declares a graph for. `productGroup` is a product
+ * with more than one variant; without its own graph it renders the `product` graph.
+ * `collection` covers every archive: a catalog collection, the collections index, and the
+ * blog index and its category/tag/author archives.
+ */
+export const STRUCTURED_DATA_PAGE_TYPES = Object.freeze([
+  "home", "product", "productGroup", "collection", "post", "page",
+]);
+
+/**
+ * The JSON-LD nodes a profile may list, as the `@type` each emits (a multi-type node joins its
+ * sorted types with `+`, the key a parity snapshot records). `Person:author` is the page's
+ * author; every other Organization/Person token is the site entity.
+ */
+export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
+  "Organization", "Person", "Organization+Person",
+  "WebSite", "ImageObject",
+  "WebPage", "ItemPage", "CollectionPage", "AboutPage", "ContactPage",
+  "Person:author",
+  "Article", "BlogPosting",
+  "Product", "ProductGroup",
+  "FAQPage", "BreadcrumbList", "ItemList",
+]);
+
+/** Node types whose `name` a profile may source, and the sources. */
+export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
+export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
+
 const SITE_TYPES = new Set(SITE_TYPES_LIST);
 
 const isPlainObject = (value) =>
   value !== null && typeof value === "object" && !Array.isArray(value);
 
+/**
+ * What is wrong with a declared `seo` value, one sentence per problem; `[]` when it is valid.
+ * A profile that names a node or page type the renderer does not build is refused whole: a
+ * partly-applied profile emits a graph nobody declared.
+ *
+ * @param {unknown} seo
+ * @returns {string[]}
+ */
+export function seoDeclarationProblems(seo) {
+  if (!isPlainObject(seo)) return ["`seo` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (seo);
+  for (const key of Object.keys(source)) {
+    if (!SEO_KEYS.includes(key)) problems.push(`\`seo.${key}\` is not a seo key (${SEO_KEYS.join(", ")})`);
+  }
+  if (source.trailingSlash !== undefined && typeof source.trailingSlash !== "boolean") {
+    problems.push("`seo.trailingSlash` must be true or false");
+  }
+  const sd = source.structuredData;
+  if (sd === undefined) return problems;
+  if (!isPlainObject(sd)) return [...problems, "`seo.structuredData` must be an object"];
+  const data = /** @type {Record<string, unknown>} */ (sd);
+  for (const key of Object.keys(data)) {
+    if (!STRUCTURED_DATA_KEYS.includes(key)) {
+      problems.push(`\`seo.structuredData.${key}\` is not a structuredData key (${STRUCTURED_DATA_KEYS.join(", ")})`);
+    }
+  }
+  if (!isPlainObject(data.graphs) || Object.keys(/** @type {object} */ (data.graphs)).length === 0) {
+    problems.push("`seo.structuredData.graphs` must map at least one page type to its node list");
+  } else {
+    for (const [pageType, tokens] of Object.entries(/** @type {Record<string, unknown>} */ (data.graphs))) {
+      const at = `seo.structuredData.graphs.${pageType}`;
+      if (!STRUCTURED_DATA_PAGE_TYPES.includes(pageType)) {
+        problems.push(`\`${at}\`: unknown page type (${STRUCTURED_DATA_PAGE_TYPES.join(", ")})`);
+        continue;
+      }
+      if (!Array.isArray(tokens) || tokens.length === 0) {
+        problems.push(`\`${at}\` must be a non-empty array of node types`);
+        continue;
+      }
+      const seen = new Set();
+      for (const token of tokens) {
+        if (typeof token !== "string" || !STRUCTURED_DATA_NODE_TOKENS.includes(token)) {
+          problems.push(`\`${at}\`: ${JSON.stringify(token)} is not a node type the renderer builds (${STRUCTURED_DATA_NODE_TOKENS.join(", ")})`);
+        } else if (seen.has(token)) {
+          problems.push(`\`${at}\` lists ${token} twice`);
+        }
+        seen.add(token);
+      }
+    }
+  }
+  if (data.names !== undefined) {
+    if (!isPlainObject(data.names)) {
+      problems.push("`seo.structuredData.names` must map a node type to documentTitle or title");
+    } else {
+      for (const [type, from] of Object.entries(/** @type {Record<string, unknown>} */ (data.names))) {
+        if (!STRUCTURED_DATA_NAMED_TYPES.includes(type)) {
+          problems.push(`\`seo.structuredData.names.${type}\`: only ${STRUCTURED_DATA_NAMED_TYPES.join(", ")} take a declared name`);
+        } else if (typeof from !== "string" || !STRUCTURED_DATA_NAME_SOURCES.includes(from)) {
+          problems.push(`\`seo.structuredData.names.${type}\` must be one of ${STRUCTURED_DATA_NAME_SOURCES.join(", ")}`);
+        }
+      }
+    }
+  }
+  if (data.reviews !== undefined && typeof data.reviews !== "boolean") {
+    problems.push("`seo.structuredData.reviews` must be true or false");
+  }
+  return problems;
+}
+
 /**
  * The declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
  * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
@@ -88,7 +194,7 @@ export function declaredTenantConfig(config) {
   /** @type {Record<string, unknown>} */
   const out = {};
   if (!isPlainObject(config)) return out;
-  const { displayName, siteType, compliance, capabilities, features, embeds } = /** @type {Record<string, unknown>} */ (config);
+  const { displayName, siteType, compliance, capabilities, features, embeds, seo } = /** @type {Record<string, unknown>} */ (config);
   // The store's name as visitors read it: the `<title>` suffix, og:site_name,
   // Organization JSON-LD, breadcrumbs, the default blog heading, the copyright line.
   if (typeof displayName === "string" && displayName.trim()) out.displayName = displayName.trim();
@@ -97,6 +203,8 @@ export function declaredTenantConfig(config) {
   if (isPlainObject(capabilities)) out.capabilities = capabilities;
   if (isPlainObject(features)) out.features = features;
   if (Array.isArray(embeds) && embeds.every((slug) => typeof slug === "string")) out.embeds = embeds;
+  // URL form and the structured-data profile: refused whole when any part is malformed.
+  if (seo !== undefined && seoDeclarationProblems(seo).length === 0) out.seo = seo;
   return out;
 }
 

package/packages/public-runtime/src/tenant.ts

@@ -750,6 +750,46 @@ export interface TenantConfig {
    * `none` are ever set. It reaches the browser through the server-stamped plan.
    */
   euUkVisitors?: Exclude<EuUkVisitorPolicy, "count-only">;
+  /**
+   * URL form and structured data, declared in `.tot/config.json` (validated by
+   * `seoDeclarationProblems`, declared-tenant-config.mjs). A migrated store keeps the
+   * canonical URL shape and the JSON-LD graph its rankings were earned under.
+   */
+  seo?: SeoDeclaration;
+}
+
+/** Page types a structured-data profile declares a graph for (STRUCTURED_DATA_PAGE_TYPES). */
+export type StructuredDataPageType = "home" | "product" | "productGroup" | "collection" | "post" | "page";
+
+/** JSON-LD nodes a profile may list (STRUCTURED_DATA_NODE_TOKENS). */
+export type StructuredDataNodeToken =
+  | "Organization" | "Person" | "Organization+Person"
+  | "WebSite" | "ImageObject"
+  | "WebPage" | "ItemPage" | "CollectionPage" | "AboutPage" | "ContactPage"
+  | "Person:author"
+  | "Article" | "BlogPosting"
+  | "Product" | "ProductGroup"
+  | "FAQPage" | "BreadcrumbList" | "ItemList";
+
+export interface SeoDeclaration {
+  /**
+   * Canonicals, og:url, JSON-LD urls, sitemap locs and platform-generated page links end in
+   * `/` (`/products/foo/`). Absent or false ⇒ no trailing slash (`/products/foo`).
+   */
+  trailingSlash?: boolean;
+  /**
+   * The structured-data profile. When present it is the ONLY JSON-LD a declared page type
+   * emits: one `@graph` holding exactly the listed nodes, in order. A node whose data the
+   * page lacks (no image, no author, no FAQ) is omitted. A page type without a graph keeps
+   * the platform default.
+   */
+  structuredData?: {
+    graphs: Partial<Record<StructuredDataPageType, StructuredDataNodeToken[]>>;
+    /** Where a node's `name` comes from: the page's `<title>` or the entity's own title. */
+    names?: Partial<Record<"Product" | "ProductGroup" | "Article" | "BlogPosting", "documentTitle" | "title">>;
+    /** Emit real sourced aggregateRating/review on Product. Absent ⇒ false. */
+    reviews?: boolean;
+  };
 }
 
 /**