@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,102 @@
+/**
+ * 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 —
+ * and in DEV that fallback ALSO covers the local dev loop's own checked-out
+ * tenant (see devFallbackResolver below). Note the @astrojs/cloudflare dev
+ * runtime proxies a (local, empty) TENANT_CACHE KV from wrangler.toml, so plain
+ * `astro dev` usually takes the KV-bound branch and resolves static/dev tenants
+ * through this shared FALLBACK — not the seeded MemoryKv.
+ *
+ * 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,
+  StaticTenantResolver,
+} from "@/config/tenants";
+import { KvTenantResolver, putTenant } from "@/config/kvTenantResolver";
+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,
+// 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).
+const localTenantFiles = import.meta.glob([
+  "../../../../tenants/*/theme.json",
+  "../../../../tenants/*/content/home.html",
+  "../../../../tenants/*/content/home.json",
+]);
+
+/** Dir names under `tenants/*` (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];
+    if (id) ids.add(id);
+  }
+  return [...ids];
+}
+
+/**
+ * The fallback resolver consulted on a KV miss. In PROD it's the plain static
+ * registry. In DEV it's the static registry EXTENDED with a synthesized,
+ * servable tenant for each local `tenants/<id>/` dir that isn't already static —
+ * so a developer's OWN checked-out tenant (grafted by `tot dev`, never in
+ * staticTenants) resolves at `/<appDomain>/` from its checkout instead of
+ * 404ing. Static tenants keep their richer hardcoded config (they're skipped by
+ * devTenantsToSeed). Used as the fallback in BOTH resolver branches, so it works
+ * whether or not the dev runtime binds a local TENANT_CACHE KV.
+ */
+function devFallbackResolver(): TenantResolver {
+  if (!import.meta.env.DEV) return staticResolver;
+  const staticIds = new Set(staticTenants.map((t) => t.tenant_id));
+  const dev = devTenantsToSeed(localTenantDirIds(), staticIds, getTenantTheme);
+  if (dev.length === 0) return staticResolver;
+  // registry[0] stays the static default (HOME_TENANT) for unknown-host fallback.
+  return new StaticTenantResolver([...staticTenants, ...dev]);
+}
+
+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> {
+  // Synthesized dev tenants live in the shared fallback, so both branches resolve
+  // the dev loop's checked-out tenant on a KV miss (prod fallback is unchanged).
+  const fallback = devFallbackResolver();
+  const kv = await readKv("TENANT_CACHE");
+  if (kv) return new KvTenantResolver(kv, fallback);
+  return new KvTenantResolver(await devKv(), fallback);
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Static tenant registry — SANITIZED for the world-shareable storefront runner.
+ *
+ * This file is REWRITTEN at build time (scripts/build/build-runner.mjs) so the
+ * public npm runner ships NO real merchant roster. It carries only a neutral
+ * "home" default and one GENERIC sample tenant (with a compliance block, so the
+ * age-gate / PACT affordance is demonstrable off a non-merchant identity).
+ *
+ * At runtime the dev loop's checkout-glob resolver (config/resolver.ts) synthesizes
+ * a servable tenant for whatever the developer grafts into tenants/<id>/, so the
+ * real staticTenants are not needed here. The public API (staticTenants,
+ * StaticTenantResolver, tenantResolver) is unchanged — only the data is generic.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+import { getTenantTheme } from "@/themes/tenants";
+
+// Default landing tenant — the fallback for unmatched hosts / bare localhost.
+// Non-commerce "coming soon" placeholder; never a fake merchant. Registered first
+// so it is the resolver default (registry[0]).
+export const HOME_TENANT: TenantConfig = {
+  tenant_id: "home",
+  appDomain: "home",
+  // NB: do NOT claim "localhost" here — a bare localhost host must fall THROUGH to
+  // path-prefix routing (/<domain>/…) so grafted dev tenants + the sample resolve.
+  // Unknown/bare hosts still land on HOME via resolveByHost (registry[0]).
+  domains: ["home"],
+  canonicalDomain: "home",
+  displayName: "Storefront",
+  storyblok_space_token: "STORYBLOK_HOME_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "home",
+  currency: "USD",
+  locale: "en-US",
+  theme_tokens: getTenantTheme("home"),
+  siteType: "marketing",
+};
+
+// Generic SAMPLE tenant — a placeholder regulated store used to demonstrate the
+// compliance affordance (age-gate + nicotine warning) WITHOUT any real merchant.
+// Routed at /sample-store.example/. Content comes from the developer's grafted
+// checkout (tenants/sample-store.example/); with none present it degrades to the
+// default scope, and the compliance overlay still renders from this config.
+export const SAMPLE_TENANT: TenantConfig = {
+  tenant_id: "sample-store.example",
+  appDomain: "sample-store.example",
+  domains: ["sample-store.example"],
+  canonicalDomain: "sample-store.example",
+  displayName: "Sample Store",
+  storyblok_space_token: "STORYBLOK_SAMPLE_DELIVERY_TOKEN_PLACEHOLDER",
+  tot_data_scope: "sample-store.example",
+  currency: "USD",
+  locale: "en-US",
+  theme_tokens: getTenantTheme("sample-store.example"),
+  // Regulated-store demo: shows the 21+/PACT compliance gate is CONFIG-driven.
+  compliance: {
+    minAge: 21,
+    nicotineWarning: true,
+    shippingRestriction:
+      "Adult signature (21+) required on delivery. Some destinations are restricted — verified at checkout.",
+  },
+  siteType: "marketing",
+};
+
+const REGISTRY: TenantConfig[] = [HOME_TENANT, SAMPLE_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.
+    return match ?? this.registry[0] ?? null;
+  }
+}
+
+export const tenantResolver: TenantResolver = new StaticTenantResolver();

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

@@ -0,0 +1,368 @@
+---
+/**
+ * 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 AnnouncementBar from "@/components/chrome/AnnouncementBar.astro";
+import SiteHeader from "@/components/chrome/SiteHeader.astro";
+import SiteFooter from "@/components/chrome/SiteFooter.astro";
+import QuickView from "@/components/islands/QuickView.tsx";
+import FoxyLoader from "@/components/commerce/FoxyLoader.astro";
+import FoxySidecartStyles from "@/components/commerce/FoxySidecartStyles.astro";
+import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
+import ShippingRestrictionNotice from "@/components/compliance/ShippingRestrictionNotice.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";
+import { readViewerSession } from "@/lib/auth/route";
+
+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/") || h.startsWith("/shared/"));
+  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;
+
+// Site-chrome data resolution (unit I4 — chrome/* is the canonical, prop-driven
+// component set; this Layout is the ONE place that resolves session/feature/
+// theme state into their props. Skipped entirely when sharedChrome (a raw
+// content/<id>/chrome.html override) is present — that path wins outright.
+//
+// Auth entry point: "Dashboard" when a session exists, "Sign in" otherwise.
+// Without this there's no discoverable path from the storefront into sign-in /
+// the vendor dashboard (#8425). On login-gated hosts the middleware already
+// resolved the viewer (locals.viewer); reuse it and only read the session KV on
+// open hosts where the gate never ran. Signed-out "Sign in" carries the current
+// path as `next`, so after the email-code round-trip the visitor lands back
+// where they were instead of the site root.
+const viewer = Astro.locals.viewer ?? (await readViewerSession(Astro));
+const nextParam = encodeURIComponent(Astro.url.pathname + Astro.url.search);
+const authLink = {
+  label: viewer ? "Dashboard" : "Sign in",
+  href: viewer ? "/dashboard" : `/auth/login?next=${nextParam}`,
+};
+
+// Per-vendor header treatment from the theme file: a "dark" header renders the
+// bar in the primary color carrying the light logo (e.g. Giant Vapes' navy +
+// white logo); a light header always shows the text wordmark (no logo image).
+const headerDark = theme.brand.headerVariant === "dark";
+const headerLogoSrc = headerDark ? theme.brand.logoLight : theme.brand.logoDark;
+const headerLogo =
+  headerDark && headerLogoSrc && /^(https?:|\/)/.test(headerLogoSrc)
+    ? { src: headerLogoSrc, alt: tenant.displayName }
+    : undefined;
+
+// Footer bottom bar: a "Legal"-titled column's links win; otherwise every
+// column's links flatten into the policy-link row (mirrors the retired
+// nav/Footer.astro exactly).
+const legalCol = chrome.footer.columns.find((c) => /legal/i.test(c.title));
+const bottomLinks = legalCol ? legalCol.links : chrome.footer.columns.flatMap((c) => c.links);
+const legalLine = `© ${new Date().getFullYear()} ${tenant.displayName}${
+  chrome.footer.legal ? ` · ${chrome.footer.legal}` : ""
+}`;
+
+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) — the tenant theme (/tenants/...) plus
+        either the tenant's own mkt.css or the platform /shared/commerce-chrome.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" />}
+        <div class="sticky top-0 z-40">
+          {chrome.announcement && <AnnouncementBar text={chrome.announcement} variant="static" />}
+          <SiteHeader
+            logo={headerLogo}
+            wordmark={tenant.displayName}
+            nav={chrome.nav}
+            variant={headerDark ? "dark" : "light"}
+            announcement={chrome.announcement}
+            searchAction={features.productSearch ? "/search" : undefined}
+            savedItemsHref={features.savedItems ? "/saved" : undefined}
+            headerCtas={chrome.headerCtas}
+            authLink={authLink}
+            sticky={false}
+          />
+        </div>
+      </>
+    )}
+
+    <main id="main">
+      <slot />
+    </main>
+
+    {sharedChrome ? (
+      <Fragment set:html={sharedChrome.footer} />
+    ) : (
+      <>
+        <ShippingRestrictionNotice text={compliance?.shippingRestriction} />
+        <SiteFooter
+          brand={{
+            wordmark: tenant.displayName,
+            contact: chrome.footer.tagline ? [chrome.footer.tagline] : undefined,
+          }}
+          columns={chrome.footer.columns}
+          newsletter={features.newsletter ? { title: "Newsletter", placeholder: "you@example.com" } : undefined}
+          social={chrome.footer.social}
+          legal={legalLine}
+          bottomLinks={bottomLinks}
+        />
+      </>
+    )}
+
+    {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 />
+
+    {/* Brand Foxy's in-page sidecart to the tenant theme (baseline + optional
+        per-tenant commerce.foxy.sidecartCss override). Commerce tenants only. */}
+    <FoxySidecartStyles />
+
+    {/* 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/admin/README.md

@@ -0,0 +1,122 @@
+# `lib/admin` — admin data/view + AI/evidence contracts
+
+Read-oriented view models and deterministic mock services for the 7 admin
+domains (orders, products, customers, fulfillment, reporting, settings,
+ai-workflows), plus the AI/evidence substrate (`ai/`, `evidence/`) those
+domains' assist surfaces build on. See
+`docs/handoffs/admin-app-implementation-baseline.md` for the product spec
+these implement.
+
+## Tenant envelope
+
+The canonical tenant envelope is `AdminTenantEnvelope`, defined in
+`lib/adminTenantEnvelope.ts` (admin-tenant-mode) and re-exported from
+`lib/admin/envelope.ts` so everything under `lib/admin/**` can import it from
+a stable relative path:
+
+```ts
+interface AdminTenantEnvelope {
+  adminAppTenant: string;      // the tenant that actually served this request
+  targetTenant: string;        // the merchant tenant this page's data/actions are scoped to
+  operator: string | null;     // the signed-in viewer's email, or null when anonymous
+}
+```
+
+For merchant-facing admin `adminAppTenant` and `targetTenant` are equal; only
+a real ToT-staff session may move `targetTenant` away from the routed tenant
+(see `resolveAdminTenantMode` for the authorization rule — deny-by-default,
+refused not hidden-only). `targetTenant` is the sole key mock services use to
+select/derive data. **Authorization must always be evaluated against
+`targetTenant`, never `adminAppTenant`** (decision `tenant-envelope-contract`).
+
+(`lib/admin/envelope.ts` used to declare its own 2-field copy of this
+interface — data-view-contracts and admin-tenant-mode were built in parallel
+per that decision, with no live coordination. Reconciled here per decision
+`envelope-type-duplication-follow-up`: one canonical type, re-exported.)
+
+## Layout
+
+```
+lib/admin/
+  envelope.ts              # re-exports the canonical AdminTenantEnvelope
+  seed.ts                  # deterministic PRNG + timestamp helpers
+  viewmodels/<domain>.ts   # types only, no I/O
+  services/mock/<domain>.ts  # getXViewModel(envelope) -> X ViewModel
+  services/mock/evidence.ts # getEvidenceViewModel(envelope) -> EvidenceReference[]
+  services/mock/tenants.ts   # seeded tenant registry + fallback profile
+  services/mock/index.ts     # barrel re-export
+  ai/
+    approvalMode.ts        # canonical ApprovalMode + isDraftOnly/requiresHumanApproval/isAutomationAllowed
+    audit.ts                # canonical AuditEvent (operator + targetTenant + action + at)
+    recommendation.ts       # AiRecommendation — the recommendation-shaped record every AI suggestion should use
+    askEnvelope.ts           # AskEnvelope + buildAskEnvelope() — the floating Ask button's context
+  evidence/
+    evidenceReference.ts     # EvidenceReference + EvidenceKind — the evidence graph's typed pointer
+```
+
+## AI / evidence substrate
+
+- **Approval state machine** (`ai/approvalMode.ts`): `draft_only` |
+  `approval_required` | `guarded_automation`. `settings.ts` and
+  `aiWorkflows.ts` both import this rather than declaring their own copy.
+- **Audit events** (`ai/audit.ts`): `{ operator, targetTenant, action, at }`.
+  `SettingsAuditEvent` extends it with a human-readable `change` string;
+  `WorkflowRecord.auditTrail` uses it directly.
+- **Recommendations** (`ai/recommendation.ts`): `AiRecommendation` is the
+  shape every AI-suggested action should carry — `summary`, `confidence`
+  (0–1), `evidenceRefs` (ids into the evidence graph), `owner`,
+  `approvalMode`, `auditTrail`. `WorkflowRecord.suggestedAction` uses this
+  today; later per-tab assist surfaces (Order Assist, Fulfillment Assist,
+  etc.) should reuse it instead of inventing a parallel "suggestion" shape.
+- **Evidence graph** (`evidence/evidenceReference.ts` +
+  `services/mock/evidence.ts`): a typed, tenant-scoped pointer
+  (`EvidenceReference`) connecting orders, customers, products, payments,
+  verification events, fulfillment/tracking, support/contact events, policy
+  acceptance, tax/excise evidence, and admin/user actions
+  (`EvidenceKind`). The mock service builds real edges by cross-referencing
+  the orders/customers/products mock services already in this directory
+  (an order's evidence ref links to its customer and product refs via
+  `relatedRefs`) rather than inventing disconnected fixture data.
+- **Ask envelope** (`ai/askEnvelope.ts`): `buildAskEnvelope()` is the pure,
+  testable source of truth for what the floating Ask button emits — the full
+  tenant envelope, active tab, selected record id (if any), role +
+  permissions (derived from `isStaff`), active filters, and evidence context.
+  `admin.astro`'s `is:inline` script mirrors this logic in plain JS (inline
+  scripts can't import modules) and emits it on Ask-button click as
+  `window.__toTAdminAsk` and a `tot:admin-ask` `CustomEvent` — **dev-inspectable
+  only, no chat backend yet.** The envelope changes whenever the active tab
+  changes (kept current by `setAskContext`) and is rebuilt fresh on click so a
+  selection made via `data-admin-selected-id` (a hook future tab units can set
+  on their selected row/detail panel — none do yet) is picked up.
+
+## Determinism
+
+Every mock service seeds its randomness from `seededRandom(`<domain>:${targetTenant}`)`
+(`seed.ts`), so **the same `targetTenant` always returns the same data** within
+a process — no reliance on `Date.now()` or other wall-clock state. Two tenants
+are curated with vertical-flavored data (`northridge-vapor.com` — vape,
+`cascade-tobacco.com` — tobacco); any other `targetTenant` string still gets a
+stable fallback profile via `tenantProfile()`, so callers never need to
+special-case an "unknown" tenant.
+
+## Usage
+
+```ts
+import { getOrdersViewModel } from "@/lib/admin/services/mock";
+
+const orders = getOrdersViewModel({
+  adminAppTenant: tenant.tenant_id,
+  targetTenant: tenant.tenant_id,
+  operator: viewerEmail,
+});
+```
+
+## Boundaries
+
+- **Read-only.** No write/mutation paths exist yet — that is a later unit.
+- **Tabs/pages → lib, never lib → tabs/pages.** Nothing under `lib/admin/**`
+  imports from `components/admin/**` or `pages/admin.astro`. Tab components
+  and `admin.astro` are free to import from here (`admin.astro` already does,
+  for `resolveAdminTenantMode` and the Ask-envelope logic it mirrors inline).
+- Gaps in these contracts should go back to the workstream board as a
+  decision, not get patched from a tab's unit.