@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

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

@@ -57,8 +57,13 @@ if (rawHtml && rawHtmlPolicy(tenant).allowed) {
   // Shared chrome: if the tenant ships a chrome.html wrapper AND this home is a
   // body-only fragment, rawHtmlResponse splices it in; a full document serves
   // verbatim (backward-compatible).
-  const chromeWrapper = await content.getChromeHtml();
-  return rawHtmlResponse(rawHtml, { nonce: Astro.locals.cspNonce, basePath, chromeWrapper });
+  const chromeWrapper = await content.getChromeHtml("/");
+  return rawHtmlResponse(rawHtml, {
+    nonce: Astro.locals.cspNonce,
+    basePath,
+    chromeWrapper,
+    plan: Astro.locals.integrationPlan,
+  });
 }
 
 const home = await content.getHome();
@@ -143,9 +148,9 @@ for (const block of marketing ? [] : home.blocks) {
   }
 }
 
-// Private-app widgets (D5) — home.section slot. Commerce-home only; marketing-
+// Private-app widgets — home.section slot. Commerce-home only; marketing-
 // tenant homes (raw HTML, above, and the marketing-block home) are out of
-// scope for D5 (deferred). No dark-mode preference infra exists yet — "light"
+// scope (deferred). No dark-mode preference infra exists yet — "light"
 // is the only theme hint until that lands.
 const homeSectionWidgets = marketing
   ? []
@@ -326,7 +331,7 @@ const homeSectionWidgets = marketing
       return null;
     })
   }
-  {/* Private-app widgets (D5, home.section) — sandboxed per install. */}
+  {/* Private-app widgets (home.section) — sandboxed per install. */}
   {homeSectionWidgets.map((w) => (
     <Section>
       <AppWidgetFrame

package/apps/storefront/src/pages/llms.txt.ts

@@ -34,7 +34,7 @@ export async function GET(context: APIContext): Promise<Response> {
       content.listPages(),
       tot.getFeatured(12),
       content.getHome().catch(() => null),
-      listBlogPosts(tenant.tenant_id),
+      listBlogPosts(tenant.tenant_id, content),
     ]);
   // Empty synthesized collections (no active members) never make the guide —
   // an LLM shouldn't be pointed at a URL that resolves to zero products.

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

@@ -60,7 +60,7 @@ if (!product || product.status === "archived") {
 }
 const isDraft = product.status !== "active";
 
-// Private-app widgets (D5) — product.aside slot, one iframe per live install.
+// Private-app widgets — product.aside slot, one iframe per live install.
 // No dark-mode preference is resolved anywhere in the storefront yet; "light"
 // is the only theme hint until that infra exists.
 const productAsideWidgets = await renderWidgetSlot(
@@ -111,7 +111,7 @@ const mf = (ns: string, key: string) =>
   product.metafields.find((m) => m.namespace === ns && m.key === key)?.value;
 
 // Reviews — REAL aggregate from the store's reviews app, mirrored to metafields.
-// readReviewAggregate is the single, real-or-absent reader (§F9): it parses both
+// readReviewAggregate is the single, real-or-absent reader: it parses both
 // the bare and JSON-blob rating forms and the real count key, and returns {0,0}
 // unless BOTH numbers are real positives — so no fabricated rating can render.
 const { average: reviewAvg, count: reviewCount } = readReviewAggregate(product);
@@ -181,7 +181,7 @@ const available = isAvailable(product);
 // side so the island can render a signed, tamper-proof form. In `signed` mode a
 // missing secret means we render NO cart (never a tamperable form); the
 // `unsigned-demo` mode needs no secret. Drafts still get a cart (preview links).
-// Membership + Autopilot mechanics (F10). Member pricing renders only once a
+// Membership + Autopilot mechanics. Member pricing renders only once a
 // real eligibility signal flows through resolveMemberContext (Phase 2); Phase 1
 // is anonymous. Autopilot (subscription options) is hidden when the tenant has
 // set commerce.autopilot.enabled = false (hide-at-launch).
@@ -198,7 +198,7 @@ const pricing: {
   ? { membershipRule, stacking: membershipProgram?.stacking ?? DEFAULT_STACKING_POLICY }
   : undefined;
 const autopilotEnabled = isAutopilotEnabled(tenant.commerce?.autopilot);
-// Server-side pricing context (F11b). The SIGNED price is the member-adjusted
+// Server-side pricing context. The SIGNED price is the member-adjusted
 // effective price for THIS request's resolved eligibility — never the list price,
 // and never re-derived client-side. Phase 1 resolves anonymous, so this yields the
 // list/subscription price; a Phase-2 member request signs their member price.
@@ -366,8 +366,9 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
           productTitle={product.title}
           checkoutCart={checkoutCart}
           pricing={pricing}
+          handoffUrl={withBase(basePath, "/api/commerce/checkout-handoff")}
         />
-        {/* Regulated-tenant checkout ENFORCEMENT gate (F12/T5). Intercepts the
+        {/* Regulated-tenant checkout ENFORCEMENT gate. Intercepts the
             managed-cart handoff to clear age + ship-to compliance server-side
             before the external checkout. Only mounts when a store is wired AND
             the tenant is regulated. */}
@@ -392,7 +393,7 @@ const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
         </button>
       </div>
 
-      {/* Private-app widgets (D5, product.aside) — sandboxed per install. */}
+      {/* Private-app widgets (product.aside) — sandboxed per install. */}
       {productAsideWidgets.map((w) => (
         <div class="mt-7">
           <AppWidgetFrame

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

@@ -67,7 +67,7 @@ export async function GET(context: APIContext): Promise<Response> {
     urls.push({ loc: `${base}/${page.slug}` });
   }
 
-  const blogPosts = await listBlogPosts(tenant.tenant_id);
+  const blogPosts = await listBlogPosts(tenant.tenant_id, content);
   if (blogPosts.length > 0) {
     urls.push({ loc: `${base}/blog/` });
     for (const post of blogPosts) {
@@ -85,7 +85,7 @@ export async function GET(context: APIContext): Promise<Response> {
     }
   }
 
-  const buildPosts = await listBuildPosts(tenant.tenant_id);
+  const buildPosts = await listBuildPosts(tenant.tenant_id, { content });
   if (buildPosts.length > 0) {
     urls.push({ loc: `${base}/the-build/` });
     for (const post of buildPosts) {

package/apps/storefront/src/pages/style-guide/[tenant]/[theme].astro

@@ -20,6 +20,7 @@ export const prerender = false;
 // utilities + reference theme-token fallbacks so the (token-styled) components
 // render here without the app Layout. The `.sg-commerce` wrapper pins the
 // reference palette so they look coherent regardless of the marketing theme CSS.
+import { tenantDirSegment } from "@tot/public-runtime";
 import "@/styles/global.css";
 import PriceDisplay from "@/components/commerce/PriceDisplay.astro";
 import RatingStars from "@/components/commerce/RatingStars.astro";
@@ -88,26 +89,27 @@ const cspNonce = Astro.locals.cspNonce;
 
 // --- Sample chrome data (preview-only; no live tenant content) ----------------
 const sampleNav: ChromeNavItem[] = [
-  { label: "New", href: "#", flag: true, badge: "NEW" },
+  { id: "nav-new", label: "New", href: "#", flag: true, badge: "NEW" },
   {
+    id: "nav-shop",
     label: "Shop",
     href: "#",
     columns: [
-      { title: "Category", links: [{ label: "Disposables", href: "#" }, { label: "E-Liquid", href: "#" }, { label: "Devices", href: "#" }] },
-      { title: "Featured", links: [{ label: "Best Sellers", href: "#" }, { label: "On Sale", href: "#", badge: "%" }] },
-      { title: "Brands", links: [{ label: "Northwind", href: "#" }, { label: "Summit Co.", href: "#" }] },
+      { title: "Category", links: [{ id: "nav-shop-disposables", label: "Disposables", href: "#" }, { id: "nav-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "nav-shop-devices", label: "Devices", href: "#" }] },
+      { title: "Featured", links: [{ id: "nav-shop-bestsellers", label: "Best Sellers", href: "#" }, { id: "nav-shop-onsale", label: "On Sale", href: "#", badge: "%" }] },
+      { title: "Brands", links: [{ id: "nav-shop-northwind", label: "Northwind", href: "#" }, { id: "nav-shop-summit", label: "Summit Co.", href: "#" }] },
     ],
   },
-  { label: "Coils & Parts", href: "#", children: [{ label: "Coils", href: "#" }, { label: "Pods", href: "#" }, { label: "Batteries", href: "#" }] },
-  { label: "On Sale", href: "#" },
+  { id: "nav-coils", label: "Coils & Parts", href: "#", children: [{ id: "nav-coils-coils", label: "Coils", href: "#" }, { id: "nav-coils-pods", label: "Pods", href: "#" }, { id: "nav-coils-batteries", label: "Batteries", href: "#" }] },
+  { id: "nav-sale", label: "On Sale", href: "#" },
 ];
 const sampleSocial = [
   { label: "X", href: "#", iconPath: "M18.9 2H22l-7.1 8.1L23 22h-6.6l-5-6.6L5.7 22H2.6l7.6-8.7L1.5 2h6.8l4.5 6 5.1-6z" },
 ];
 const sampleFooterCols = [
-  { title: "Shop", links: [{ label: "Disposables", href: "#" }, { label: "E-Liquid", href: "#" }, { label: "Devices", href: "#" }] },
-  { title: "Support", links: [{ label: "Contact", href: "#" }, { label: "Shipping", href: "#" }, { label: "Returns", href: "#" }] },
-  { title: "Company", links: [{ label: "About", href: "#" }, { label: "Blog", href: "#" }] },
+  { title: "Shop", links: [{ id: "ftr-shop-disposables", label: "Disposables", href: "#" }, { id: "ftr-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "ftr-shop-devices", label: "Devices", href: "#" }] },
+  { title: "Support", links: [{ id: "ftr-support-contact", label: "Contact", href: "#" }, { id: "ftr-support-shipping", label: "Shipping", href: "#" }, { id: "ftr-support-returns", label: "Returns", href: "#" }] },
+  { title: "Company", links: [{ id: "ftr-company-about", label: "About", href: "#" }, { id: "ftr-company-blog", label: "Blog", href: "#" }] },
 ];
 // BrandGrid samples: text-wordmark tiles and logo-image tiles (Img renders
 // deterministic placeholders offline so the image code path is exercised
@@ -125,7 +127,7 @@ const sampleBrandsLogo: Brand[] = [
   { label: "Pod King", href: "#", logoSrc: "#", logoWidth: 200, logoHeight: 100 },
   { label: "Flavor Beast", href: "#", logoSrc: "#", logoWidth: 200, logoHeight: 100 },
 ];
-// Review/UGC samples (P3 reviews-ugc-widgets): illustrative fixture reviews
+// Review/UGC samples: illustrative fixture reviews
 // ONLY, for previewing ReviewSummary/ReviewList token styling in isolation —
 // never sourced from or rendered on a live product page (see
 // docs/architecture/review-markup-policy.md; real callers pass tot.getReviews()
@@ -135,7 +137,7 @@ const sampleReviews: Review[] = [
   { author: "Priya K.", rating: 4, body: "Good overall, battery life could be a bit longer.", date: "2026-05-18", verifiedBuyer: true },
   { author: "T. Nguyen", rating: 3, title: "Decent, not amazing", body: "Does the job but nothing stands out versus similar devices.", date: "2026-04-30" },
 ];
-// Blog/article samples (W4): featured-image cards (Img renders deterministic
+// Blog/article samples: featured-image cards (Img renders deterministic
 // placeholders offline so the image path is exercised) + one image-less card
 // (token-tinted placeholder band). Meta is illustrative example copy only.
 const sampleArticles: Article[] = [
@@ -236,7 +238,7 @@ const sampleComparisonRows: ComparisonRow[] = [
   { label: "Cancel anytime", cells: [null, true, true] },
 ];
 
-// --- Sample structured content (F4) — the DATA a policy page is driven by,
+// --- Sample structured content — the DATA a policy page is driven by,
 //     replacing a hand-authored HTML/CSS fragment. Exercises headings (TOC),
 //     rich-text links, lists, a definition glossary, tone callouts, a contact
 //     block, and a needs-review flag (reviewer-only). ---------------------------
@@ -293,13 +295,13 @@ const sampleProseSections: ProseSection[] = [
   },
 ];
 
-// Trust strip (F4, f09-guarded): mixes real claims + a real rating with
+// Trust strip: mixes real claims + a real rating with
 // fabrication vectors that MUST be dropped — the guide proves real-or-absent.
 const sampleTrustStrip: TrustStripItem[] = [
   { kind: "claim", label: "Ships from USA" },
   { kind: "claim", label: "Lab-tested" },
   { kind: "rating", average: 4.9, count: 369, label: "avg rating" },
-  { kind: "claim", label: "Based on 369 reviews" }, // fabricated → dropped by f09
+  { kind: "claim", label: "Based on 369 reviews" }, // fabricated → dropped
   { kind: "rating", average: 5, count: 0 }, // half-populated → dropped
 ];
 
@@ -458,10 +460,13 @@ const sampleMarketingBlocks: MarketingBlock[] = [
 // Colocated repo-root layout: from src/pages/style-guide/[tenant]/ the repo
 // root is six levels up.
 const themeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../../tenants/*/content/themes/*.json",
+  [
+    "../../../../../../tenants/*/content/themes/*.json",
+    "../../../../../../tenants/e2e/*/content/themes/*.json",
+  ],
   { eager: true, import: "default" },
 );
-const seg = `/tenants/${tenant}/content/themes/`;
+const seg = `${tenantDirSegment(tenant ?? "")}content/themes/`;
 const t = Object.entries(themeModules)
   .filter(([path]) => path.includes(seg))
   .map(([, mod]) => mod)
@@ -469,17 +474,23 @@ const t = Object.entries(themeModules)
 
 if (!t) return new Response(null, { status: 404 });
 
-// Has this tenant adopted the canonical shared chrome (unit F3)? If so it no
-// longer ships its own mkt.css (retired at integration, I1/I2/I3) — link the
+// Has this tenant adopted the canonical shared chrome? If so it no
+// longer ships its own mkt.css (retired at integration) — link the
 // platform /shared/commerce-chrome.css instead so the marketing-component
 // samples below still render in-brand.
 const chromeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../../tenants/*/content/chrome.json",
+  [
+    "../../../../../../tenants/*/content/chrome.json",
+    "../../../../../../tenants/e2e/*/content/chrome.json",
+  ],
   { eager: true, import: "default" },
 );
-const chromeSeg = `/tenants/${tenant}/content/chrome.json`;
+const chromeSeg = `${tenantDirSegment(tenant ?? "")}content/chrome.json`;
 const chromeConfig = Object.entries(chromeModules).find(([path]) => path.includes(chromeSeg))?.[1];
-const usesSharedChrome = chromeConfig?.sharedChrome === true;
+// Adoption is now "does chrome.json carry the consolidated header/footer
+// shape" (lib/chrome/model.ts ChromeConfig) — the old `sharedChrome: true`
+// opt-in flag is retired; a successfully-shaped config IS the adopted signal.
+const usesSharedChrome = !!chromeConfig?.header && !!chromeConfig?.footer;
 
 const tk = t.tokens ?? {};
 const storyboard = t.storyboard ?? null;
@@ -492,7 +503,7 @@ const REFERENCE_COMPONENT_VARS: Record<string, string> = {
   "--color-muted": "#5c6663", "--color-primary": "#1f3a34", "--color-primary-contrast": "#f4f1ea",
   "--color-accent": "#b5612f", "--color-border": "#dcd6c9", "--color-success": "#3f6b4f",
   "--color-sale": "#9e3b2e",
-  // F1 semantic + F6 quality-bar interaction tokens — reference (Northwind)
+  // Semantic + quality-bar interaction tokens — reference (Northwind)
   // values so the text/icon-token samples render concretely and re-skin when a
   // descriptor overrides them via preview.componentVars.
   "--color-warning": "#8a5717", "--color-error": "#a22014", "--color-info": "#2c5b73",
@@ -610,7 +621,7 @@ const componentVarsInline = Object.entries(componentVars)
       .sg-commerce .sg-h { color: var(--color-primary); }
       .sg-commerce .sg-block { border-top-color: var(--color-border); }
 
-      /* Semantic text & icon token samples (v1.1 · unit F6). Each swatch reads
+      /* Semantic text & icon token samples (v1.1). Each swatch reads
          ONE contract token so the guide proves text/icon roles resolve + re-skin
          from tokens alone — never a hard-coded color. */
       .sg-tok-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(210px, 1fr)); gap: 12px; }
@@ -952,7 +963,7 @@ const componentVarsInline = Object.entries(componentVars)
         </div>
       </section>
 
-      {/* ── Semantic text & icon tokens (v1.1 · unit F6) ────────────────────
+      {/* ── Semantic text & icon tokens (v1.1) ──────────────────────────────
           The quality-bar coverage sample: every text role, icon tint, and
           interaction state renders from a NAMED contract token — nothing here
           hard-codes a color or borrows `accent`. Swap the theme (or a
@@ -1138,7 +1149,7 @@ const componentVarsInline = Object.entries(componentVars)
       <section class="sg-block">
         <p class="sg-h">Chrome — UtilityNav</p>
         <UtilityNav
-          links={[{ label: "News", href: "#" }, { label: "About", href: "#" }, { label: "Contact", href: "#" }]}
+          links={[{ id: "util-news", label: "News", href: "#" }, { id: "util-about", label: "About", href: "#" }, { id: "util-contact", label: "Contact", href: "#" }]}
           locale="English"
           currency="United States (USD $)"
           social={sampleSocial}
@@ -1283,8 +1294,8 @@ const componentVarsInline = Object.entries(componentVars)
           — no pricing/checkout/subscription mechanics. Figures are ILLUSTRATIVE
           by default: unless a tier asserts real:true the widget renders a
           first-class "Illustrative figures" affordance (badge + "e.g." + note)
-          so an example number is never shown as a live offer (decision
-          compliance-widgets-platform-owned). Fed sample tiers here; a tenant
+          so an example number is never shown as a live offer. Fed sample
+          tiers here; a tenant
           supplies its own on a membership page. */}
       <section class="sg-block">
         <p class="sg-h">Membership tiers — <code>components/membership/</code></p>
@@ -1307,13 +1318,13 @@ const componentVarsInline = Object.entries(componentVars)
         />
       </section>
 
-      {/* ── Structured content widgets (components/content/, spec §F4) ───────
+      {/* ── Structured content widgets (components/content/) ───────
           The DATA-driven promotion of repeated raw-page patterns. A tenant
           authors a policy/about/compliance page as structured `sections`
           (JSON) instead of copying an HTML/CSS fragment; these components
           render it with the a11y (headings, <dl>, <address>, roles, tap
-          targets) baked in and every color from f06 tokens. The trust strip is
-          f09-guarded — real-or-absent, fabricated proof dropped. */}
+          targets) baked in and every color from tokens. The trust strip is
+          guarded — real-or-absent, fabricated proof dropped. */}
       <section class="sg-block">
         <p class="sg-h">Structured content — <code>components/content/</code></p>
         <p class="lede" style="font-size:.95rem;color:var(--color-muted)">Data-driven framework widgets (F4): a policy page rendered from structured <code>sections</code> with no HTML/CSS to copy. Accessibility lives in the components; tenant content is pure data.</p>
@@ -1374,7 +1385,7 @@ const componentVarsInline = Object.entries(componentVars)
       {/* ── Interactive islands (components/islands/) ─────────────────────
           Client-hydrated Preact islands. Each is tenant-agnostic and reads
           only fixture/localStorage data here — no live catalog, cart, or ToT
-          calls (unit style-guide-full-coverage). */}
+          calls. */}
       <section class="sg-block">
         <p class="sg-h">Islands — <code>components/islands/</code></p>
         <p class="lede" style="font-size:.95rem;color:var(--color-muted)">Client-hydrated Preact islands exercised with fixture data — no live catalog, cart, or ToT calls.</p>

package/apps/storefront/src/pages/style-guide/[tenant]/chrome/[theme].astro

@@ -1,7 +1,7 @@
 ---
 /**
  * Preview/dev-only SHARED RAW-CHROME STYLE GUIDE —
- * `/_style-guide/<tenant>/chrome/<theme-id>/` (unit F4).
+ * `/_style-guide/<tenant>/chrome/<theme-id>/`.
  *
  * Renders the platform-shipped raw chrome set — the `/shared/commerce-chrome.css`
  * class vocabulary (announcement + utility bar, header + search + actions, primary
@@ -30,11 +30,16 @@ const cspNonce = Astro.locals.cspNonce;
 
 // Tenant-local theme descriptors. From src/pages/style-guide/[tenant]/chrome/ the
 // repo root is seven levels up.
+import { tenantDirSegment } from "@tot/public-runtime";
+
 const themeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../../../tenants/*/content/themes/*.json",
+  [
+    "../../../../../../../tenants/*/content/themes/*.json",
+    "../../../../../../../tenants/e2e/*/content/themes/*.json",
+  ],
   { eager: true, import: "default" },
 );
-const seg = `/tenants/${tenant}/content/themes/`;
+const seg = `${tenantDirSegment(tenant ?? "")}content/themes/`;
 const t = Object.entries(themeModules)
   .filter(([path]) => path.includes(seg))
   .map(([, mod]) => mod)

package/apps/storefront/src/pages/style-guide/[tenant]/guide/[theme].astro

@@ -17,6 +17,7 @@
  */
 export const prerender = false;
 
+import { tenantDirSegment } from "@tot/public-runtime";
 import "@/styles/global.css";
 import type { MarkdownInstance } from "astro";
 import StyleGuideNav from "@/components/style-guide/StyleGuideNav.astro";
@@ -27,10 +28,13 @@ const cspNonce = Astro.locals.cspNonce;
 // Tenant-local theme descriptors. From src/pages/style-guide/[tenant]/guide/ the
 // repo root is seven levels up (same depth as the chrome guide).
 const themeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../../../tenants/*/content/themes/*.json",
+  [
+    "../../../../../../../tenants/*/content/themes/*.json",
+    "../../../../../../../tenants/e2e/*/content/themes/*.json",
+  ],
   { eager: true, import: "default" },
 );
-const seg = `/tenants/${tenant}/content/themes/`;
+const seg = `${tenantDirSegment(tenant ?? "")}content/themes/`;
 const t = Object.entries(themeModules)
   .filter(([path]) => path.includes(seg))
   .map(([, mod]) => mod)

package/apps/storefront/src/pages/style-guide/[tenant]/index.astro

@@ -16,6 +16,7 @@
  */
 export const prerender = false;
 
+import { tenantDirSegment } from "@tot/public-runtime";
 import StyleGuideNav from "@/components/style-guide/StyleGuideNav.astro";
 
 const { tenant } = Astro.params;
@@ -24,10 +25,13 @@ const cspNonce = Astro.locals.cspNonce;
 // Tenant-local theme descriptors. Colocated repo-root layout: from
 // src/pages/style-guide/[tenant]/ the repo root is six levels up.
 const themeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../../tenants/*/content/themes/*.json",
+  [
+    "../../../../../../tenants/*/content/themes/*.json",
+    "../../../../../../tenants/e2e/*/content/themes/*.json",
+  ],
   { eager: true, import: "default" },
 );
-const seg = `/tenants/${tenant}/content/themes/`;
+const seg = `${tenantDirSegment(tenant ?? "")}content/themes/`;
 const themes = Object.entries(themeModules)
   .filter(([path]) => path.includes(seg))
   .map(([, mod]) => mod);

package/apps/storefront/src/pages/style-guide/index.astro

@@ -2,8 +2,11 @@
 /**
  * Preview/dev-only STYLE-GUIDE ROOT INDEX — `/_style-guide/`.
  *
- * Lists EVERY tenant and each of its theme guides, so all clients' guides are
- * discoverable from one place. Review surface only: noindex, never in the
+ * Lists every REAL tenant and each of its theme guides, so all clients' guides
+ * are discoverable from one place. Platform test tenants (the `.e2e.test` class,
+ * colocated under tenants/e2e/) are NOT listed — a generalized listing shows
+ * clients, not fixtures. `?includeTestTenants=1` opts them back in for someone
+ * who came here to look at one. Review surface only: noindex, never in the
  * sitemap, never part of production marketing publishing. Tenant-agnostic —
  * theme data is tenant-local (tenants/<tenant>/content/themes/*.json).
  *
@@ -17,25 +20,33 @@
  */
 export const prerender = false;
 
+import { listedTenantIds } from "@tot/public-runtime";
+
 const cspNonce = Astro.locals.cspNonce;
+const includeTestTenants = Astro.url.searchParams.get("includeTestTenants") === "1";
 
 // All tenant-local theme descriptors, grouped by tenant. Colocated repo-root
 // layout: from src/pages/style-guide/ the repo root is five levels up.
 const themeModules = import.meta.glob<Record<string, any>>(
-  "../../../../../tenants/*/content/themes/*.json",
+  [
+    "../../../../../tenants/*/content/themes/*.json",
+    "../../../../../tenants/e2e/*/content/themes/*.json",
+  ],
   { eager: true, import: "default" },
 );
 
 const ROLE_ORDER: Record<string, number> = { current: 0, candidate: 1, legacy: 2 };
 const byTenant = new Map<string, any[]>();
 for (const [path, mod] of Object.entries(themeModules)) {
-  const m = /\/tenants\/([^/]+)\/content\/themes\//.exec(path);
+  const m = /\/tenants\/(?:e2e\/)?([^/]+)\/content\/themes\//.exec(path);
   const tenant = m?.[1];
   if (!tenant) continue;
   if (!byTenant.has(tenant)) byTenant.set(tenant, []);
   byTenant.get(tenant)!.push(mod);
 }
+const listedIds = new Set(listedTenantIds([...byTenant.keys()], { includeTestTenants }));
 const tenants = [...byTenant.entries()]
+  .filter(([tenant]) => listedIds.has(tenant))
   .map(([tenant, themes]) => ({
     tenant,
     themes: themes.sort((a, b) => (ROLE_ORDER[a.role] ?? 9) - (ROLE_ORDER[b.role] ?? 9)),
@@ -77,7 +88,10 @@ const tenants = [...byTenant.entries()]
     <div class="wrap">
       <span class="flag">Preview · dev only · noindex</span>
       <h1>Client style guides</h1>
-      <p class="sub">Every tenant and its theme guides. Open a guide to preview the standard components and page sections re-skinned under that theme. Nothing here re-skins a live site.</p>
+      <p class="sub">Every client tenant and its theme guides. Open a guide to preview the standard components and page sections re-skinned under that theme. Nothing here re-skins a live site.</p>
+      <p class="sub">{includeTestTenants
+        ? <span>Showing platform test tenants too — <a href="/_style-guide/">hide them</a>.</span>
+        : <span>Platform test tenants are hidden — <a href="/_style-guide/?includeTestTenants=1">show them</a>.</span>}</p>
 
       {tenants.map(({ tenant, themes }) => (
         <section class="tenant">

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -2,7 +2,7 @@
  * GET /tenants/<id>/<path> — serve a tenant's versioned static asset from R2.
  *
  * The version-scoped replacement for the build-time `copy-tenant-assets.mjs`
- * baking (decision `assets-r2-versioned`). Resolves the tenant's active
+ * baking. Resolves the tenant's active
  * channel→snapshot versionId from the `cust:assets-pointer:<id>` KV record and
  * streams `tenants/<id>/<versionId>/<rel>` from the TENANT_ASSETS R2 bucket with
  * the right content-type + a revalidating cache header + a versionId ETag.
@@ -17,12 +17,36 @@
 import type { APIContext } from "astro";
 import {
   serveTenantAsset,
+  verifyPreviewToken,
   type R2BucketLike,
 } from "@tot/public-runtime";
-import { readR2, readKv } from "@/lib/env";
+import { readR2, readKv, readEnv } from "@/lib/env";
 
 export const prerender = false;
 
+/** A versionId is a content sha — restrict to a safe R2 key segment (no traversal). */
+const SAFE_VERSION_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+/**
+ * Resolve a CANDIDATE-preview version override for this asset request, or null.
+ * A candidate/revision page sets `tot_preview_version` (its versionId) + the
+ * `tot_preview` capability token; when the token verifies for THIS tenant, we serve
+ * that exact snapshot (`tenants/<id>/<versionId>/…`) instead of the channel pointer,
+ * so a candidate's NEW assets — unreachable via the never-flipped channel — resolve.
+ * Token-gated + tenant-matched so it can never serve another tenant's snapshot.
+ */
+async function resolvePreviewVersion(context: APIContext, urlTenant: string): Promise<string | null> {
+  const versionId = context.cookies.get("tot_preview_version")?.value ?? null;
+  const token = context.cookies.get("tot_preview")?.value ?? null;
+  if (!versionId || !token || !urlTenant) return null;
+  if (!SAFE_VERSION_ID.test(versionId) || versionId.includes("..")) return null;
+  const secret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+  if (!secret) return null;
+  const verified = await verifyPreviewToken(secret, token, Math.floor(Date.now() / 1000));
+  if (!verified.ok || verified.claims.tenantId !== urlTenant) return null;
+  return versionId;
+}
+
 export async function GET(context: APIContext): Promise<Response> {
   const [bucket, kv] = await Promise.all([
     readR2("TENANT_ASSETS"),
@@ -36,17 +60,29 @@ export async function GET(context: APIContext): Promise<Response> {
     });
   }
 
+  const previewVersionId = await resolvePreviewVersion(context, context.params.id ?? "");
+
   const res = await serveTenantAsset(
     {
       // Runtime binding structurally satisfies the shared-runtime R2 seam.
       bucket: bucket as unknown as R2BucketLike,
       kvGet: (key) => kv.get(key),
       channel: context.locals.customizationEnv ?? "live",
+      ...(previewVersionId ? { versionId: previewVersionId } : {}),
       ifNoneMatch: context.request.headers.get("if-none-match"),
     },
     new URL(context.request.url).pathname,
   );
 
+  // A candidate-preview asset must NEVER be edge/CDN-cached under its tokenless URL
+  // (that would poison the public asset with candidate bytes, and Vary doesn't cover
+  // the auth cookie). Force no-store for the preview-version path; the normal
+  // channel-served asset keeps its revalidating cache header.
+  if (res && previewVersionId) {
+    res.headers.set("cache-control", "no-store");
+    res.headers.set("x-robots-tag", "noindex, nofollow");
+  }
+
   return (
     res ??
     new Response("Not found", {

package/apps/storefront/src/pages/the-build/[slug].astro

@@ -11,11 +11,11 @@ import { getTranslations } from "@/lib/blog/collection.js";
 import { buildAlternates } from "@/lib/seo/alternates.js";
 import { breadcrumbLd } from "@/lib/jsonld.js";
 
-const { tenant, canonicalBase, basePath } = Astro.locals;
+const { tenant, canonicalBase, basePath, content } = Astro.locals;
 const slug = Astro.params.slug ?? "";
-const post = await getBuildPost(tenant.tenant_id, slug);
+const post = await getBuildPost(tenant.tenant_id, slug, { content });
 if (!post) {
-  const redirect = await resolveBuildRedirect(tenant.tenant_id, slug);
+  const redirect = await resolveBuildRedirect(tenant.tenant_id, slug, content);
   if (redirect) return Astro.redirect(`${basePath}/the-build/${redirect}/`, 301);
   return new Response(null, { status: 404 });
 }
@@ -45,7 +45,7 @@ const buildHref = `${basePath}/the-build/`;
 // the live-visible variant set (self + siblings); `buildAlternates` yields [] for
 // a singleton, so a non-translated post gets no alternates and no `lang` override
 // (byte-identical to today).
-const translations = await getTranslations(tenant.tenant_id, THE_BUILD.id, post.slug);
+const translations = await getTranslations(tenant.tenant_id, THE_BUILD.id, post.slug, { content });
 const alternates = buildAlternates(translations, (s) =>
   new URL(`/the-build/${s}/`, canonicalBase + "/").toString(),
 );

package/apps/storefront/src/pages/the-build/index.astro

@@ -8,8 +8,8 @@ import Layout from "@/layouts/Layout.astro";
 import PostAccessBadge from "@/components/blog/PostAccessBadge.astro";
 import { listBuildPosts } from "@/lib/the-build/provider.js";
 
-const { tenant, basePath, canonicalBase } = Astro.locals;
-const posts = await listBuildPosts(tenant.tenant_id);
+const { tenant, basePath, canonicalBase, content } = Astro.locals;
+const posts = await listBuildPosts(tenant.tenant_id, { content });
 if (posts.length === 0) return new Response(null, { status: 404 });
 
 const href = (path: string) => `${basePath}${path}` || "/";

package/apps/storefront/src/pages/the-build/rss.xml.ts

@@ -11,8 +11,8 @@ import { listBuildPosts, THE_BUILD } from "@/lib/the-build/provider.js";
 import { renderRssFeed } from "@/lib/blog/rss.js";
 
 export async function GET(context: APIContext): Promise<Response> {
-  const { tenant, canonicalBase } = context.locals;
-  const posts = await listBuildPosts(tenant.tenant_id);
+  const { tenant, canonicalBase, content } = context.locals;
+  const posts = await listBuildPosts(tenant.tenant_id, { content });
   if (posts.length === 0) return new Response(null, { status: 404 });
 
   const body = renderRssFeed({