@tokenoftrust/storefront-runner 2.0.0 → 2.0.1

package/apps/storefront/dev-plugins/tenant-hot-reload.mjs

@@ -4,13 +4,15 @@ import { readdirSync, existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { markSave, reportServerUp } from "./dev-loop-state.mjs";
 import { isTransientWatchFile } from "../../../scripts/dev/transient-files.mjs";
+import { E2E_TENANT_DIR, tenantDirSegments } from "../../../scripts/lib/tenant-dirs.mjs";
 import { readFile } from "node:fs/promises";
 
 // Repo-root tenants/ dir (colocated tenant layout) + the generated static dest
 // the predev copy step mirrors public/ into. This module lives at
 // apps/storefront/dev-plugins/, so tenants/ is three levels up. Forward-slash
 // normalized to match Vite's ctx.file (Vite always reports posix-style paths).
-const TENANTS_DIR = fileURLToPath(new URL("../../../tenants", import.meta.url)).replace(/\\/g, "/");
+const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
+const TENANTS_DIR = join(REPO_ROOT, "tenants").replace(/\\/g, "/");
 const PUBLIC_TENANTS_DEST = fileURLToPath(new URL("../public/tenants", import.meta.url));
 
 /**
@@ -53,7 +55,10 @@ async function loadTsModule(server, url) {
 export function classifyTenantFile(file) {
   const f = String(file).replace(/\\/g, "/");
   if (!f.startsWith(TENANTS_DIR + "/")) return null;
-  const rel = f.slice(TENANTS_DIR.length + 1); // "<id>/<...>"
+  // "<id>/<...>" for a real tenant, "e2e/<id>/<...>" for a platform test tenant —
+  // consume the nesting segment so `id` is always the tenant's own id.
+  let rel = f.slice(TENANTS_DIR.length + 1);
+  if (rel.startsWith(E2E_TENANT_DIR + "/")) rel = rel.slice(E2E_TENANT_DIR.length + 1);
   const slash = rel.indexOf("/");
   if (slash < 0) return null;
   const rest = rel.slice(slash + 1);
@@ -97,7 +102,7 @@ export function isVersionedTenant(id) {
     .map((s) => s.trim())
     .filter(Boolean);
   if (envList.includes(id)) return true;
-  return existsSync(join(TENANTS_DIR, id, ".tot", "assets-versioned"));
+  return existsSync(join(REPO_ROOT, ...tenantDirSegments(id), ".tot", "assets-versioned"));
 }
 
 /**

package/apps/storefront/scripts/generated/v84-clean-clone-replay.bundle.mjs

@@ -10639,7 +10639,7 @@ if (invokedPath2) {
 // apps/storefront/scripts/v84CleanCloneGraphPin.ts
 var V84_CLEAN_CLONE_LAUNCHER_ENTRY = "scripts/diag/rerun-v84-clean-clone.sh";
 var V84_CLEAN_CLONE_GRAPH_COUNT = 191;
-var V84_CLEAN_CLONE_GRAPH_SHA256 = "e284ebf9bd5f0795bee4126c5b2e36cf7cbade05fcbcc9b716a35fa9800fa377";
+var V84_CLEAN_CLONE_GRAPH_SHA256 = "dc9fb2e28b7d8041ca901ae2df204ab34da1eb957cd88f75437361e42491e566";
 
 // apps/storefront/scripts/replay-v84-clean-clone-pass.ts
 var SOURCE3 = "tokenoftrust.com";

package/apps/storefront/scripts/v84CleanCloneGraphPin.ts

@@ -12,7 +12,7 @@ export const V84_CLEAN_CLONE_BUILD_ENTRY =
   "apps/storefront/scripts/build-v84-clean-clone-standalone.mjs" as const;
 export const V84_CLEAN_CLONE_GRAPH_COUNT = 191;
 export const V84_CLEAN_CLONE_GRAPH_SHA256 =
-  "e284ebf9bd5f0795bee4126c5b2e36cf7cbade05fcbcc9b716a35fa9800fa377" as const;
+  "dc9fb2e28b7d8041ca901ae2df204ab34da1eb957cd88f75437361e42491e566" as const;
 
 export interface V84CleanCloneGraphIdentity {
   readonly paths: readonly string[];

package/apps/storefront/src/config/resolver.ts

@@ -20,7 +20,7 @@
  * Changing that value flips which tenant a bare/unknown host serves — proof the
  * default is configurable, not hardcoded.
  */
-import type { TenantResolver } from "@tot/public-runtime";
+import { tenantIdFromPath, type TenantResolver } from "@tot/public-runtime";
 import { readEnv, readKv } from "@/lib/env";
 import {
   tenantResolver as staticResolver,
@@ -32,24 +32,32 @@ import { getTenantTheme } from "@/themes/tenants";
 import { devTenantsToSeed } from "@/config/devTenantSeed";
 import { MemoryKv } from "@/lib/memoryKv";
 
-// LOCAL dev loop discovery: enumerate the colocated `tenants/<id>/` dirs on disk,
+// LOCAL dev loop discovery: enumerate the colocated tenant dirs on disk,
 // INCLUDING a developer's checkout grafted in by `tot dev` (scripts/tot-dev.mjs).
 // Keys only — the loaders are never invoked. Vite resolves this glob at
 // dev-server boot (after the graft) and re-resolves on HMR, so a newly grafted
 // tenant dir is discovered. Mirrors the content/theme dir globs the app already
 // uses (provider.ts, themes/tenants/index.ts). Depth: from src/config/ the repo
 // root is four levels up (config→src→storefront→apps→root).
+//
+// Both tiers are globbed: real tenants at `tenants/<id>/`, platform test tenants
+// one level deeper at `tenants/e2e/<id>/` (tenantDirRelative). Vite needs literal
+// patterns, so the nesting is spelled out here and `tenantIdFromPath` — the one
+// inverse of that mapping — recovers the id from either shape.
 const localTenantFiles = import.meta.glob([
   "../../../../tenants/*/theme.json",
   "../../../../tenants/*/content/home.html",
   "../../../../tenants/*/content/home.json",
+  "../../../../tenants/e2e/*/theme.json",
+  "../../../../tenants/e2e/*/content/home.html",
+  "../../../../tenants/e2e/*/content/home.json",
 ]);
 
-/** Dir names under `tenants/*` (dir == tenant id), from the discovery glob keys. */
+/** Tenant ids with a local dir (dir == tenant id), from the discovery glob keys. */
 function localTenantDirIds(): string[] {
   const ids = new Set<string>();
   for (const key of Object.keys(localTenantFiles)) {
-    const id = /\/tenants\/([^/]+)\//.exec(key)?.[1];
+    const id = tenantIdFromPath(key);
     if (id) ids.add(id);
   }
   return [...ids];
@@ -80,7 +88,7 @@ function catalogScopes(): Set<string> {
 // it. The explicit `.tot` literal in the pattern matches the dotdir; if the glob
 // sees nothing, synthesis simply falls back to the colocation convention.
 const tenantMarkerFiles = import.meta.glob<{ scope?: string }>(
-  "../../../../tenants/*/.tot/config.json",
+  ["../../../../tenants/*/.tot/config.json", "../../../../tenants/e2e/*/.tot/config.json"],
   { eager: true, import: "default" },
 );
 
@@ -88,7 +96,7 @@ const tenantMarkerFiles = import.meta.glob<{ scope?: string }>(
 function slugScopes(): Map<string, string> {
   const map = new Map<string, string>();
   for (const [key, cfg] of Object.entries(tenantMarkerFiles)) {
-    const id = /\/tenants\/([^/]+)\//.exec(key)?.[1];
+    const id = tenantIdFromPath(key);
     const scope = cfg?.scope;
     // A hostname scope that DIFFERS from the dir is the slug override; a scope
     // equal to the dir (the colocation norm) needs no override.

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

@@ -1,3 +1,4 @@
+import { tenantDirSegment } from "@tot/public-runtime";
 import type { AuthorBio, BlogPost, BlogPostSummary, PostStatus } from "./types.js";
 import type { ContentProvider } from "../storyblok/provider.js";
 
@@ -21,15 +22,24 @@ export interface Collection {
 // collection id are both path segments filtered at call time. The derived index
 // is the set of `posts/*.json` files — there is no hand-maintained index.json.
 const postGlobs = import.meta.glob<BlogPost>(
-  "../../../../../tenants/*/content/*/posts/*.json",
+  [
+    "../../../../../tenants/*/content/*/posts/*.json",
+    "../../../../../tenants/e2e/*/content/*/posts/*.json",
+  ],
   { import: "default" },
 );
 const redirectGlobs = import.meta.glob<Record<string, string>>(
-  "../../../../../tenants/*/content/*/redirects.json",
+  [
+    "../../../../../tenants/*/content/*/redirects.json",
+    "../../../../../tenants/e2e/*/content/*/redirects.json",
+  ],
   { import: "default" },
 );
 const authorsGlobs = import.meta.glob<Record<string, AuthorBio>>(
-  "../../../../../tenants/*/content/*/authors.json",
+  [
+    "../../../../../tenants/*/content/*/authors.json",
+    "../../../../../tenants/e2e/*/content/*/authors.json",
+  ],
   { import: "default" },
 );
 
@@ -128,7 +138,7 @@ function normalize(raw: BlogPost): BlogPost {
 }
 
 function postsPrefix(tenantId: string, collection: string): string {
-  return `/tenants/${tenantId}/content/${collection}/posts/`;
+  return `${tenantDirSegment(tenantId)}content/${collection}/posts/`;
 }
 
 function toSummary(p: BlogPost): BlogPostSummary {
@@ -162,7 +172,7 @@ export async function listCollections(
   tenantId: string,
   content?: ArtifactSource,
 ): Promise<string[]> {
-  const marker = `/tenants/${tenantId}/content/`;
+  const marker = `${tenantDirSegment(tenantId)}content/`;
   const collections = new Set<string>();
   const runtimePaths = canReadArtifacts(content)
     ? await content.listArtifactPaths("")
@@ -360,7 +370,7 @@ export async function getRedirects(
   }
   const key = Object.keys(redirectGlobs).find(
     (candidate) =>
-      candidate.includes(`/tenants/${tenantId}/content/${collection}/`) &&
+      candidate.includes(`${tenantDirSegment(tenantId)}content/${collection}/`) &&
       candidate.endsWith("/redirects.json"),
   );
   if (!key) return {};
@@ -392,7 +402,7 @@ export async function getAuthors(
   }
   const key = Object.keys(authorsGlobs).find(
     (candidate) =>
-      candidate.includes(`/tenants/${tenantId}/content/${collection}/`) &&
+      candidate.includes(`${tenantDirSegment(tenantId)}content/${collection}/`) &&
       candidate.endsWith("/authors.json"),
   );
   if (!key) return {};

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

@@ -3,6 +3,7 @@
 // derived engine lives in ./collection.ts and powers `the-build` + any new
 // collection; switching `/blog` onto it is a later migration once order is
 // encoded as data (see B0.1 §"/blog migration caution").
+import { tenantDirSegment } from "@tot/public-runtime";
 import type { BlogPost, BlogPostSummary } from "./types.js";
 import type { ContentProvider } from "../storyblok/provider.js";
 
@@ -12,21 +13,33 @@ function canReadArtifacts(value: ArtifactSource | undefined): value is ArtifactS
   return typeof value?.listArtifactPaths === "function" && typeof value.readArtifact === "function";
 }
 
+// Both tenant tiers: real at `tenants/<id>/`, platform test one level deeper at
+// `tenants/e2e/<id>/`. `tenantDirSegment` is the one inverse used to look a
+// tenant's keys back up.
 const indexGlobs = import.meta.glob<BlogPostSummary[]>(
-  "../../../../../tenants/*/content/blog/index.json",
+  [
+    "../../../../../tenants/*/content/blog/index.json",
+    "../../../../../tenants/e2e/*/content/blog/index.json",
+  ],
   { import: "default" },
 );
 const postGlobs = import.meta.glob<BlogPost>(
-  "../../../../../tenants/*/content/blog/posts/*.json",
+  [
+    "../../../../../tenants/*/content/blog/posts/*.json",
+    "../../../../../tenants/e2e/*/content/blog/posts/*.json",
+  ],
   { import: "default" },
 );
 const redirectGlobs = import.meta.glob<Record<string, string>>(
-  "../../../../../tenants/*/content/blog/redirects.json",
+  [
+    "../../../../../tenants/*/content/blog/redirects.json",
+    "../../../../../tenants/e2e/*/content/blog/redirects.json",
+  ],
   { import: "default" },
 );
 
 function tenantKey(keys: string[], tenantId: string, suffix: string): string | undefined {
-  const segment = `/tenants/${tenantId}/content/blog/`;
+  const segment = `${tenantDirSegment(tenantId)}content/blog/`;
   return keys.find((key) => key.includes(segment) && key.endsWith(suffix));
 }
 
@@ -47,7 +60,7 @@ export async function listBlogPosts(
     if (paths !== null) return [];
   }
   const key = tenantKey(Object.keys(indexGlobs), tenantId, "/index.json")
-    ?? Object.keys(indexGlobs).find((candidate) => candidate.includes(`/tenants/${tenantId}/content/blog/index.json`));
+    ?? Object.keys(indexGlobs).find((candidate) => candidate.includes(`${tenantDirSegment(tenantId)}content/blog/index.json`));
   return key ? indexGlobs[key]!() : [];
 }
 
@@ -91,7 +104,7 @@ export async function resolveBlogRedirect(
     if (paths !== null) return null;
   }
   const key = tenantKey(Object.keys(redirectGlobs), tenantId, "/redirects.json")
-    ?? Object.keys(redirectGlobs).find((candidate) => candidate.includes(`/tenants/${tenantId}/content/blog/redirects.json`));
+    ?? Object.keys(redirectGlobs).find((candidate) => candidate.includes(`${tenantDirSegment(tenantId)}content/blog/redirects.json`));
   if (!key) return null;
   const redirects = await redirectGlobs[key]!();
   return redirects[slug] ?? null;

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

@@ -24,6 +24,8 @@ import {
   contentArtifactPath,
   listPublishedArtifactPaths,
   readPublishedArtifact,
+  tenantDirRelative,
+  tenantDirSegment,
 } from "@tot/public-runtime";
 import { renderRawChrome } from "../rawChrome.js";
 import { parseChromeConfig } from "../chrome/parseConfig.js";
@@ -86,41 +88,65 @@ export interface ContentProvider {
 // time; a file missing for a tenant falls back to the default scope, so a
 // partially-adopted tenant still renders. Depth: from src/lib/storyblok/ the
 // repo root is five levels up (storyblok→lib→src→storefront→apps→root).
-const homeGlobs = import.meta.glob<HomeContent>("../../../../../tenants/*/content/home.json", {
+const homeGlobs = import.meta.glob<HomeContent>([
+  "../../../../../tenants/*/content/home.json",
+  "../../../../../tenants/e2e/*/content/home.json",
+], {
   import: "default",
 });
-const chromeGlobs = import.meta.glob<unknown>("../../../../../tenants/*/content/chrome.json", {
+const chromeGlobs = import.meta.glob<unknown>([
+  "../../../../../tenants/*/content/chrome.json",
+  "../../../../../tenants/e2e/*/content/chrome.json",
+], {
   import: "default",
 });
 // Per-page header/footer variant overrides for the raw-HTML chrome path (see
 // lib/chrome/assignments.ts). Tenant-owned, no cross-tenant fallback — same
 // convention as chromeGlobs above.
 const chromeAssignmentGlobs = import.meta.glob<unknown>(
-  "../../../../../tenants/*/content/chrome-assignments.json",
+  [
+    "../../../../../tenants/*/content/chrome-assignments.json",
+    "../../../../../tenants/e2e/*/content/chrome-assignments.json",
+  ],
   { import: "default" },
 );
-const pageGlobs = import.meta.glob<EditorialPage>("../../../../../tenants/*/content/pages/*.json", {
+const pageGlobs = import.meta.glob<EditorialPage>([
+  "../../../../../tenants/*/content/pages/*.json",
+  "../../../../../tenants/e2e/*/content/pages/*.json",
+], {
   import: "default",
 });
 // Raw self-authored home documents (marketing tenants). `?raw` bundles the file
 // as a string; a tenant with no home.html simply has no entry here.
-const homeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/home.html", {
+const homeHtmlGlobs = import.meta.glob<string>([
+  "../../../../../tenants/*/content/home.html",
+  "../../../../../tenants/e2e/*/content/home.html",
+], {
   query: "?raw",
   import: "default",
 });
 // Raw self-authored SUBPAGE documents: tenants/<tenant>/content/pages-html/<slug>.html
 // (e.g. pages-html/pricing.html -> /pricing/). `**` supports nested slugs.
-const pageHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/pages-html/**/*.html", {
+const pageHtmlGlobs = import.meta.glob<string>([
+  "../../../../../tenants/*/content/pages-html/**/*.html",
+  "../../../../../tenants/e2e/*/content/pages-html/**/*.html",
+], {
   query: "?raw",
   import: "default",
 });
 // Shared-chrome wrapper document (marketing tenants that author body-only page
 // fragments). One per tenant; a tenant without it keeps serving full documents.
-const chromeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/chrome.html", {
+const chromeHtmlGlobs = import.meta.glob<string>([
+  "../../../../../tenants/*/content/chrome.html",
+  "../../../../../tenants/e2e/*/content/chrome.html",
+], {
   query: "?raw",
   import: "default",
 });
-const artifactGlobs = import.meta.glob<string>("../../../../../tenants/*/content/**/*", {
+const artifactGlobs = import.meta.glob<string>([
+  "../../../../../tenants/*/content/**/*",
+  "../../../../../tenants/e2e/*/content/**/*",
+], {
   query: "?raw",
   import: "default",
 });
@@ -131,13 +157,13 @@ function pickContent<T>(
   globs: Record<string, () => Promise<T>>,
   scope: string,
 ): (() => Promise<T>) | null {
-  const seg = `/tenants/${scope}/content/`;
+  const seg = `${tenantDirSegment(scope)}content/`;
   const key = Object.keys(globs).find((k) => k.includes(seg));
   return (key ? globs[key] : null) ?? null;
 }
 
 function pickPages(scope: string): Array<() => Promise<EditorialPage>> {
-  const seg = `/tenants/${scope}/content/pages/`;
+  const seg = `${tenantDirSegment(scope)}content/pages/`;
   return Object.keys(pageGlobs)
     .filter((k) => k.includes(seg))
     .map((k) => pageGlobs[k]!);
@@ -150,7 +176,7 @@ function normalizeRawPageSlug(slug: string): string {
 
 /** The subpage slug a glob key encodes for `scope`, or null if it's not one. */
 function rawPageSlugForKey(scope: string, key: string): string | null {
-  const seg = `/tenants/${scope}/content/pages-html/`;
+  const seg = `${tenantDirSegment(scope)}content/pages-html/`;
   const start = key.indexOf(seg);
   if (start < 0 || !key.endsWith(".html")) return null;
   return key.slice(start + seg.length, -".html".length);
@@ -187,7 +213,7 @@ async function readRawDevFile(scope: string, relative: string): Promise<string |
     // provider.ts lives at apps/storefront/src/lib/storyblok/ — the repo root is five
     // levels up, mirroring the import.meta.glob prefix ("../../../../../tenants/...").
     const here = dirname(fileURLToPath(import.meta.url));
-    const abs = resolve(here, "../../../../..", "tenants", scope, "content", relative);
+    const abs = resolve(here, "../../../../..", ...tenantDirRelative(scope).split("/"), "content", relative);
     return await readFile(abs, "utf8");
   } catch {
     return null;
@@ -306,13 +332,13 @@ export class LocalContentProvider implements ContentProvider {
 
   async readArtifact(relative: string): Promise<string | null> {
     const normalized = relative.replace(/^\/+/, "");
-    const marker = `/tenants/${this.scope}/content/${normalized}`;
+    const marker = `${tenantDirSegment(this.scope)}content/${normalized}`;
     const key = Object.keys(artifactGlobs).find((candidate) => candidate.endsWith(marker));
     return key ? artifactGlobs[key]!() : null;
   }
 
   async listArtifactPaths(prefix = ""): Promise<string[]> {
-    const marker = `/tenants/${this.scope}/content/`;
+    const marker = `${tenantDirSegment(this.scope)}content/`;
     return Object.keys(artifactGlobs)
       .flatMap((key) => {
         const at = key.indexOf(marker);

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";
@@ -459,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)
@@ -475,10 +479,13 @@ if (!t) return new Response(null, { status: 404 });
 // 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];
 // Adoption is now "does chrome.json carry the consolidated header/footer
 // shape" (lib/chrome/model.ts ChromeConfig) — the old `sharedChrome: true`

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

@@ -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/themes/tenants/index.ts

@@ -13,10 +13,19 @@
  * Depth: from src/themes/tenants/ the repo root is five levels up
  * (tenants→themes→src→storefront→apps→root).
  */
-import type { DeepPartial, ThemeTokens } from "@tot/public-runtime";
+import {
+  listedTenantIds,
+  tenantIdFromPath,
+  type DeepPartial,
+  type TenantListingOptions,
+  type ThemeTokens,
+} from "@tot/public-runtime";
 
+// Both tiers: real tenants at `tenants/<id>/`, platform test tenants one level
+// deeper at `tenants/e2e/<id>/`. Vite needs literal patterns, so the nesting is
+// spelled out; `tenantIdFromPath` recovers the id from either shape.
 const modules = import.meta.glob<Record<string, unknown>>(
-  "../../../../../tenants/*/theme.json",
+  ["../../../../../tenants/*/theme.json", "../../../../../tenants/e2e/*/theme.json"],
   {
     eager: true,
     import: "default",
@@ -34,8 +43,7 @@ function stripMeta(obj: Record<string, unknown>): DeepPartial<ThemeTokens> {
 
 const THEMES: Record<string, DeepPartial<ThemeTokens>> = {};
 for (const [path, mod] of Object.entries(modules)) {
-  // Path looks like ".../tenants/<id>/theme.json" — the id is the dir segment.
-  const id = /\/tenants\/([^/]+)\/theme\.json$/.exec(path)?.[1];
+  const id = tenantIdFromPath(path);
   if (!id) continue;
   THEMES[id] = stripMeta(mod as Record<string, unknown>);
 }
@@ -45,7 +53,11 @@ export function getTenantTheme(tenantId: string): DeepPartial<ThemeTokens> {
   return THEMES[tenantId] ?? {};
 }
 
-/** Tenant ids that ship a theme file (for diagnostics / listing). */
-export function tenantsWithThemes(): string[] {
-  return Object.keys(THEMES);
+/**
+ * Tenant ids that ship a theme file (for diagnostics / listing). Platform test
+ * tenants are excluded by default — pass `{ includeTestTenants: true }` to see
+ * the whole set.
+ */
+export function tenantsWithThemes(opts: TenantListingOptions = {}): string[] {
+  return listedTenantIds(Object.keys(THEMES), opts);
 }

package/package.json

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

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

@@ -546,6 +546,97 @@ export function isInternalTestTenant(
   return t.classification === "internal-test" || t.appDomain.endsWith(".e2e.test");
 }
 
+// ---------------------------------------------------------------------------
+// Where a tenant's colocated directory lives.
+//
+// A tenant IS a directory. Real tenants sit directly under `tenants/<id>/`.
+// PLATFORM TEST tenants — every id ending `.e2e.test`, the single greppable
+// class — sit one level deeper, under `tenants/e2e/<id>/`, so `ls tenants/`
+// shows only real tenants and a generalized listing can drop the whole test
+// class with one predicate instead of a hand-maintained denylist.
+//
+// The id → directory mapping is TOTAL and mechanical: nothing else decides it,
+// so a glob, an fs walk, and a KV artifact path can never disagree about where
+// a tenant lives.
+// ---------------------------------------------------------------------------
+
+/** The directory segment platform test tenants are nested under. */
+export const E2E_TENANT_DIR = "e2e";
+
+/**
+ * True for a PLATFORM TEST tenant id — the `<scenario>.e2e.test` class. This is
+ * the id-only form of {@link isInternalTestTenant} (which also honours an
+ * explicit `classification`), for the many call sites that hold an id string
+ * and no config: globs, fs walks, CLI arguments, listing filters.
+ */
+export function isE2ETenantId(tenantId: string): boolean {
+  return /\.e2e\.test$/.test(tenantId);
+}
+
+/**
+ * The repo-relative directory for a tenant id: `tenants/e2e/<id>` for a test
+ * tenant, `tenants/<id>` for a real one. Always POSIX-separated — callers that
+ * need an OS path join its segments themselves.
+ */
+export function tenantDirRelative(tenantId: string): string {
+  return isE2ETenantId(tenantId)
+    ? `tenants/${E2E_TENANT_DIR}/${tenantId}`
+    : `tenants/${tenantId}`;
+}
+
+/**
+ * The `/tenants/…/<id>/` substring that identifies one tenant inside an
+ * absolute path or a Vite glob key — leading AND trailing slash, so a bare
+ * suffix match can never mistake `a.e2e.test` for `extra-a.e2e.test`.
+ */
+export function tenantDirSegment(tenantId: string): string {
+  return `/${tenantDirRelative(tenantId)}/`;
+}
+
+/**
+ * The tenant id a `…/tenants/[e2e/]<id>/…` path encodes, or null when the path
+ * names no tenant. The inverse of {@link tenantDirRelative}: the optional `e2e/`
+ * segment is consumed, so a nested test tenant yields its OWN id and never the
+ * literal `e2e`.
+ */
+export function tenantIdFromPath(path: string): string | null {
+  return /\/tenants\/(?:e2e\/)?([^/]+)\//.exec(path)?.[1] ?? null;
+}
+
+/** Opt back IN to platform test tenants on a generalized listing. */
+export interface TenantListingOptions {
+  /**
+   * Include platform test tenants. Default `false`: a GENERALIZED listing —
+   * one that enumerates "all tenants" for a human to look at or a bulk job to
+   * walk — shows only real tenants. A caller that genuinely wants the test
+   * class asks for it here, explicitly, at the call site.
+   */
+  includeTestTenants?: boolean;
+}
+
+/**
+ * Narrow a set of tenant ids to what a generalized listing should show.
+ * Platform test tenants are dropped unless explicitly requested.
+ */
+export function listedTenantIds(
+  ids: readonly string[],
+  opts: TenantListingOptions = {},
+): string[] {
+  return opts.includeTestTenants ? [...ids] : ids.filter((id) => !isE2ETenantId(id));
+}
+
+/**
+ * The listing counterpart for full configs — drops anything
+ * {@link isInternalTestTenant} recognizes (the `.e2e.test` class AND an
+ * explicitly marked clone), unless explicitly requested.
+ */
+export function listedTenants<T extends Pick<TenantConfig, "classification" | "appDomain">>(
+  tenants: readonly T[],
+  opts: TenantListingOptions = {},
+): T[] {
+  return opts.includeTestTenants ? [...tenants] : tenants.filter((t) => !isInternalTestTenant(t));
+}
+
 // ---------------------------------------------------------------------------
 // Non-premium (self-serve) tenant identity.
 //

package/scripts/build/copy-tenant-assets.mjs

@@ -31,10 +31,11 @@
  * reference files that don't exist. The Worker-plane build never sets this, so
  * R2 shadowing semantics are unchanged there.
  */
-import { cp, mkdir, readdir, rm } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { listTenantDirIds, tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const src = resolve(repoRoot, "tenants");
@@ -53,15 +54,21 @@ const versionedEnv = new Set(
     .filter(Boolean),
 );
 const bakeVersioned = process.env.TENANT_ASSETS_BAKE_VERSIONED === "1";
+const tenantDir = (id) => join(repoRoot, ...tenantDirSegments(id));
 const isVersioned = (id) =>
   !bakeVersioned &&
   (versionedEnv.has(id) ||
-    existsSync(join(src, id, ".tot", "assets-versioned")));
+    existsSync(join(tenantDir(id), ".tot", "assets-versioned")));
+
+// Both tiers: real tenants directly under tenants/, platform test tenants one
+// level deeper under tenants/e2e/. The destination stays FLAT — the served URL
+// is `/tenants/<id>/…` for every tenant, whichever tier its source sits in.
+const ids = listTenantDirIds(src, readdirSync, (p) => statSync(p).isDirectory(), join);
 
 let copied = 0;
 let skipped = 0;
-for (const id of await readdir(src)) {
-  const pub = join(src, id, "public");
+for (const id of ids) {
+  const pub = join(tenantDir(id), "public");
   if (!existsSync(pub)) continue;
   // Versioned tenants are served from R2 — baking would shadow the R2 route.
   if (isVersioned(id)) {

package/scripts/dev/ai-edit.mjs

@@ -24,12 +24,13 @@ import { join, dirname } from "node:path";
 import { createMcpClient } from "../../packages/cli/src/mcp.mjs";
 import { resolveDeveloperSession, AuthUnavailableError } from "../../packages/cli/src/auth.mjs";
 import { applyUnifiedDiff } from "./unified-diff.mjs";
+import { tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 /** Where a tenant's editable files + AI-edit history live (monorepo layout). */
 export function tenantPaths(repoRoot, tenantId) {
-  const dir = join(repoRoot, "tenants", tenantId);
+  const dir = join(repoRoot, ...tenantDirSegments(tenantId));
   return {
     dir,
     home: join(dir, "content", "home.html"),

package/scripts/dev/tenant-source-root.mjs

@@ -19,6 +19,7 @@
  */
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 /**
  * @returns {{ok:true, tenantId:string, sourceRoot:string, gitCwd:string}
@@ -72,5 +73,5 @@ export function resolveTenantSourceRoot(env = process.env) {
 export function resolveDevSourceRoot(workspacePath, repoRoot, tenant) {
   return workspacePath
     ? resolve(workspacePath)
-    : resolve(repoRoot, "tenants", tenant);
+    : resolve(repoRoot, ...tenantDirSegments(tenant));
 }

package/scripts/tot-dev.mjs

@@ -62,6 +62,7 @@ import {
 import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveDevSourceRoot } from "./dev/tenant-source-root.mjs";
+import { tenantDirRelative, tenantDirSegments } from "./lib/tenant-dirs.mjs";
 import { firstFreePort } from "./dev/port-check.mjs";
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
 
@@ -244,7 +245,7 @@ if (workspacePath) {
     // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
     const wsRel = String(map.workspace ?? "").replace(/\/+$/, "");
     if (!wsRel) continue;
-    const repoRel = join("tenants", tenant, wsRel);
+    const repoRel = join(tenantDirRelative(tenant), wsRel);
 
     const source = resolve(wsRoot, wsRel); // real files in the checkout
     const target = resolve(repoRoot, repoRel); // where the app globs them
@@ -288,7 +289,7 @@ if (workspacePath) {
     cleanupGrafts();
     process.exit(1);
   }
-} else if (!existsSync(resolve(repoRoot, "tenants", tenant, "content"))) {
+} else if (!existsSync(resolve(repoRoot, ...tenantDirSegments(tenant), "content"))) {
   console.warn(`⚠ no tenants/${tenant}/content/ found — the tenant may not be registered yet.`);
 }