@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

package/apps/storefront/src/components/publication/storefront/islands/CatalogQueryView.tsx

@@ -0,0 +1,321 @@
+/**
+ * <CatalogQueryView> — applies a listing or search URL's query in the browser
+ * when the page's render did not (lib/publication/shared/staticQuery.ts). A
+ * static host serves one document per path, so `?sort=`, facets, price and
+ * `?q=` reach no renderer there; this island reads the static catalog index and
+ * replaces the rendered results (`[data-catalog-query-rendered]`) with the view
+ * the URL asks for. Where the render already applied the query (the Worker, the
+ * local dev loop) it renders nothing.
+ */
+import { useEffect, useState } from "preact/hooks";
+import type { Facet, ListProductsQuery } from "@tot/public-runtime";
+import {
+  bucketByKey,
+  collectionViewFromIndex,
+  loadCatalogIndex,
+  searchFromIndex,
+} from "@/lib/catalog/shared/catalogQueryView";
+import type { CatalogIndexProduct } from "@/lib/catalog/shared/catalogIndex";
+import { planCollectionQuery, searchQueryFromUrl } from "@/lib/publication/shared/staticQuery";
+import {
+  buildQueryString,
+  isPriceBucketActive,
+  toggleFacet,
+  togglePriceBucket,
+} from "@/lib/publication/shared/url";
+import { formatPrice } from "@/lib/content/shared/format";
+import { clientBasePath, withClientBase } from "@/lib/publication/shared/basePath";
+
+type Props =
+  | {
+      mode: "collection";
+      collection: string;
+      /** The page the route's path names. */
+      pathPage: number;
+      /** Tenant-prefixed collection path in the tenant's URL form: query links hang off it. */
+      linkBase: string;
+      /** Tenant-prefixed collection path, unformed: page variants hang off it. */
+      pageBase: string;
+      trailingSlash: boolean;
+      locale: string;
+    }
+  | { mode: "search"; trailingSlash: boolean; locale: string };
+
+type View =
+  | { kind: "collection"; query: ListProductsQuery; products: CatalogIndexProduct[]; page: number; pageSize: number; total: number; facets: Facet[] }
+  | { kind: "search"; q: string; products: CatalogIndexProduct[] }
+  | { kind: "error" };
+
+function renderedRegion(): HTMLElement | null {
+  return document.querySelector<HTMLElement>("[data-catalog-query-rendered]");
+}
+
+export default function CatalogQueryView(props: Props) {
+  const [view, setView] = useState<View | null>(null);
+
+  useEffect(() => {
+    const region = renderedRegion();
+    const appliedKey = region?.dataset.appliedQuery ?? null;
+    const url = new URL(window.location.href);
+    let run: (() => Promise<View>) | null = null;
+
+    if (props.mode === "collection") {
+      const plan = planCollectionQuery({
+        url,
+        pathPage: props.pathPage,
+        appliedKey,
+        pageBase: props.pageBase,
+        trailingSlash: props.trailingSlash,
+      });
+      if (plan.kind === "rendered") return;
+      if (plan.kind === "redirect") {
+        window.location.replace(plan.href);
+        return;
+      }
+      run = async () => {
+        const index = await loadCatalogIndex(clientBasePath());
+        return { kind: "collection", query: plan.query, ...collectionViewFromIndex(index, props.collection, plan.query) } as View;
+      };
+    } else {
+      const q = searchQueryFromUrl(url);
+      if (appliedKey !== null && q === appliedKey) return;
+      run = async () => {
+        const index = await loadCatalogIndex(clientBasePath());
+        return { kind: "search", q, products: q ? searchFromIndex(index, q) : [] };
+      };
+    }
+
+    run()
+      .then(setView)
+      .catch(() => setView({ kind: "error" }));
+  }, []);
+
+  useEffect(() => {
+    if (!view || view.kind === "error") return;
+    const region = renderedRegion();
+    if (region) region.style.display = "none";
+    if (view.kind === "search") {
+      const heading = document.querySelector<HTMLElement>("[data-search-heading]");
+      if (heading) heading.textContent = view.q ? `Results for “${view.q}”` : "What are you after?";
+      const input = document.querySelector<HTMLInputElement>("input[name=q]");
+      if (input) input.value = view.q;
+    }
+  }, [view]);
+
+  if (!view || view.kind === "error") return null;
+  const productHref = (handle: string) => {
+    const path = withClientBase(`/products/${handle}`);
+    return props.trailingSlash && !path.endsWith("/") ? `${path}/` : path;
+  };
+
+  if (view.kind === "search") {
+    return (
+      <div class="container-prose pb-[clamp(2rem,5vw,3.5rem)]" data-widget="catalog-query-search">
+        <p class="mb-6 text-sm text-[var(--color-muted)]">
+          {view.products.length} {view.products.length === 1 ? "result" : "results"}
+        </p>
+        {view.q && view.products.length === 0 ? (
+          <p class="display-md">No matches for “{view.q}”</p>
+        ) : (
+          <Grid products={view.products} locale={props.locale} productHref={productHref} wide />
+        )}
+      </div>
+    );
+  }
+
+  const linkBase = props.mode === "collection" ? props.linkBase : "";
+  return (
+    <CollectionResults view={view} linkBase={linkBase} locale={props.locale} productHref={productHref} />
+  );
+}
+
+function Grid(props: {
+  products: CatalogIndexProduct[];
+  locale: string;
+  productHref: (handle: string) => string;
+  wide?: boolean;
+}) {
+  return (
+    <ul class={props.wide ? "grid grid-cols-2 gap-5 lg:grid-cols-4" : "grid grid-cols-2 gap-5 lg:grid-cols-3"}>
+      {props.products.map((p) => {
+        const img = p.image;
+        return (
+          <li class="group relative">
+            <div class="relative aspect-[4/5] overflow-hidden rounded-md bg-[var(--color-border)] ring-1 ring-[var(--color-border)]">
+              {img?.url && (
+                <img
+                  src={img.url}
+                  alt={img.alt ?? p.title}
+                  width={400}
+                  height={500}
+                  loading="lazy"
+                  class="h-full w-full object-cover transition-transform duration-500 motion-safe:group-hover:scale-[1.03]"
+                />
+              )}
+            </div>
+            <a href={props.productHref(p.handle)} class="mt-3 block after:absolute after:inset-0">
+              {p.vendor && (
+                <span class="block font-mono text-[0.62rem] uppercase tracking-[0.14em] text-[var(--color-muted)]">
+                  {p.vendor}
+                </span>
+              )}
+              <span class="mt-1 block font-display text-[0.95rem] font-medium leading-snug">{p.title}</span>
+              <span class="mt-1 block font-display text-sm tabular-nums">
+                {formatPrice(p.price_range.min, p.price_range.currency, props.locale)}
+              </span>
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+const SORTS: { value: NonNullable<ListProductsQuery["sort"]>; label: string }[] = [
+  { value: "featured", label: "Featured" },
+  { value: "newest", label: "Newest" },
+  { value: "price-asc", label: "Price: Low to High" },
+  { value: "price-desc", label: "Price: High to Low" },
+  { value: "title-asc", label: "Alphabetical (A–Z)" },
+];
+
+function CollectionResults(props: {
+  view: Extract<View, { kind: "collection" }>;
+  linkBase: string;
+  locale: string;
+  productHref: (handle: string) => string;
+}) {
+  const { query, products, page, pageSize, total, facets } = props.view;
+  const base = props.linkBase;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const chips: { label: string; href: string }[] = [];
+  for (const [name, values] of Object.entries(query.filters ?? {})) {
+    for (const v of values) chips.push({ label: name === "tags" ? `#${v}` : `${name}: ${v}`, href: base + toggleFacet(query, name, v) });
+  }
+  if (query.priceMin != null || query.priceMax != null) {
+    const { priceMin: _min, priceMax: _max, ...rest } = query;
+    chips.push({ label: `$${query.priceMin ?? 0}–${query.priceMax != null ? `$${query.priceMax}` : "any"}`, href: base + buildQueryString(rest) });
+  }
+  if (query.availability === "in-stock") {
+    const { availability: _a, ...rest } = query;
+    chips.push({ label: "In stock", href: base + buildQueryString(rest) });
+  }
+  const selected = (name: string, value: string) => (query.filters?.[name] ?? []).includes(value);
+  const facetLabel = (name: string) => (name === "tags" ? "Tags" : name === "availability" ? "Availability" : name);
+  const ordered = facets
+    .filter((f) => f.name !== "price")
+    .sort((a, b) => {
+      const rank = (n: string) => (n === "availability" ? 2 : n === "tags" ? 1 : 0);
+      return rank(a.name) - rank(b.name);
+    });
+  const priceFacet = facets.find((f) => f.name === "price");
+  const option = (href: string, label: string, count: number, isSel: boolean) => (
+    <li>
+      <a
+        href={href}
+        rel="nofollow"
+        aria-current={isSel ? "true" : undefined}
+        class={`flex items-center justify-between gap-3 rounded-[var(--radius-sm)] px-2 py-1 ${isSel ? "bg-[var(--color-primary)] text-[var(--color-primary-contrast)]" : "hover:bg-[color-mix(in_srgb,var(--color-primary)_8%,transparent)]"}`}
+      >
+        <span>{isSel ? "✓ " : ""}{label}</span>
+        <span class="text-xs">{count}</span>
+      </a>
+    </li>
+  );
+
+  return (
+    <div class="container-prose grid gap-10 pb-16 lg:grid-cols-[230px_1fr]" data-widget="catalog-query-collection">
+      <aside aria-label="Filters" class="text-sm lg:sticky lg:top-24 lg:self-start">
+        <div class="space-y-7">
+          {ordered.map((facet) => (
+            <fieldset>
+              <legend class="mb-2.5 font-display text-[0.95rem] font-medium">{facetLabel(facet.name)}</legend>
+              <ul class="space-y-1.5">
+                {facet.values.map((fv) =>
+                  option(
+                    base + toggleFacet(query, facet.name, fv.value),
+                    fv.value === "all" ? "All items" : fv.value,
+                    fv.count,
+                    selected(facet.name, fv.value),
+                  ),
+                )}
+              </ul>
+            </fieldset>
+          ))}
+          {priceFacet && (
+            <fieldset>
+              <legend class="mb-2.5 font-display text-[0.95rem] font-medium">Price</legend>
+              <ul class="space-y-1.5">
+                {priceFacet.values.map((fv) => {
+                  const bucket = bucketByKey(fv.value);
+                  return bucket
+                    ? option(base + togglePriceBucket(query, bucket), bucket.label, fv.count, isPriceBucketActive(query, bucket))
+                    : null;
+                })}
+              </ul>
+            </fieldset>
+          )}
+        </div>
+      </aside>
+
+      <div>
+        <div class="mb-5 flex flex-wrap items-center justify-between gap-3 border-b border-[var(--color-border)] pb-4">
+          <p class="text-sm text-[var(--color-muted)]">
+            {total} {total === 1 ? "item" : "items"}
+          </p>
+          <label class="flex items-center gap-2 text-sm">
+            <span class="text-[var(--color-muted)]">Sort</span>
+            <select
+              class="rounded-[var(--radius-sm)] border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 font-display"
+              onChange={(e) => {
+                const sort = (e.currentTarget as HTMLSelectElement).value as ListProductsQuery["sort"];
+                window.location.assign(base + buildQueryString(query, { sort, page: 1 }));
+              }}
+            >
+              {SORTS.map((o) => (
+                <option value={o.value} selected={o.value === (query.sort ?? "featured")}>{o.label}</option>
+              ))}
+            </select>
+          </label>
+        </div>
+
+        {chips.length > 0 && (
+          <div class="mb-5 flex flex-wrap items-center gap-2">
+            {chips.map((chip) => (
+              <a href={chip.href} rel="nofollow" class="inline-flex items-center gap-1.5 rounded-full border border-[var(--color-border)] bg-[var(--color-surface)] py-1 pl-3 pr-2 text-xs">
+                <span>{chip.label}</span>
+                <span aria-hidden="true">×</span>
+                <span class="sr-only">Remove filter</span>
+              </a>
+            ))}
+            <a href={base} rel="nofollow" class="ml-1 text-xs text-[var(--color-muted)] underline underline-offset-2">Clear all</a>
+          </div>
+        )}
+
+        {products.length === 0 ? (
+          <p class="display-md">Nothing matches — yet</p>
+        ) : (
+          <Grid products={products} locale={props.locale} productHref={props.productHref} />
+        )}
+
+        {pageCount > 1 && (
+          <nav aria-label="Pagination" class="mt-12 flex justify-center">
+            <ul class="flex items-center gap-1">
+              {Array.from({ length: pageCount }, (_, i) => i + 1).map((p) => (
+                <li>
+                  <a
+                    href={base + buildQueryString(query, { page: p })}
+                    aria-current={p === page ? "page" : undefined}
+                    class={`grid h-9 w-9 place-items-center rounded-[var(--radius-sm)] font-display text-sm ${p === page ? "bg-[var(--color-primary)] text-[var(--color-primary-contrast)]" : "hover:bg-[var(--color-surface)]"}`}
+                  >
+                    {p}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -19,8 +19,9 @@ import {
   type DeclaredTenantConfig,
 } from "@tot/public-runtime/declared-tenant-config";
 import {
-  readPublishedArtifact,
-  readVersionArtifact,
+  customizationArtifactKey,
+  readSiteVersion,
+  resolvePublishedArtifactKey,
   tenantIdFromPath,
   type CustomizationEnv,
   type TenantConfig,
@@ -55,40 +56,67 @@ export function checkoutDeclaredTenantConfig(tenantId: string): DeclaredTenantCo
     ?? checkoutConfigFiles[`../../../../tenants/e2e/${tenantId}/.tot/config.json`]);
 }
 
-/** The declaration the reconcile published for this environment, or `{}`. */
-export async function publishedDeclaredTenantConfig(
-  kvGet: (key: string) => Promise<string | null>,
-  tenantId: string,
-  env: CustomizationEnv,
-): Promise<DeclaredTenantConfig> {
-  const raw = await readPublishedArtifact(kvGet, tenantId, env, declaredTenantConfigArtifactPath(tenantId));
-  if (!raw) return {};
+/**
+ * A stored declaration read back: what it declares, or `null` when it could not be read.
+ * `null` is never "declares nothing" — a regulated store whose compliance lives only in its
+ * `.tot/config.json` would read as unregulated. A judge takes it as unread
+ * (`declaredComplianceSignals`); a render refuses (`DeclaredTenantConfigUnreadError`).
+ */
+export type DeclarationRead = DeclaredTenantConfig | null;
+
+function parseDeclaration(raw: string | null): DeclarationRead {
+  if (raw === null) return null;
   try {
     return declaredTenantConfig(JSON.parse(raw));
   } catch {
-    return {};
+    return null;
   }
 }
 
-/** The declaration pinned to one immutable version (a candidate under review), or `{}`. */
-export async function versionDeclaredTenantConfig(
+/**
+ * The declaration the reconcile published for this environment. `{}` when the environment
+ * serves no declaration (nothing published, or the served version has none); `null` when the
+ * served version names one whose body cannot be read or parsed.
+ */
+export async function readPublishedDeclaration(
+  kvGet: (key: string) => Promise<string | null>,
+  tenantId: string,
+  env: CustomizationEnv,
+): Promise<DeclarationRead> {
+  const key = await resolvePublishedArtifactKey(kvGet, tenantId, env, declaredTenantConfigArtifactPath(tenantId));
+  return key ? parseDeclaration(await kvGet(key)) : {};
+}
+
+/**
+ * The declaration pinned to one immutable version (a candidate under review). `{}` when the
+ * version carries none (the reconcile materializes only a non-empty declaration); `null` when
+ * the version's manifest cannot be read, or it lists a declaration whose body cannot be read or
+ * parsed.
+ */
+export async function readVersionDeclaration(
   kvGet: (key: string) => Promise<string | null>,
   tenantId: string,
   versionId: string,
-): Promise<DeclaredTenantConfig> {
-  const raw = await readVersionArtifact(kvGet, tenantId, versionId, declaredTenantConfigArtifactPath(tenantId));
-  if (!raw) return {};
-  try {
-    return declaredTenantConfig(JSON.parse(raw));
-  } catch {
-    return {};
+): Promise<DeclarationRead> {
+  const manifest = await readSiteVersion(kvGet, tenantId, versionId);
+  if (!manifest) return null;
+  const contentHash = manifest.artifacts?.[declaredTenantConfigArtifactPath(tenantId)];
+  return contentHash ? parseDeclaration(await kvGet(customizationArtifactKey(tenantId, contentHash))) : {};
+}
+
+/** A render refused because the declaration it would render under could not be read. */
+export class DeclaredTenantConfigUnreadError extends Error {
+  constructor(tenantId: string, source: string) {
+    super(`declared config unreadable for ${tenantId} (${source}); refusing to render without it`);
+    this.name = "DeclaredTenantConfigUnreadError";
   }
 }
 
 /**
  * The tenant as it renders: its record with every declaration applied. A render
  * pinned to one version (a candidate under review) takes that version's
- * declaration; otherwise the environment's channel supplies it.
+ * declaration; otherwise the environment's channel supplies it. Throws
+ * {@link DeclaredTenantConfigUnreadError} when that declaration cannot be read.
  */
 export async function withDeclaredTenantConfig(
   tenant: TenantConfig,
@@ -96,10 +124,14 @@ export async function withDeclaredTenantConfig(
   source: { env: CustomizationEnv; pinnedVersionId?: string },
 ): Promise<TenantConfig> {
   const fromCheckout = applyDeclaredTenantConfig(tenant, checkoutDeclaredTenantConfig(tenant.tenant_id));
-  return applyDeclaredTenantConfig(
-    fromCheckout,
-    source.pinnedVersionId
-      ? await versionDeclaredTenantConfig(kvGet, tenant.tenant_id, source.pinnedVersionId)
-      : await publishedDeclaredTenantConfig(kvGet, tenant.tenant_id, source.env),
-  );
+  const declared = source.pinnedVersionId
+    ? await readVersionDeclaration(kvGet, tenant.tenant_id, source.pinnedVersionId)
+    : await readPublishedDeclaration(kvGet, tenant.tenant_id, source.env);
+  if (declared === null) {
+    throw new DeclaredTenantConfigUnreadError(
+      tenant.tenant_id,
+      source.pinnedVersionId ? `version ${source.pinnedVersionId}` : `channel ${source.env}`,
+    );
+  }
+  return applyDeclaredTenantConfig(fromCheckout, declared);
 }

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

@@ -27,6 +27,7 @@
  */
 import type { DeepPartial, TenantConfig, ThemeTokens } from "@tot/public-runtime";
 import { SHARED_DEMO_CHECKOUT } from "@tot/public-runtime";
+import { DEFAULT_CURRENCY } from "@tot/public-runtime/declared-tenant-config";
 import { rootPublicationSpaceConfig } from "./publicationSpaceConfig";
 import { loadTenantAnalyticsDeclarations } from "@/lib/integrations/integration/tenantAnalyticsDeclarations";
 
@@ -81,7 +82,7 @@ export function synthesizeDevTenant(
     // content/home.html (globbed by dir == this id).
     storyblok_space_token: "STORYBLOK_DEV_TENANT_TOKEN_PLACEHOLDER",
     tot_data_scope: appDomain,
-    currency: "USD",
+    currency: DEFAULT_CURRENCY,
     locale: "en-US",
     theme_tokens: themeTokens,
     publicationSpaces: [rootPublicationSpaceConfig(id, {

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

@@ -483,7 +483,7 @@ const footerWidgets = await renderWidgetSlot(
 
     {/* Checkout loader — turns add-to-cart forms into the cart drawer + hosted
         checkout. Only for commerce tenants with a store. */}
-    <CheckoutLoader />
+    <CheckoutLoader nonce={cspNonce} />
 
     {/* Brand the in-page cart drawer to the tenant theme (baseline + optional
         per-tenant commerce.checkout.cartDrawerCss override). Commerce tenants only. */}

package/apps/storefront/src/lib/access/auth/gatePage.ts

@@ -11,6 +11,8 @@
  * renders publicly so people can browse + sign up.
  */
 
+import { GATE_REMEDY, type GateReason } from "@/lib/access/shared/publicAccess";
+
 /** Escape a string for safe interpolation into an HTML attribute value. */
 function escapeAttr(s: string): string {
   return s
@@ -62,6 +64,7 @@ export function gatedHoldingHtml(loginHref: string): string {
     <span class="badge">Token of Trust</span>
     <h1>Coming soon</h1>
     <p>This storefront isn't open to the public yet. If you have access, sign in to preview it.</p>
+    <p style="font-size:.85rem;color:#94a3b8">Store owner? This hosted address is a sign-in review surface and stays gated by design; your public site is served on your own domain.</p>
     <a class="btn" href="${href}">Sign in</a>
   </main>
 </body>
@@ -75,17 +78,26 @@ export function gatedHoldingHtml(loginHref: string): string {
  */
 export const GATE_HEADER = "x-tot-gate";
 export const GATE_WITHHELD = "store-not-public";
+/** Why the gate withheld, and where the answer to "what turns it off" lives. */
+export const GATE_REASON_HEADER = "x-tot-gate-reason";
+export const GATE_DOCS_HEADER = "x-tot-gate-docs";
+export const GATE_DOCS = "runbook://storefront-publish-go-live";
+
+function gateHeaders(reason: GateReason): Record<string, string> {
+  return {
+    "cache-control": "no-store",
+    "x-robots-tag": "noindex, nofollow",
+    [GATE_HEADER]: GATE_WITHHELD,
+    [GATE_REASON_HEADER]: reason,
+    [GATE_DOCS_HEADER]: GATE_DOCS,
+  };
+}
 
 /** A `200 OK` holding page — never indexed, never cached. */
-export function gatedHoldingResponse(loginHref: string): Response {
+export function gatedHoldingResponse(loginHref: string, reason: GateReason): Response {
   return new Response(gatedHoldingHtml(loginHref), {
     status: 200,
-    headers: {
-      "content-type": "text/html; charset=utf-8",
-      "cache-control": "no-store",
-      "x-robots-tag": "noindex, nofollow",
-      [GATE_HEADER]: GATE_WITHHELD,
-    },
+    headers: { ...gateHeaders(reason), "content-type": "text/html; charset=utf-8" },
   });
 }
 
@@ -103,12 +115,8 @@ function isNavigation(request: Request): boolean {
  * the holding page with its Sign-in button, the same answer the store's pages give;
  * a fetch gets JSON naming the reason and where to sign in.
  */
-export function gatedApiResponse(loginHref: string, request: Request): Response {
-  const headers = {
-    "cache-control": "no-store",
-    "x-robots-tag": "noindex, nofollow",
-    [GATE_HEADER]: GATE_WITHHELD,
-  };
+export function gatedApiResponse(loginHref: string, request: Request, reason: GateReason): Response {
+  const headers = gateHeaders(reason);
   if (isNavigation(request)) {
     return new Response(gatedHoldingHtml(loginHref), {
       status: 401,
@@ -116,7 +124,14 @@ export function gatedApiResponse(loginHref: string, request: Request): Response
     });
   }
   return new Response(
-    JSON.stringify({ ok: false, error: GATE_WITHHELD, signIn: loginHref }),
+    JSON.stringify({
+      ok: false,
+      error: GATE_WITHHELD,
+      reason,
+      remedy: GATE_REMEDY[reason],
+      docs: GATE_DOCS,
+      signIn: loginHref,
+    }),
     { status: 401, headers: { ...headers, "content-type": "application/json; charset=utf-8" } },
   );
 }

package/apps/storefront/src/lib/access/shared/publicAccess.ts

@@ -0,0 +1,95 @@
+/**
+ * Can the public see this store? — the one answer, derived from the SAME inputs the
+ * login gate (`controlPlane.ts` → `evaluateLoginGate`) decides on, so the pipeline
+ * verdict, the gate's own response headers, and the docs can never disagree.
+ *
+ * The gate withholds a store (the "Coming soon" page, `x-tot-gate: store-not-public`) for
+ * exactly two reasons, and no others:
+ *
+ *   - `shared-preview-host`: the request host is on `DEMO_GATE_HOSTS` (the shared
+ *     `*.tokenoftrust.store` hosts) in `login` mode and the platform registry does not
+ *     declare the tenant `access.public`. That is the permanent state of every hosted
+ *     preview URL, by design: it is a review surface, not a storefront.
+ *   - `storefront-unpaid`: `storefront.mode` is explicitly set to something other than
+ *     `"enabled"`. This gates the tenant on every host the Worker serves, billing-bound.
+ *
+ * A tenant's own public site is not on the shared host. Cloudflare tenants are served by
+ * the Worker on their own domain once it is attached (not in `DEMO_GATE_HOSTS`, so the
+ * gate does not apply); CloudFront (`s3-overwrite`) tenants are served CDN -> S3 with no
+ * Worker in the path, so the gate never applies to the public site at all.
+ */
+import { hostInGateList } from "./demoGate";
+import { storefrontModeRequiresSignIn } from "@tot/public-runtime";
+
+export type GateReason = "shared-preview-host" | "storefront-unpaid";
+
+export interface PublicAccessInput {
+  /** The tenant's `storefront.mode`. */
+  storefrontMode: string | null | undefined;
+  /** `tenantIsDeclaredPublic(tenantId)` — the platform registry, never the KV record. */
+  declaredPublic: boolean;
+  /** `DEMO_GATE_MODE` parsed (`parseGateMode`). */
+  gateMode: "password" | "login";
+  /** `DEMO_GATE_HOSTS`. */
+  gateHosts: string | null | undefined;
+  /** `serving.provider`. */
+  provider: "worker-r2-pointer" | "s3-overwrite";
+  /** The host the question is asked on (the shared hosted URL's host). */
+  requestHost: string;
+  /** The tenant's hostnames that are real domains (not the shared preview hosts). */
+  domains: readonly string[];
+}
+
+export interface PublicAccess {
+  /** The shared hosted URL (`https://storefront.tokenoftrust.store/<tenant>/`). */
+  sharedHost: "gated" | "public";
+  /** The tenant's own domain(s) as served today by the Worker or CDN. */
+  ownDomain: "public" | "gated";
+  /** Why `sharedHost` / `ownDomain` is gated; absent when both are public. */
+  reason?: GateReason;
+  /** `x-tot-gate` value a withheld response carries. */
+  gateHeader: "store-not-public";
+  /** One sentence a person or agent can relay as the answer to "can the public see my store?". */
+  summary: string;
+  /** What turns the gate off, or the honest statement that nothing should. */
+  remedy: string;
+}
+
+export const GATE_REMEDY: Record<GateReason, string> = {
+  "shared-preview-host":
+    "Nothing to flip: the shared hosted URL is a sign-in review surface for every store. " +
+    "Visitors see the store on its own domain once the domain is attached; use a preview link (tot preview token) to show reviewers the pages. " +
+    "See runbook://storefront-publish-go-live (\"Can the public see my store?\").",
+  "storefront-unpaid":
+    "The store's storefront mode is not \"enabled\" (unpaid). Enable the storefront plan " +
+    "(scripts/tenant/set-storefront-mode.mjs --mode=enabled, a Token of Trust staff action); until then only signed-in members and preview links reach it.",
+};
+
+export function describePublicAccess(input: PublicAccessInput): PublicAccess {
+  const unpaid = storefrontModeRequiresSignIn(input.storefrontMode);
+  const sharedGated =
+    unpaid || (!input.declaredPublic && input.gateMode === "login" && hostInGateList(input.requestHost, input.gateHosts));
+  const ownHostGated =
+    unpaid ||
+    (!input.declaredPublic &&
+      input.provider === "worker-r2-pointer" &&
+      input.gateMode === "login" &&
+      input.domains.some((d) => hostInGateList(d, input.gateHosts)));
+  const reason: GateReason | undefined = unpaid ? "storefront-unpaid" : sharedGated ? "shared-preview-host" : undefined;
+  const substrate = input.provider === "s3-overwrite" ? "CloudFront" : "Cloudflare";
+  const summary = unpaid
+    ? "No: the store is unpaid (storefront.mode is not enabled), so every hosted URL shows \"Coming soon\" to signed-out visitors."
+    : sharedGated
+      ? ownHostGated
+        ? "No: every domain this store has points at a gated host, so signed-out visitors see \"Coming soon\"."
+        : `The shared hosted URL always shows "Coming soon" to signed-out visitors (by design); the public sees the store only on its own domain, served by ${substrate}.`
+      : "Yes: signed-out visitors can see the store.";
+  return {
+    sharedHost: sharedGated ? "gated" : "public",
+    ownDomain: ownHostGated ? "gated" : "public",
+    ...(reason ? { reason } : {}),
+    gateHeader: "store-not-public",
+    summary,
+    remedy: reason ? GATE_REMEDY[reason] : "None needed.",
+  };
+}

package/apps/storefront/src/lib/access/shared/tenantRouting.ts

@@ -30,6 +30,25 @@ export interface TenantRouting {
   renderPath: string;
 }
 
+/** Keep preview navigation on its session host whenever that host can route the target. */
+export function previewDashboardHref(
+  appDomain: string,
+  scope: {
+    routedTenant?: Pick<TenantConfig, "appDomain">;
+    basePath: string;
+    hostTenant: Pick<TenantConfig, "appDomain" | "pathPrefixTenants"> | null;
+    sharedOrigin: string;
+  },
+): string {
+  if (scope.routedTenant?.appDomain === appDomain) {
+    return `${scope.basePath}/preview/dashboard`;
+  }
+  const path = `/${encodeURIComponent(appDomain)}/preview/dashboard`;
+  return scope.hostTenant && !scope.hostTenant.pathPrefixTenants
+    ? new URL(path, scope.sharedOrigin).href
+    : path;
+}
+
 /**
  * A path segment is treated as a tenant-domain candidate only if it looks like
  * a hostname (has a dot, no "@" or other path-ish junk). Real first segments