@tokenoftrust/storefront-runner 2.4.72 → 2.4.74

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}` || "/";

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

@@ -0,0 +1,146 @@
+---
+/**
+ * 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]}
+  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/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/chrome/model.ts

@@ -48,6 +48,11 @@ export {
   type ChromeHeader,
   type ChromeFooter,
   type ChromeConfig,
+  type ProductDetailsConfig,
+  type ProductDetailSpecRow,
+  type ProductAttributeLine,
+  type ProductMetafieldRef,
+  type ProductDetailFaqConfig,
   type ChromeAssignmentEntry,
   type ChromeAssignments,
   type ChromeAssignmentsValidationResult,

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 })),

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

@@ -15,6 +15,9 @@ import { truncate } from "@/lib/format";
 import { rawHtmlPolicy, rawHtmlResponse, rawPageCanonicalUrl } from "@/lib/rawMarketingHtml";
 import { renderRawComplianceTop, renderRawComplianceBottom } from "@/lib/compliance/rawComplianceNotices";
 import { styleGuideAliasRewrite } from "@/lib/styleGuidePaths";
+import { getBlogSettings } from "@/lib/blog/provider.js";
+import { loadBlogPostViewV1, type BlogPostViewPropsV1 } from "@/lib/blog/postView.js";
+import BlogPostArticle from "@/components/blog/BlogPostArticle.astro";
 
 const { tenant, canonicalBase, content, basePath, apiBasePath, capabilities, features } =
   Astro.locals;
@@ -41,51 +44,73 @@ if (styleGuideTarget !== undefined) {
   return Astro.rewrite(styleGuideTarget);
 }
 
-// Raw tenant-authored marketing subpage (vendor-injected HTML) — serve the
-// self-contained document VERBATIM only when rawHtmlPolicy says this tenant may
-// bypass Layout. Regulated commerce tenants fall through to platform-composed
-// pages so compliance UI cannot be removed by raw HTML.
-const rawHtml = await content.getPageHtml(slug);
-const rawPolicy = rawHtmlPolicy(tenant);
-if (rawHtml && rawPolicy.allowed) {
-  // Shared chrome: a body-only fragment gets wrapped in the tenant's chrome.html;
-  // a full document serves verbatim (backward-compatible). See rawMarketingHtml.ts.
-  const chromeWrapper = await content.getChromeHtml(`/${slug}`);
-  const notices = {
-    nicotineWarning: tenant.compliance?.nicotineWarning,
-    pactAct: !!tenant.compliance?.pactAct,
-    minAge: tenant.compliance?.minAge,
-    shippingRestriction: tenant.compliance?.shippingRestriction,
-    exciseTaxEnabled: capabilities.exciseTax.enabled && features.catalog,
-  };
-  return rawHtmlResponse(rawHtml, {
-    nonce: Astro.locals.cspNonce,
-    basePath,
-    apiBasePath,
-    chromeWrapper,
-    plan: Astro.locals.integrationPlan,
-    consentSnapshot: Astro.locals.consentSnapshot,
-    canonicalUrl: rawPageCanonicalUrl(canonicalBase, slug),
-    complianceTop: rawPolicy.regulated ? renderRawComplianceTop(notices) : undefined,
-    complianceBottom: rawPolicy.regulated ? renderRawComplianceBottom(notices) : undefined,
-  });
+// A tenant that declares `BlogSettings.postsAtRoot` (see lib/blog/types.ts) serves its
+// 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.
+let blogPostProps: BlogPostViewPropsV1 | null = null;
+if (!slug.includes("/")) {
+  const blogSettings = await getBlogSettings(tenant.tenant_id, content);
+  if (blogSettings?.postsAtRoot) {
+    const result = await loadBlogPostViewV1(Astro, slug);
+    if (result.status === "redirect") return Astro.redirect(result.to, 308);
+    if (result.status === "ok") blogPostProps = result.props;
+  }
 }
 
-const page = await content.getPage(slug);
-if (!page) return new Response(null, { status: 404 });
+let page: Awaited<ReturnType<typeof content.getPage>> | null = null;
+if (!blogPostProps) {
+  // Raw tenant-authored marketing subpage (vendor-injected HTML) — serve the
+  // self-contained document VERBATIM only when rawHtmlPolicy says this tenant may
+  // bypass Layout. Regulated commerce tenants fall through to platform-composed
+  // pages so compliance UI cannot be removed by raw HTML.
+  const rawHtml = await content.getPageHtml(slug);
+  const rawPolicy = rawHtmlPolicy(tenant);
+  if (rawHtml && rawPolicy.allowed) {
+    // Shared chrome: a body-only fragment gets wrapped in the tenant's chrome.html;
+    // a full document serves verbatim (backward-compatible). See rawMarketingHtml.ts.
+    const chromeWrapper = await content.getChromeHtml(`/${slug}`);
+    const notices = {
+      nicotineWarning: tenant.compliance?.nicotineWarning,
+      pactAct: !!tenant.compliance?.pactAct,
+      minAge: tenant.compliance?.minAge,
+      shippingRestriction: tenant.compliance?.shippingRestriction,
+      exciseTaxEnabled: capabilities.exciseTax.enabled && features.catalog,
+    };
+    return rawHtmlResponse(rawHtml, {
+      nonce: Astro.locals.cspNonce,
+      basePath,
+      apiBasePath,
+      chromeWrapper,
+      plan: Astro.locals.integrationPlan,
+      consentSnapshot: Astro.locals.consentSnapshot,
+      canonicalUrl: rawPageCanonicalUrl(canonicalBase, slug),
+      complianceTop: rawPolicy.regulated ? renderRawComplianceTop(notices) : undefined,
+      complianceBottom: rawPolicy.regulated ? renderRawComplianceBottom(notices) : undefined,
+    });
+  }
 
-const crumbs = siteTrail(
-  homeCrumbLabel(await Astro.locals.content.getChrome()),
-  { label: page.title, href: `/${page.slug}` },
-);
+  page = await content.getPage(slug);
+  if (!page) return new Response(null, { status: 404 });
+}
+
+// Only reached when no root-level blog post claimed this slug. `page` is always truthy by
+// the time this renders (the block above already 404s otherwise) — `[]` here is only to
+// keep `crumbs` non-nullable for the breadcrumbLd/<Breadcrumbs> calls below.
+const crumbs = page
+  ? siteTrail(
+      homeCrumbLabel(await Astro.locals.content.getChrome()),
+      { label: page.title, href: `/${page.slug}` },
+    )
+  : [];
 
-const description =
-  page.seoDescription ||
-  (page.intro ? truncate(page.intro, 160) : undefined);
+const description = page
+  ? page.seoDescription || (page.intro ? truncate(page.intro, 160) : undefined)
+  : undefined;
 
 // Structured pages drive the body from `sections`; legacy pages keep the
 // sanitized `body_html`. Prefer structured whenever a page ships sections.
-const structured = (page.sections?.length ?? 0) > 0;
+const structured = (page?.sections?.length ?? 0) > 0;
 
 // Reviewer-only needs-review flags render in preview/dev only — mirrors the
 // middleware's "production read" definition (no preview host / token / cookie),
@@ -96,7 +121,7 @@ const isPreview =
   Astro.url.searchParams.has("__preview") ||
   Astro.cookies.has("tot_preview");
 
-const updatedLabel = page.updated
+const updatedLabel = page?.updated
   ? new Date(page.updated).toLocaleDateString("en-US", {
       year: "numeric",
       month: "long",
@@ -105,44 +130,48 @@ const updatedLabel = page.updated
   : null;
 ---
 
-<Layout
-  title={page.title}
-  seoTitle={page.seoTitle}
-  description={description}
-  path={`/${page.slug}`}
-  ogType="article"
-  jsonLd={breadcrumbLd(crumbs, canonicalBase)}
->
-  <div class="container-prose pt-6">
-    <Breadcrumbs crumbs={crumbs} />
-  </div>
+{blogPostProps ? (
+  <BlogPostArticle {...blogPostProps} />
+) : (
+  <Layout
+    title={page!.title}
+    seoTitle={page!.seoTitle}
+    description={description}
+    path={`/${page!.slug}`}
+    ogType="article"
+    jsonLd={breadcrumbLd(crumbs, canonicalBase)}
+  >
+    <div class="container-prose pt-6">
+      <Breadcrumbs crumbs={crumbs} />
+    </div>
 
-  {/* Page hero */}
-  <header class="container-prose pb-2 pt-8">
-    {page.eyebrow && <p class="eyebrow eyebrow--tick mb-3">{page.eyebrow}</p>}
-    <h1 class="display-xl max-w-[20ch]">
-      {page.title}
-    </h1>
-    {page.intro && (
-      <p class="mt-5 max-w-[60ch] text-[1.1rem] text-[var(--color-muted)]">
-        {page.intro}
-      </p>
-    )}
-    {updatedLabel && (
-      <p class="mt-3 text-sm text-[var(--color-muted)]">Last updated {updatedLabel}</p>
-    )}
-    {structured && <ProseToc sections={page.sections!} />}
-  </header>
+    {/* Page hero */}
+    <header class="container-prose pb-2 pt-8">
+      {page!.eyebrow && <p class="eyebrow eyebrow--tick mb-3">{page!.eyebrow}</p>}
+      <h1 class="display-xl max-w-[20ch]">
+        {page!.title}
+      </h1>
+      {page!.intro && (
+        <p class="mt-5 max-w-[60ch] text-[1.1rem] text-[var(--color-muted)]">
+          {page!.intro}
+        </p>
+      )}
+      {updatedLabel && (
+        <p class="mt-3 text-sm text-[var(--color-muted)]">Last updated {updatedLabel}</p>
+      )}
+      {structured && <ProseToc sections={page!.sections!} />}
+    </header>
 
-  {/* Body — constrained to a readable measure. Structured pages render
-      framework widgets from `sections`; legacy pages keep the sanitized HTML. */}
-  <div class="container-prose pb-[clamp(3rem,7vw,6rem)] pt-8">
-    {structured ? (
-      <div class="mx-auto max-w-[68ch]">
-        <ProseSections sections={page.sections!} includeNeedsReview={isPreview} />
-      </div>
-    ) : (
-      <div class="rte mx-auto max-w-[68ch] text-[var(--color-text)]" set:html={page.body_html} />
-    )}
-  </div>
-</Layout>
+    {/* Body — constrained to a readable measure. Structured pages render
+        framework widgets from `sections`; legacy pages keep the sanitized HTML. */}
+    <div class="container-prose pb-[clamp(3rem,7vw,6rem)] pt-8">
+      {structured ? (
+        <div class="mx-auto max-w-[68ch]">
+          <ProseSections sections={page!.sections!} includeNeedsReview={isPreview} />
+        </div>
+      ) : (
+        <div class="rte mx-auto max-w-[68ch] text-[var(--color-text)]" set:html={page!.body_html} />
+      )}
+    </div>
+  </Layout>
+)}