@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,87 @@
+/**
+ * KV-backed tenant resolver — the many-tenant path documented in
+ * src/config/tenants.ts and wrangler.toml ([[kv_namespaces]] TENANT_CACHE).
+ *
+ * It implements the SAME `TenantResolver` interface as StaticTenantResolver, so
+ * middleware, pages, and the /<domain>/* path routing are untouched — only the
+ * backing store changes. Tenants are added by WRITING to KV (see putTenant),
+ * not by editing code, so onboarding/migration can register a store at runtime.
+ *
+ * KV layout:
+ *   domain:<host>          -> tenant_id        (one per claimed hostname)
+ *   tenant:<tenant_id>     -> JSON TenantConfig
+ *   config:default_tenant  -> tenant_id        (unknown-host fallback)
+ *
+ * A static `fallback` resolver is consulted when KV has no entry, so the system
+ * keeps working before KV is seeded and during a gradual cutover from static.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+
+const DOMAIN_PREFIX = "domain:";
+const TENANT_PREFIX = "tenant:";
+const DEFAULT_KEY = "config:default_tenant";
+// Edge-cache KV reads briefly; tenant config changes are rare and propagate
+// within this window. Bump down if you need faster propagation after a write.
+const CACHE_TTL = 300;
+
+function cleanHost(host: string): string {
+  return host.toLowerCase().split(":")[0]?.trim() ?? "";
+}
+
+export class KvTenantResolver implements TenantResolver {
+  constructor(
+    private readonly kv: KVNamespace,
+    /** Consulted when KV has no record (pre-seed / gradual cutover). */
+    private readonly fallback?: TenantResolver,
+  ) {}
+
+  private async readTenant(id: string): Promise<TenantConfig | null> {
+    const raw = await this.kv.get(TENANT_PREFIX + id, { cacheTtl: CACHE_TTL });
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as TenantConfig;
+    } catch {
+      return null;
+    }
+  }
+
+  async resolveStrict(host: string): Promise<TenantConfig | null> {
+    const clean = cleanHost(host);
+    if (!clean) return null;
+    const id = await this.kv.get(DOMAIN_PREFIX + clean, { cacheTtl: CACHE_TTL });
+    if (id) {
+      const tenant = await this.readTenant(id);
+      if (tenant) return tenant;
+    }
+    return this.fallback ? this.fallback.resolveStrict(host) : null;
+  }
+
+  async resolveByHost(host: string): Promise<TenantConfig | null> {
+    const strict = await this.resolveStrict(host);
+    if (strict) return strict;
+    const defaultId = await this.kv.get(DEFAULT_KEY, { cacheTtl: CACHE_TTL });
+    if (defaultId) {
+      const tenant = await this.readTenant(defaultId);
+      if (tenant) return tenant;
+    }
+    return this.fallback ? this.fallback.resolveByHost(host) : null;
+  }
+}
+
+/**
+ * Register (or update) a tenant in KV. Idempotent: writes the config blob and a
+ * domain->id index entry for each claimed hostname. Pass `makeDefault` to point
+ * the unknown-host fallback at this tenant. Call this from onboarding/migration.
+ */
+export async function putTenant(
+  kv: KVNamespace,
+  config: TenantConfig,
+  opts: { makeDefault?: boolean } = {},
+): Promise<void> {
+  await kv.put(TENANT_PREFIX + config.tenant_id, JSON.stringify(config));
+  for (const domain of config.domains) {
+    const host = cleanHost(domain);
+    if (host) await kv.put(DOMAIN_PREFIX + host, config.tenant_id);
+  }
+  if (opts.makeDefault) await kv.put(DEFAULT_KEY, config.tenant_id);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Tenant-resolver factory. Picks the backing store at request time:
+ *
+ *   - TENANT_CACHE KV bound (prod / wired dev)  -> KvTenantResolver over real KV.
+ *   - No KV binding (plain `astro dev`)         -> KvTenantResolver over an
+ *     in-memory KV seeded from the static registry, so the dynamic path and a
+ *     data-driven default are exercised locally without a Cloudflare account.
+ *
+ * Either way the caller gets a TenantResolver and nothing downstream changes.
+ * The static registry is passed as a fallback so unseeded hosts still resolve.
+ *
+ * The unknown-host default is data-driven: in prod it's the KV
+ * `config:default_tenant` key (set via putTenant({makeDefault:true})); in dev
+ * it's seeded from DEFAULT_TENANT_ID (falling back to the first static tenant).
+ * 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 { readEnv, readKv } from "@/lib/env";
+import { tenantResolver as staticResolver, staticTenants } from "@/config/tenants";
+import { KvTenantResolver, putTenant } from "@/config/kvTenantResolver";
+import { MemoryKv } from "@/lib/memoryKv";
+
+let devKvPromise: Promise<KVNamespace> | null = null;
+
+/** Build (once) an in-memory KV seeded from the static registry for dev. */
+function devKv(): Promise<KVNamespace> {
+  if (!devKvPromise) {
+    devKvPromise = (async () => {
+      const kv = new MemoryKv();
+      const configured = (await readEnv("DEFAULT_TENANT_ID"))?.trim();
+      const defaultId = configured || staticTenants[0]?.tenant_id;
+      for (const tenant of staticTenants) {
+        await putTenant(kv, tenant, { makeDefault: tenant.tenant_id === defaultId });
+      }
+      return kv;
+    })();
+  }
+  return devKvPromise;
+}
+
+export async function getTenantResolver(): Promise<TenantResolver> {
+  const kv = await readKv("TENANT_CACHE");
+  if (kv) return new KvTenantResolver(kv, staticResolver);
+  return new KvTenantResolver(await devKv(), staticResolver);
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Static tenant registry (Phase 1).
+ *
+ * ASSUMPTION: one pilot tenant lives in code here — when we go many-tenant this
+ * map moves to the TENANT_CACHE KV namespace (wrangler.toml) and the resolver
+ * gains an async KV read; the StaticTenantResolver interface stays identical so
+ * pages/middleware don't change. — to change: implement KvTenantResolver and
+ * select it by env in middleware.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+import { getTenantTheme } from "@/themes/tenants";
+
+// Default landing tenant — the fallback for unmatched hosts / bare localhost.
+// Placeholder "coming soon" content in content/home/* + a minimal theme; a real
+// homepage is built out later. This replaces the old "pilot" fixture tenant.
+// PRODUCT INTENT: "/" should route to the logged-in user's home — until that
+// auth-aware routing lands, an unmatched host falls back HERE, never to a fake
+// merchant. Registered first in REGISTRY so it is the resolver default (registry[0]).
+export const HOME_TENANT: TenantConfig = {
+  tenant_id: "home",
+  appDomain: "home",
+  domains: ["home", "tot-storefront.workers.dev"],
+  canonicalDomain: "home",
+  displayName: "Storefront",
+  storyblok_space_token:
+    import.meta.env.STORYBLOK_HOME_TOKEN ?? "STORYBLOK_HOME_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "home",
+  currency: "USD",
+  locale: "en-US",
+  // Per-tenant theme override from src/themes/tenants/<tenant_id>.theme.json
+  // (auto-discovered). Empty {} falls back to the reference theme.
+  theme_tokens: getTenantTheme("home"),
+  // Non-commerce placeholder: no catalog/compliance until the real home is built.
+  siteType: "marketing",
+};
+
+// Second pilot tenant — Big D Vapor (bigdvapor.net). Catalog migrated locally
+// from Shopify (big-d-vapor.myshopify.com) into out/catalog/bigdvapor/; brand
+// adopted into themes/tenants/bigdvapor.theme.json. tot_data_scope "bigdvapor"
+// matches the fixture dir + each record's tenant_id.
+export const BIGDVAPOR_TENANT: TenantConfig = {
+  tenant_id: "bigdvapor",
+  appDomain: "bigdvapor.net",
+  // + bigdvapor.tokenoftrust.store — the per-tenant hosted-store subdomain on our
+  // CF zone (reached via the *.tokenoftrust.store wildcard route; ADR-0007).
+  domains: ["bigdvapor.net", "www.bigdvapor.net", "bigdvapor.tokenoftrust.store"],
+  canonicalDomain: "bigdvapor.net",
+  displayName: "Big D Vapor",
+  storyblok_space_token:
+    import.meta.env.STORYBLOK_BIGDVAPOR_TOKEN ??
+    "STORYBLOK_BIGDVAPOR_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "bigdvapor",
+  currency: "USD",
+  locale: "en-US",
+  theme_tokens: getTenantTheme("bigdvapor"),
+  // Regulated vape/nicotine merchant (21+, PACT) — same compliance shape as pilot.
+  compliance: {
+    minAge: 21,
+    nicotineWarning: true,
+    shippingRestriction:
+      "Adult signature (21+) required on delivery. We can't ship vapor/nicotine products to some states due to PACT Act and local restrictions — verified at checkout.",
+  },
+  // Cart/checkout (Track A). Demo build points at the shared ToT demo FoxyCart
+  // store (test mode, cart validation OFF → no secret needed, so it runs on
+  // localhost AND the shared preview worker). Override the subdomain with
+  // FOXY_STORE_SUBDOMAIN; switch mode:"signed" + a real store secret for live.
+  // In live each merchant gets its own store + a branded checkout domain via
+  // `storeDomain` (e.g. secure.bigdvapor.net) — customer-visible at checkout.
+  commerce: {
+    foxy: { storeSubDomain: "tot-preview", mode: "unsigned-demo" },
+  },
+  // PR-gated capabilities (build-time default; overridden per-env by the
+  // published capabilities artifact). Regulated vape store → all three on.
+  capabilities: {
+    cartCheckout: { enabled: true },
+    ageVerification: { enabled: true },
+    exciseTax: { enabled: true },
+  },
+};
+
+// Token of Trust's own corporate/marketing site — the first NON-COMMERCE tenant.
+// siteType "marketing" flips the platform's commerce affordances off (no
+// catalog, search, saved, quick-view, product JSON-LD, or commerce sitemap; see
+// resolveTenantFeatures) so the shared component library renders a B2B SaaS site.
+// No `compliance` object: this is the corporate site, not a regulated store.
+// tot_data_scope has no catalog fixtures on purpose — the client returns empty.
+export const TOKENOFTRUST_TENANT: TenantConfig = {
+  tenant_id: "tokenoftrust",
+  appDomain: "tokenoftrust.com",
+  domains: ["tokenoftrust.com", "www.tokenoftrust.com"],
+  canonicalDomain: "tokenoftrust.com",
+  displayName: "Token of Trust",
+  // Marketing content lives locally under src/content/tokenoftrust/*.json; no
+  // Storyblok space is wired, so the LocalContentProvider renders it.
+  storyblok_space_token:
+    import.meta.env.STORYBLOK_TOKENOFTRUST_TOKEN ??
+    "STORYBLOK_TOKENOFTRUST_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "tokenoftrust",
+  currency: "USD",
+  locale: "en-US",
+  theme_tokens: getTenantTheme("tokenoftrust"),
+  siteType: "marketing",
+};
+
+// Third pilot tenant — Giant Vapes (giantvapes.com). Online vape shop since 2013,
+// reconstituted from the old "pilot" fixture into the colocated tenants/giantvapes/
+// layout. Brand adopted into tenants/giantvapes/theme.json (giant-navy). Marketing
+// chrome ported HYBRID (raw home.html + pages-html/** + public assets); commerce
+// routes are platform-served. tot_data_scope "giantvapes" seeded with a 50-product
+// sample pulled from the live giantvapes.com Shopify store into
+// out/catalog/giantvapes/ (products + collections), so /collections + /products
+// resolve. Same 21+/PACT compliance shape as bigdvapor.
+export const GIANTVAPES_TENANT: TenantConfig = {
+  tenant_id: "giantvapes",
+  appDomain: "giantvapes.com",
+  // + giantvapes.tokenoftrust.store — per-tenant hosted-store subdomain (see bigdvapor).
+  domains: ["giantvapes.com", "www.giantvapes.com", "giantvapes.tokenoftrust.store"],
+  canonicalDomain: "giantvapes.com",
+  displayName: "Giant Vapes",
+  storyblok_space_token:
+    import.meta.env.STORYBLOK_GIANTVAPES_TOKEN ??
+    "STORYBLOK_GIANTVAPES_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "giantvapes",
+  currency: "USD",
+  locale: "en-US",
+  theme_tokens: getTenantTheme("giantvapes"),
+  // Regulated vape/nicotine merchant (21+, PACT) — same compliance shape as bigdvapor.
+  compliance: {
+    minAge: 21,
+    nicotineWarning: true,
+    shippingRestriction:
+      "Adult signature (21+) required on delivery. We can't ship vapor/nicotine products to some states due to PACT Act and local restrictions — verified at checkout.",
+  },
+  // Cart/checkout (Track A) — shared demo FoxyCart store, see BIGDVAPOR_TENANT.
+  commerce: {
+    foxy: { storeSubDomain: "tot-preview", mode: "unsigned-demo" },
+  },
+  // PR-gated capabilities — regulated vape store → all three on.
+  capabilities: {
+    cartCheckout: { enabled: true },
+    ageVerification: { enabled: true },
+    exciseTax: { enabled: true },
+  },
+};
+
+// DEMO (storefront-runner): a renamed variant of an existing tenant — one object.
+// Reuses tokenoftrust's theme + content scope, served at its own path prefix
+// /tokenoftrust-preview.com/. This is the whole edit needed to add a tenant.
+export const TOKENOFTRUST_PREVIEW_TENANT: TenantConfig = {
+  ...TOKENOFTRUST_TENANT,
+  tenant_id: "tokenoftrust-preview",
+  appDomain: "tokenoftrust-preview.com",
+  domains: ["tokenoftrust-preview.com"],
+  canonicalDomain: "tokenoftrust-preview.com",
+  displayName: "Token of Trust (Preview)",
+};
+
+const REGISTRY: TenantConfig[] = [
+  HOME_TENANT,
+  BIGDVAPOR_TENANT,
+  TOKENOFTRUST_TENANT,
+  GIANTVAPES_TENANT,
+  TOKENOFTRUST_PREVIEW_TENANT,
+];
+
+/** The built-in tenants — seed source for the KV store (dev MemoryKv / prod). */
+export const staticTenants: TenantConfig[] = REGISTRY;
+
+export class StaticTenantResolver implements TenantResolver {
+  constructor(private readonly registry: TenantConfig[] = REGISTRY) {}
+
+  /** Strict domain match — null when no tenant explicitly claims `host`. */
+  async resolveStrict(host: string): Promise<TenantConfig | null> {
+    const clean = host.toLowerCase().split(":")[0]?.trim() ?? "";
+    if (!clean) return null;
+    return (
+      this.registry.find((t) =>
+        t.domains.some((d) => d.toLowerCase() === clean),
+      ) ?? null
+    );
+  }
+
+  async resolveByHost(host: string): Promise<TenantConfig | null> {
+    const match = await this.resolveStrict(host);
+    // Unmatched hosts / bare localhost fall back to the default HOME_TENANT
+    // (registry[0]) — the "coming soon" placeholder home, NOT a fake merchant.
+    // TODO: when auth-aware routing lands, "/" should go to the logged-in user's
+    // home instead of a static default.
+    return match ?? this.registry[0] ?? null;
+  }
+}
+
+export const tenantResolver: TenantResolver = new StaticTenantResolver();

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

@@ -0,0 +1,303 @@
+---
+/**
+ * Root layout. Injects per-tenant theme CSS vars at the edge, loads the font
+ * pairing, mounts header + footer chrome, and wires privacy-friendly analytics.
+ * Every page renders inside this.
+ */
+import "@/styles/global.css";
+import Seo from "@/components/Seo.astro";
+import Header from "@/components/nav/Header.astro";
+import Footer from "@/components/nav/Footer.astro";
+import QuickView from "@/components/islands/QuickView.tsx";
+import FoxyLoader from "@/components/commerce/FoxyLoader.astro";
+import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
+import IsolatedAgeGate from "@/components/islands/IsolatedAgeGate.tsx";
+import AuthBadge from "@/components/auth/AuthBadge.astro";
+import { referenceTheme } from "@/themes/reference";
+import { mergeTheme, themeFontHref } from "@/themes/schema";
+import { organizationLd, websiteLd } from "@/lib/jsonld";
+import { nonceInlineTags, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
+
+interface Props {
+  title: string;
+  description?: string;
+  path: string;
+  ogType?: "website" | "product" | "article";
+  ogImage?: string;
+  noindex?: boolean;
+  jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Wider pages (PLP/home) drop the prose max-width. */
+  fullBleed?: boolean;
+}
+
+const { title, description, path, ogType, ogImage, noindex, jsonLd } =
+  Astro.props;
+const { tenant, themeStyle, canonicalBase, basePath, cspNonce, features, capabilities } =
+  Astro.locals;
+
+// Organization JSON-LD is emitted site-wide (brief §8); pages add their own
+// graphs (Product, BreadcrumbList…) via the jsonLd prop.
+const pageGraphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
+const allJsonLd = [
+  organizationLd(tenant, canonicalBase),
+  websiteLd(tenant, canonicalBase),
+  ...pageGraphs,
+];
+
+const theme = mergeTheme(referenceTheme, tenant.theme_tokens);
+const fontHref = themeFontHref(theme);
+
+const chrome = await Astro.locals.content.getChrome();
+
+// SHARED CHROME: if the tenant ships content/<id>/chrome.html (the pixel-perfect
+// header/footer the raw marketing pages use), render THAT chrome around the
+// Layout content too — so commerce pages (collections/products/search/…) share
+// ONE chrome instead of the generic Header/Footer. Split the wrapper at
+// <!--PAGE_BODY-->: everything before = header, after = footer; pull its tenant
+// stylesheet links into <head>; nonce its inline tags for CSP. Tenants without a
+// chrome.html keep the token-driven Header/Footer (below).
+const chromeHtml = await Astro.locals.content.getChromeHtml();
+let sharedChrome: { header: string; footer: string; css: string[] } | null = null;
+if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
+  const headEnd = chromeHtml.indexOf("</head>");
+  const head = headEnd >= 0 ? chromeHtml.slice(0, headEnd) : "";
+  const css = [...head.matchAll(/<link[^>]+href="([^"]+\.css)"[^>]*>/gi)]
+    .map((m) => m[1] ?? "")
+    .filter((h) => h.startsWith("/tenants/"));
+  const bodyOpen = chromeHtml.indexOf(">", chromeHtml.indexOf("<body")) + 1;
+  const marker = chromeHtml.indexOf(CHROME_BODY_MARKER);
+  const bodyEnd = chromeHtml.lastIndexOf("</body>");
+  sharedChrome = {
+    header: nonceInlineTags(chromeHtml.slice(bodyOpen, marker), cspNonce),
+    footer: nonceInlineTags(chromeHtml.slice(marker + CHROME_BODY_MARKER.length, bodyEnd >= 0 ? bodyEnd : undefined), cspNonce),
+    css,
+  };
+}
+
+const compliance = tenant.compliance;
+
+const analyticsToken = import.meta.env.PUBLIC_CF_ANALYTICS_TOKEN;
+const analyticsEnabled =
+  analyticsToken && !/REPLACE|PLACEHOLDER/i.test(analyticsToken);
+---
+
+<!doctype html>
+<html lang={tenant.locale.split("-")[0] ?? "en"} data-base-path={basePath || undefined}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/svg+xml" href={theme.brand.favicon} />
+
+    {/* Per-tenant theme tokens injected at the edge (brief §7). */}
+    <style set:html={themeStyle} nonce={cspNonce}></style>
+
+    {/* Shared chrome's own stylesheet(s) (bigd-navy.css + mkt.css) so the ported
+        chrome renders in-brand on Layout (commerce) pages too. */}
+    {sharedChrome?.css.map((href) => <link rel="stylesheet" href={href} />)}
+
+    {
+      fontHref && (
+        <>
+          <link rel="preconnect" href="https://fonts.googleapis.com" />
+          <link
+            rel="preconnect"
+            href="https://fonts.gstatic.com"
+            crossorigin
+          />
+          <link rel="stylesheet" href={fontHref} />
+        </>
+      )
+    }
+
+    <Seo
+      title={title}
+      description={description}
+      path={path}
+      ogType={ogType}
+      ogImage={ogImage}
+      noindex={noindex}
+      jsonLd={allJsonLd}
+    />
+
+    {
+      analyticsEnabled && (
+        <script
+          defer
+          src="https://static.cloudflareinsights.com/beacon.min.js"
+          data-cf-beacon={`{"token": "${analyticsToken}"}`}
+        />
+      )
+    }
+  </head>
+  <body>
+    <a
+      href="#main"
+      class="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:m-3 focus:rounded-md focus:bg-[var(--color-primary)] focus:px-4 focus:py-2 focus:text-[var(--color-primary-contrast)]"
+    >
+      Skip to content
+    </a>
+
+    <AuthBadge />
+
+    {sharedChrome ? (
+      <Fragment set:html={sharedChrome.header} />
+    ) : (
+      <>
+        {compliance?.nicotineWarning && <NicotineWarning variant="bar" />}
+        <Header chrome={chrome} />
+      </>
+    )}
+
+    <main id="main">
+      <slot />
+    </main>
+
+    {sharedChrome ? (
+      <Fragment set:html={sharedChrome.footer} />
+    ) : (
+      <>
+        {compliance?.shippingRestriction && (
+          <div class="border-t border-[var(--color-border)] bg-[var(--color-bg)]" data-compliance="shipping-restriction">
+            <p class="container-prose py-3 text-center text-xs text-[var(--color-muted)]">
+              {compliance.shippingRestriction}
+            </p>
+          </div>
+        )}
+        <Footer chrome={chrome} />
+      </>
+    )}
+
+    {capabilities.ageVerification.enabled && compliance?.minAge && (
+      <IsolatedAgeGate client:load minAge={compliance.minAge} brand={tenant.displayName} />
+    )}
+
+    {/* Global quick-view dialog (opened by any [data-quickview] card button).
+        Commerce-only — marketing tenants ship no product UI. */}
+    {features.quickView && <QuickView client:idle locale={tenant.locale} />}
+
+    {/* Excise tax (Track B) — when enabled for this environment, the excise line
+        is calculated + added inside the FoxyCart cart (tot-foxycart pre-cart
+        webhook). This is the storefront's honest shopper-facing signal of it. */}
+    {capabilities.exciseTax.enabled && features.catalog && (
+      <p
+        class="border-t border-[var(--color-border)] bg-[var(--color-bg)] py-2.5 text-center text-xs text-[var(--color-muted)]"
+        data-capability="excise-tax"
+      >
+        Applicable excise tax is calculated at checkout.
+      </p>
+    )}
+
+    {/* FoxyCart loader (Powered by FoxyCart) — turns add-to-cart forms into the
+        sidecart + hosted checkout. Only for commerce tenants with a store. */}
+    <FoxyLoader />
+
+    {/* Wishlist hearts: event-delegated toggle + state hydration + count sync.
+        Cards/PDP carry [data-wishlist]; the header shows [data-wishlist-count].
+        Kept as one tiny script (no per-card hydration). Commerce-only — a
+        marketing tenant has no saved-items surface, so this never renders. */}
+    {features.savedItems && (
+    <script>
+      import {
+        readWishlist,
+        toggleSaved,
+        isSaved,
+        WISHLIST_EVENT,
+      } from "@/lib/wishlist";
+
+      function syncCount() {
+        const n = readWishlist().length;
+        document.querySelectorAll<HTMLElement>("[data-wishlist-count]").forEach((el) => {
+          el.textContent = n > 0 ? String(n) : "";
+          el.toggleAttribute("hidden", n === 0);
+        });
+      }
+
+      function syncHearts() {
+        document.querySelectorAll<HTMLButtonElement>(".wishlist-toggle").forEach((btn) => {
+          try {
+            const { handle } = JSON.parse(btn.getAttribute("data-wishlist") || "{}");
+            if (handle) btn.setAttribute("aria-pressed", String(isSaved(handle)));
+          } catch {}
+        });
+      }
+
+      document.addEventListener("click", (e) => {
+        const btn = (e.target as HTMLElement)?.closest?.<HTMLButtonElement>(".wishlist-toggle");
+        if (!btn) return;
+        e.preventDefault();
+        try {
+          const item = JSON.parse(btn.getAttribute("data-wishlist") || "{}");
+          if (!item.handle) return;
+          const saved = toggleSaved(item);
+          btn.setAttribute("aria-pressed", String(saved));
+        } catch {}
+      });
+
+      window.addEventListener(WISHLIST_EVENT, syncCount);
+      syncHearts();
+      syncCount();
+    </script>
+    )}
+
+    {/* Path-prefix tenant routing: when this request was selected via a
+        /<domain>/ path segment (locals.basePath), keep same-origin
+        root-absolute links inside that prefix so navigation stays on the
+        tenant. Host-routed requests have no base path and skip this entirely. */}
+    {basePath && (
+      <script is:inline nonce={cspNonce} define:vars={{ basePath }}>
+        (function () {
+          var base = basePath;
+          if (!base) return;
+          function fix(a) {
+            var href = a.getAttribute("href");
+            if (!href || href.charAt(0) !== "/" || href.charAt(1) === "/") return;
+            if (href === base || href.indexOf(base + "/") === 0) return;
+            a.setAttribute("href", base + href);
+          }
+          function fixAll() {
+            document.querySelectorAll('a[href^="/"]').forEach(fix);
+          }
+          if (document.readyState === "loading") {
+            document.addEventListener("DOMContentLoaded", fixAll);
+          } else {
+            fixAll();
+          }
+          // Late/island-rendered anchors: fix just-in-time before navigation.
+          document.addEventListener(
+            "pointerdown",
+            function (e) {
+              var a = e.target && e.target.closest && e.target.closest('a[href^="/"]');
+              if (a) fix(a);
+            },
+            true,
+          );
+        })();
+      </script>
+    )}
+
+    {/* Scroll-reveal + analytics pageview hook. ~0.5KB, no framework. */}
+    <script>
+      // Reveal-on-scroll (respects reduced motion via CSS).
+      const els = document.querySelectorAll("[data-reveal]");
+      if (
+        els.length &&
+        !window.matchMedia("(prefers-reduced-motion: reduce)").matches
+      ) {
+        const io = new IntersectionObserver(
+          (entries) => {
+            for (const e of entries) {
+              if (e.isIntersecting) {
+                e.target.classList.add("is-in");
+                io.unobserve(e.target);
+              }
+            }
+          },
+          { rootMargin: "0px 0px -8% 0px", threshold: 0.05 },
+        );
+        els.forEach((el) => io.observe(el));
+      } else {
+        els.forEach((el) => el.classList.add("is-in"));
+      }
+    </script>
+  </body>
+</html>

package/apps/storefront/src/lib/analytics/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Privacy-friendly analytics (brief §5 Analytics).
+ *
+ * Phase 1 ships TWO layers:
+ *  1. Pageviews — Cloudflare Web Analytics, a single beacon script injected in
+ *     Layout.astro when PUBLIC_CF_ANALYTICS_TOKEN is set (no cookies, no PII).
+ *  2. Commerce events — product impression/click/PDP-view instrumented NOW to a
+ *     NO-OP sink, so Phase 2 conversion work inherits the call sites for free.
+ *
+ * The event API is intentionally tiny and synchronous-looking; swap the sink
+ * (e.g. to a Workers Analytics Engine writer or a beacon) without touching call
+ * sites. See DECISIONS.md.
+ */
+
+export type CommerceEvent =
+  | { type: "product_impression"; handle: string; list?: string; position?: number }
+  | { type: "product_click"; handle: string; list?: string }
+  | { type: "pdp_view"; handle: string; variant_id?: string }
+  | { type: "search"; query: string; results: number }
+  | { type: "collection_view"; handle: string }
+  | { type: "newsletter_signup"; source: string };
+
+export interface AnalyticsSink {
+  track(event: CommerceEvent): void;
+}
+
+/** Default sink: discard. Visible in dev console when ?debugAnalytics is set. */
+export class NoOpSink implements AnalyticsSink {
+  constructor(private readonly debug = false) {}
+  track(event: CommerceEvent): void {
+    if (this.debug && typeof console !== "undefined") {
+      // eslint-disable-next-line no-console
+      console.debug("[analytics]", event);
+    }
+  }
+}
+
+let sink: AnalyticsSink = new NoOpSink();
+
+/** Phase 2: call setAnalyticsSink(new RealSink()) once at boot. */
+export function setAnalyticsSink(next: AnalyticsSink): void {
+  sink = next;
+}
+
+export function track(event: CommerceEvent): void {
+  sink.track(event);
+}