@tokenoftrust/storefront-runner 2.4.73 → 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

@@ -20,10 +20,14 @@ interface Props {
   pagePosts: BlogPostSummary[];
   page: number;
   totalPages: number;
+  /** `BlogSettings.postsAtRoot` — see `collectionPaths.js`'s `blogPathOptsV1`. */
+  postsAtRoot?: boolean;
 }
 
-const { basePath, canonicalBase, copy, presentation, tags, pagePosts, page, totalPages } = Astro.props;
-const blogPaths = collectionPathsV1(Astro.locals, "blog");
+const {
+  basePath, canonicalBase, copy, presentation, tags, pagePosts, page, totalPages, postsAtRoot,
+} = Astro.props;
+const blogPaths = collectionPathsV1(Astro.locals, "blog", postsAtRoot ? { postBase: "" } : {});
 const showTopics = presentation.topics && tags.length > 0;
 
 const href = (path: string) => `${basePath}${path}` || "/";
@@ -56,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

@@ -0,0 +1,156 @@
+---
+/**
+ * The post article view — rendered by `pages/blog/[slug].astro` at its usual
+ * `/blog/<slug>` URL, and by `pages/[...slug].astro` at the site root when the
+ * tenant declares `BlogSettings.postsAtRoot`. Both callers resolve their props
+ * through `@/lib/blog/postView.js`'s `loadBlogPostViewV1`, so the markup, byline,
+ * paywall gate and structured data are identical regardless of which URL served
+ * the request.
+ */
+import Layout from "@/layouts/Layout.astro";
+import Breadcrumbs from "@/components/Breadcrumbs.astro";
+import BlogPaywall from "@/components/blog/BlogPaywall.astro";
+import ReactionBar from "@/components/blog/ReactionBar.astro";
+import ShareRow from "@/components/blog/ShareRow.astro";
+import { languageLabel } from "@/lib/i18n.js";
+import type { BlogPostViewPropsV1 } from "@/lib/blog/postView.js";
+
+type Props = BlogPostViewPropsV1;
+
+const {
+  post, path, bodyHtml, gated, unlock, next, loginHref, viewer, presentation, author,
+  authorHref, authorUrl, tagLinks, articleLd, trail, crumbs, blogHref, share, translationLinks,
+  alternates, lang,
+} = Astro.props;
+---
+
+<Layout
+  title={post.seoTitle || post.title}
+  description={post.description}
+  path={path}
+  ogType="article"
+  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,
+    author: authorUrl,
+    section: post.categories[0],
+    tags: post.tags,
+  }}
+  imageAlt={post.featuredImage?.alt}
+  imageWidth={post.featuredImage?.width}
+  imageHeight={post.featuredImage?.height}
+  canonicalOverride={post.canonicalUrl}
+  alternates={alternates}
+  lang={lang}
+>
+  <article class="article-shell">
+    <Breadcrumbs crumbs={trail} class="breadcrumbs" />
+    <header>
+      {presentation.postEyebrow && post.tags[0] && <p class="eyebrow eyebrow--tick">{post.tags[0]}</p>}
+      <h1>{post.title}</h1>
+      {presentation.dek && post.excerpt && <p class="dek">{post.excerpt}</p>}
+      <div class="byline">
+        {author && <span>By {authorHref
+          ? <a href={authorHref} class="byline-author" rel="author">{author}</a>
+          : <span class="byline-author">{author}</span>}</span>}
+        {author && <span aria-hidden="true">·</span>}
+        <time datetime={post.publishedAt}>{new Date(post.publishedAt).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}</time>
+      </div>
+      {translationLinks.length > 1 && (
+        <nav class="lang-switcher" aria-label="Available languages">
+          {translationLinks.map(({ code, href, current }) => (
+            <a hreflang={code} href={href} aria-current={current ? "true" : undefined}>
+              {languageLabel(code)}
+            </a>
+          ))}
+        </nav>
+      )}
+    </header>
+    {post.featuredImage && (
+      <img
+        class="featured"
+        src={post.featuredImage.src}
+        alt={post.featuredImage.alt}
+        width={post.featuredImage.width}
+        height={post.featuredImage.height}
+        fetchpriority="high"
+        decoding="async"
+      />
+    )}
+    <div class:list={["article-grid", { "article-grid--single": !presentation.aside }]}>
+      {presentation.aside && (
+        <aside>
+          <a href={blogHref}>← All articles</a>
+          {tagLinks.length > 0 && <div class="article-tags">{tagLinks.map((tag) => tag.href ? <a href={tag.href}>{tag.label}</a> : <span>{tag.label}</span>)}</div>}
+        </aside>
+      )}
+      <div class="blog-main">
+        <div class="blog-body" set:html={bodyHtml}></div>
+        {gated && !unlock && (
+          <BlogPaywall access={post.access ?? "authenticated"} next={next} signedIn={!!viewer} loginHref={loginHref} />
+        )}
+        {!presentation.aside && tagLinks.length > 0 && (
+          <ul class="post-tags" aria-label="Tags">
+            {tagLinks.map((tag) => <li>{tag.href ? <a href={tag.href}>{tag.label}</a> : <span>{tag.label}</span>}</li>)}
+          </ul>
+        )}
+        <ShareRow links={share} />
+      </div>
+    </div>
+    {presentation.reactions && <ReactionBar collection="blog" slug={post.slug} />}
+  </article>
+</Layout>
+
+<style>
+  .article-shell { width: min(1120px, calc(100% - 2rem)); margin-inline: auto; padding-block: clamp(2rem, 5vw, 5rem); }
+  .article-shell :global(.breadcrumbs) { font-size: .84rem; }
+  .article-shell :global(.breadcrumbs a) { color: var(--color-accent-ink); font-weight: 700; }
+  header { max-width: 880px; margin: clamp(2.5rem, 6vw, 5rem) auto clamp(2rem, 5vw, 3.5rem); text-align: center; }
+  header .eyebrow { justify-content: center; }
+  h1 { margin-top: .9rem; font-size: clamp(2.5rem, 6vw, 5rem); line-height: 1.02; }
+  .dek { max-width: 68ch; margin: 1.5rem auto 0; color: var(--color-muted); font-size: clamp(1rem, 2vw, 1.2rem); }
+  .byline { display: flex; justify-content: center; gap: .55rem; margin-top: 1.35rem; color: var(--color-muted); font-size: .85rem; }
+  .byline-author { color: var(--color-accent-ink); font-weight: 700; text-decoration: none; }
+  .byline-author:hover { text-decoration: underline; text-underline-offset: .18em; }
+  .lang-switcher { display: flex; flex-wrap: wrap; justify-content: center; gap: .4rem; margin-top: 1.1rem; }
+  .lang-switcher a { padding: .28rem .6rem; border: 1px solid var(--color-border); border-radius: var(--radius-full); color: var(--color-muted); font-size: .78rem; font-weight: 600; text-decoration: none; }
+  .lang-switcher a:hover { color: var(--color-accent-ink); border-color: var(--color-accent); }
+  .lang-switcher a[aria-current="true"] { color: var(--color-accent-ink); border-color: var(--color-accent); background: var(--color-surface); }
+  .featured { display: block; width: 100%; max-height: 620px; object-fit: cover; border-radius: var(--radius-lg); box-shadow: var(--shadow-md); }
+  .article-grid { display: grid; grid-template-columns: 190px minmax(0, 720px); justify-content: center; gap: clamp(2rem, 6vw, 5rem); margin-top: clamp(3rem, 7vw, 5.5rem); }
+  aside { align-self: start; position: sticky; top: 7rem; }
+  aside > a { color: var(--color-accent-ink); font-size: .88rem; font-weight: 700; }
+  .article-grid--single { grid-template-columns: minmax(0, 720px); }
+  .article-tags { display: flex; flex-wrap: wrap; gap: .45rem; margin-top: 1.2rem; }
+  .article-tags > *, .post-tags :is(a, span) { padding: .3rem .55rem; border: 1px solid var(--color-border); border-radius: var(--radius-full); color: var(--color-muted); font-size: .7rem; text-decoration: none; }
+  .article-tags a:hover, .post-tags a:hover { color: var(--color-accent-ink); border-color: var(--color-accent); }
+  .post-tags { display: flex; flex-wrap: wrap; gap: .45rem; margin: 2rem 0 0; padding: 0; list-style: none; }
+  .blog-main { min-width: 0; }
+  .blog-body { min-width: 0; font-size: 1.05rem; line-height: 1.78; }
+  .blog-body :global(p), .blog-body :global(ul), .blog-body :global(ol), .blog-body :global(blockquote), .blog-body :global(figure), .blog-body :global(table), .blog-body :global(pre) { margin-block: 1.25rem; }
+  .blog-body :global(h2), .blog-body :global(h3), .blog-body :global(h4) { scroll-margin-top: 7rem; margin: 2.8rem 0 1rem; line-height: 1.18; }
+  .blog-body :global(h2) { font-size: clamp(1.75rem, 3vw, 2.35rem); }
+  .blog-body :global(h3) { font-size: clamp(1.35rem, 2.4vw, 1.75rem); }
+  .blog-body :global(a) { color: var(--color-accent-ink); text-decoration: underline; text-underline-offset: .18em; }
+  .blog-body :global(ul), .blog-body :global(ol) { padding-left: 1.4rem; }
+  .blog-body :global(li) { margin-block: .45rem; }
+  .blog-body :global(blockquote) { padding: .8rem 1.25rem; border-left: 4px solid var(--color-accent); background: var(--color-surface); color: var(--color-muted); }
+  .blog-body :global(img) { display: block; width: auto; max-width: 100%; margin-inline: auto; border-radius: var(--radius-md); }
+  .blog-body :global(figcaption) { margin-top: .5rem; color: var(--color-muted); text-align: center; font-size: .78rem; }
+  .blog-body :global(table) { display: block; width: 100%; overflow-x: auto; border-collapse: collapse; }
+  .blog-body :global(th), .blog-body :global(td) { padding: .7rem; border: 1px solid var(--color-border); text-align: left; }
+  @media (max-width: 760px) { .article-grid { grid-template-columns: 1fr; } aside { position: static; } .article-tags { display: none; } }
+</style>

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/blog/collectionPaths.ts

@@ -11,6 +11,7 @@ import {
   type PublicationCollectionV1,
   type PublicationRoutePlanV1,
 } from "@tot/public-runtime";
+import type { BlogSettings } from "./types.js";
 
 export interface CollectionPathsV1 {
   /** The collection index, page 1. */
@@ -23,10 +24,21 @@ export interface CollectionPathsV1 {
   rss: string;
 }
 
-/** The collection paths for the space the request resolved to (the root space otherwise). */
+/**
+ * The collection paths for the space the request resolved to (the root space otherwise).
+ *
+ * `opts.postBase`, when given, replaces the collection's declared base for the `post` route
+ * only — every other route (index, page, author, category, tag, rss) keeps resolving from the
+ * manifest as before. This is the one constructor a tenant's declared
+ * `BlogSettings.postsAtRoot` goes through (see `./types.ts`): callers pass `postBase: ""` to
+ * serve posts at the mount root while the archive stays at its usual base. Still a single
+ * spelling of the path shape — never a second one — because every call still ends in
+ * `publicationCollectionPathV1`.
+ */
 export function collectionPathsV1(
   locals: { publicationRoute?: PublicationRoutePlanV1 },
   collection: PublicationCollectionV1,
+  opts?: { postBase?: string },
 ): CollectionPathsV1 {
   const plan = locals.publicationRoute;
   const manifest = plan && plan.action === "render" ? plan.manifest : null;
@@ -34,13 +46,22 @@ export function collectionPathsV1(
   const base = publicationCollectionBaseV1(manifest, collection);
   const path = (route: Parameters<typeof publicationCollectionPathV1>[2]) =>
     publicationCollectionPathV1(mount, base, route);
+  const postBase = opts?.postBase;
   return {
     index: path({ kind: "index" }),
     page: (page) => path({ kind: "page", page }),
-    post: (slug) => path({ kind: "post", slug }),
+    post: (slug) =>
+      postBase !== undefined
+        ? publicationCollectionPathV1(mount, postBase, { kind: "post", slug })
+        : path({ kind: "post", slug }),
     author: (slug) => path({ kind: "author", slug }),
     category: (slug) => path({ kind: "category", slug }),
     tag: (slug) => path({ kind: "tag", slug }),
     rss: path({ kind: "rss" }),
   };
 }
+
+/** `collectionPathsV1`'s `postBase` override for `/blog`, from the tenant's own declared settings. */
+export function blogPathOptsV1(settings: BlogSettings | null | undefined): { postBase?: string } {
+  return settings?.postsAtRoot ? { postBase: "" } : {};
+}

package/apps/storefront/src/lib/blog/postView.ts

@@ -0,0 +1,141 @@
+/**
+ * The resolved view for one blog post — the frontmatter `pages/blog/[slug].astro` used to compute
+ * inline, factored out so a SECOND route can serve the same post at a different URL shape.
+ * `pages/[...slug].astro` calls this when the tenant declares `BlogSettings.postsAtRoot` (see
+ * `./types.js`), so a root-level request renders the identical article the `/blog/<slug>` route
+ * would, through the one resolver rather than a second re-implementation.
+ */
+import type { AstroGlobal } from "astro";
+import { getBlogPost, getBlogSettings, listBlogPosts, resolveBlogRedirect } from "./provider.js";
+import { authorSlug, categorySlug, getTranslations } from "./collection.js";
+import {
+  bylineAuthor,
+  resolveBlogPresentation,
+  shareLinks,
+  type BlogPresentation,
+  type ShareLink,
+} from "./presentation.js";
+import { homeCrumbLabel, siteTrail, type Crumb } from "@/lib/breadcrumbs.js";
+import { viewerHasBlogAccess } from "./access.js";
+import { articleBodyHtml } from "./teaser.js";
+import { readViewerSession, safeNext } from "@/lib/auth/route.js";
+import { buildAlternates, type Alternate } from "@/lib/seo/alternates.js";
+import { breadcrumbLd, blogPostingLd } from "@/lib/jsonld.js";
+import { collectionPathsV1, blogPathOptsV1 } from "./collectionPaths.js";
+import type { BlogPost } from "./types.js";
+import type { SessionRecord } from "@/lib/auth/session.js";
+
+export interface BlogPostViewPropsV1 {
+  post: BlogPost;
+  /** Tenant-relative path this post actually resolved at (root or `/blog/<slug>`). */
+  path: string;
+  bodyHtml: string;
+  gated: boolean;
+  unlock: boolean;
+  next: string;
+  loginHref: string;
+  viewer: SessionRecord | null;
+  canonical: string;
+  presentation: BlogPresentation;
+  author: string | null;
+  authorHref: string | null;
+  authorUrl: string | undefined;
+  tagLinks: { label: string; href: string | null }[];
+  articleLd: ReturnType<typeof blogPostingLd>;
+  trail: Crumb[];
+  crumbs: ReturnType<typeof breadcrumbLd>;
+  blogHref: string;
+  share: ShareLink[];
+  translationLinks: { code: string; href: string; current: boolean }[];
+  alternates: Alternate[];
+  lang: string | undefined;
+}
+
+export type BlogPostViewResultV1 =
+  | { status: "not_found" }
+  | { status: "redirect"; to: string }
+  | { status: "ok"; props: BlogPostViewPropsV1 };
+
+/** Resolve one post, by slug, into everything `BlogPostArticle.astro` renders. */
+export async function loadBlogPostViewV1(Astro: AstroGlobal, slug: string): Promise<BlogPostViewResultV1> {
+  const { tenant, canonicalBase, basePath, content, publicationTimestamp } = Astro.locals;
+  const blogSettings = await getBlogSettings(tenant.tenant_id, content);
+  const blogPaths = collectionPathsV1(Astro.locals, "blog", blogPathOptsV1(blogSettings));
+  const post = await getBlogPost(tenant.tenant_id, slug, content, publicationTimestamp);
+  if (!post) {
+    const redirect = await resolveBlogRedirect(tenant.tenant_id, slug, content);
+    if (redirect) return { status: "redirect", to: `${basePath}${blogPaths.post(redirect)}` };
+    return { status: "not_found" };
+  }
+
+  const path = blogPaths.post(post.slug);
+  const viewer = await readViewerSession(Astro);
+  const gated = (post.access ?? "public") !== "public";
+  const unlock = viewerHasBlogAccess(viewer, post);
+  const bodyHtml = articleBodyHtml(post.contentHtml, { gated, unlock });
+  const next = safeNext(`${basePath}${blogPaths.post(post.slug)}`);
+  const loginHref = `/auth/login?next=${encodeURIComponent(next)}`;
+
+  const canonical = new URL(blogPaths.post(post.slug), canonicalBase + "/").toString();
+  const presentation = resolveBlogPresentation(blogSettings);
+  const author = bylineAuthor(post.author);
+
+  const listed = await listBlogPosts(tenant.tenant_id, content, publicationTimestamp);
+  const authorArchiveSlug = author ? authorSlug(author) : "";
+  const authorHasArchive = authorArchiveSlug !== "" && listed.some(
+    (p) => authorSlug(p.author) === authorArchiveSlug,
+  );
+  const archivedTags = new Set(listed.flatMap((p) => p.tags.map(categorySlug)));
+  const tagLinks = post.tags.map((tag) => {
+    const tagSlug = categorySlug(tag);
+    return { label: tag, href: tagSlug && archivedTags.has(tagSlug) ? `${basePath}${blogPaths.tag(tagSlug)}` : null };
+  });
+  const authorUrl = authorHasArchive
+    ? new URL(blogPaths.author(authorArchiveSlug), canonicalBase + "/").toString()
+    : undefined;
+  const articleLd = blogPostingLd(post, {
+    url: canonical,
+    canonicalBase,
+    publisherName: tenant.displayName,
+    authorUrl,
+  });
+  const trail = siteTrail(
+    homeCrumbLabel(await content.getChrome()),
+    { label: "Blog", href: blogPaths.index },
+    { label: post.title, href: blogPaths.post(post.slug) },
+  );
+  const crumbs = breadcrumbLd(trail, canonicalBase);
+  const blogHref = `${basePath}${blogPaths.index}`;
+  const authorHref = authorHasArchive ? `${basePath}${blogPaths.author(authorArchiveSlug)}` : null;
+  const share = shareLinks(presentation.share, {
+    url: canonical,
+    title: post.title,
+    image: post.featuredImage ? new URL(post.featuredImage.src, canonicalBase + "/").toString() : undefined,
+  });
+
+  const translations = post.translationGroupId
+    ? await getTranslations(tenant.tenant_id, "blog", post.slug, { content, now: publicationTimestamp })
+    : [];
+  const alternates = buildAlternates(translations, (s) =>
+    new URL(blogPaths.post(s), canonicalBase + "/").toString());
+  const lang = alternates.length ? (post.inLanguage ?? "en") : undefined;
+  // The on-page language switcher stays same-origin (preview-host-relative), unlike `alternates`
+  // (absolute canonical URLs for the <link rel="alternate"> head tags) — a path-prefixed preview
+  // host must never send a reader off to the production domain.
+  const translationLinks = translations.length > 1
+    ? translations.map((variant) => ({
+        code: variant.inLanguage ?? "en",
+        href: `${basePath}${blogPaths.post(variant.slug)}`,
+        current: variant.slug === post.slug,
+      }))
+    : [];
+
+  return {
+    status: "ok",
+    props: {
+      post, path, bodyHtml, gated, unlock, next, loginHref, viewer, canonical, presentation, author,
+      authorHref, authorUrl, tagLinks, articleLd, trail, crumbs, blogHref, share, translationLinks,
+      alternates, lang,
+    },
+  };
+}

package/apps/storefront/src/lib/blog/types.ts

@@ -77,6 +77,16 @@ export interface BlogSettings {
   reactions?: boolean;
   /** Share row after the post's tags, in this order. `[]` renders none; absent uses `DEFAULT_SHARE_TARGETS`. */
   share?: string[];
+  /**
+   * Declared permalink shape: `true` serves individual posts at the site root
+   * (`/<slug>/`, no `/blog` prefix), matching a migrated source whose archive stays
+   * at `/blog/` but whose singular posts never carried that prefix (a common
+   * WordPress permalink split: a static "posts page" plus `/%postname%/`).
+   * Default false/absent keeps every post under `/blog/<slug>/`. The index, author,
+   * category and tag archives are unaffected either way — only the `post` route
+   * moves. Declared per tenant; never branched on tenant id.
+   */
+  postsAtRoot?: boolean;
 }
 
 /**

package/apps/storefront/src/lib/publication/rootDiscovery.ts

@@ -5,10 +5,10 @@
  * Paths are spelled exactly as the root sitemap lists them.
  */
 import type { APIContext } from "astro";
-import { listBlogPosts } from "@/lib/blog/provider.js";
+import { getBlogSettings, listBlogPosts } from "@/lib/blog/provider.js";
 import { listBuildPosts } from "@/lib/the-build/provider.js";
 import { isIndexableHtml, rawPageCanonicalUrl } from "@/lib/rawMarketingHtml.js";
-import { collectionPathsV1 } from "@/lib/blog/collectionPaths.js";
+import { collectionPathsV1, blogPathOptsV1 } from "@/lib/blog/collectionPaths.js";
 
 export interface RootDiscoveryDocumentV1 {
   kind: "home" | "page" | "post";
@@ -33,11 +33,12 @@ function htmlTitle(html: string): string {
 /** Root listable posts (blog and the-build), newest first as the collections list them. */
 export async function rootPostDocumentsV1(locals: APIContext["locals"]): Promise<RootDiscoveryDocumentV1[]> {
   const { tenant, content, publicationTimestamp } = locals;
-  const [blogPosts, buildPosts] = await Promise.all([
+  const [blogPosts, buildPosts, blogSettings] = await Promise.all([
     listBlogPosts(tenant.tenant_id, content, publicationTimestamp),
     listBuildPosts(tenant.tenant_id, { content, now: publicationTimestamp }),
+    getBlogSettings(tenant.tenant_id, content),
   ]);
-  const blogPaths = collectionPathsV1(locals, "blog");
+  const blogPaths = collectionPathsV1(locals, "blog", blogPathOptsV1(blogSettings));
   const buildPaths = collectionPathsV1(locals, "the-build");
   return [
     ...blogPosts.map((post) => ({ post, paths: blogPaths })),