@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/components/chrome/SiteHeader.astro

@@ -3,7 +3,7 @@
  * <SiteHeader> — logo/wordmark + search island + account/auth + cart-count
  * affordance, with the primary <MegaMenu> nav below and a mobile drawer (the
  * <MobileNav> island). Tenant-agnostic; theme-token skinned. This is the
- * CANONICAL site header (unit I4) — the former `components/nav/Header.astro`
+ * CANONICAL site header — the former `components/nav/Header.astro`
  * app-Layout implementation is retired; every feature it had (search typeahead,
  * mobile drawer with focus-trap/scroll-lock, the session-aware auth entry point,
  * the saved-items/wishlist cue, marketing header CTAs, a dark header variant)
@@ -13,8 +13,9 @@
  * COMMERCE BOUNDARY: the cart is a LINK only — no cart state, no add-to-cart.
  * The count is a static affordance the managed cart can hydrate later.
  */
-import type { ChromeNavItem, ChromeLogo, ChromeCta } from "@/lib/chrome/model";
+import type { ChromeNavItem, ChromeLogo, ChromeCta, HeaderVariant } from "@/lib/chrome/model";
 import MegaMenu from "@/components/chrome/MegaMenu.astro";
+import NavDropdown from "@/components/chrome/NavDropdown.astro";
 import SearchTypeahead from "@/components/islands/SearchTypeahead.tsx";
 import MobileNav from "@/components/islands/MobileNav.tsx";
 import { withBase } from "@/lib/basePath";
@@ -23,6 +24,11 @@ interface Props {
   logo?: ChromeLogo;
   /** Fallback wordmark text when no logo image. */
   wordmark?: string;
+  /**
+   * Home/brand link target (lib/chrome/model.ts ChromeBrand.href). Run through
+   * `withBase` same as every other same-origin href. Omit to default to "/".
+   */
+  brandHref?: string;
   nav?: ChromeNavItem[];
   /** Search form action (GET). Omit to hide search. Mounts the live SearchTypeahead island. */
   searchAction?: string;
@@ -41,6 +47,15 @@ interface Props {
   cartCount?: number;
   /** A brand-fixed "dark" header bar (e.g. a navy bar with a light logo) vs. the default light bar. */
   variant?: "light" | "dark";
+  /**
+   * Content-shape variant (lib/chrome/model.ts HeaderVariant) — independent of
+   * `variant`'s light/dark TONE above. "minimal" (e.g. checkout/policy pages)
+   * renders brand + a reduced action set only: no search, no marketing CTAs,
+   * no saved-items affordance, no primary-nav bar, no mobile-menu toggle.
+   * Defaults to "primary" (the full header) so every existing caller is
+   * unaffected.
+   */
+  layout?: HeaderVariant;
   sticky?: boolean;
   class?: string;
 }
@@ -48,6 +63,7 @@ interface Props {
 const {
   logo,
   wordmark,
+  brandHref,
   nav = [],
   searchAction,
   announcement,
@@ -58,14 +74,16 @@ const {
   cartHref,
   cartCount = 0,
   variant = "light",
+  layout = "primary",
   sticky = true,
   class: className,
 } = Astro.props;
 
 const { basePath } = Astro.locals;
-const homeHref = withBase(basePath, "/");
+const homeHref = withBase(basePath, brandHref ?? "/");
 const showLogo = !!logo && /^(https?:|\/)/.test(logo.src);
 const dark = variant === "dark";
+const minimal = layout === "minimal";
 
 const ctaClass = (v?: string) =>
   v === "secondary" || v === "ghost"
@@ -86,6 +104,11 @@ const mobileNav = nav.map((item) => ({
     href: withBase(basePath, child.href),
   })),
 }));
+
+// Current-page path, for aria-current="page" — threaded to the MobileNav
+// island (which can't read Astro.url itself) so it marks the same link the
+// server-rendered nav (NavDropdown, via Astro.url internally) marks.
+const currentPath = Astro.url.pathname;
 ---
 
 <header class:list={[sticky && "sticky top-0 z-40", className]}>
@@ -133,7 +156,7 @@ const mobileNav = nav.map((item) => ({
 
       <!-- Search (live typeahead island) -->
       {
-        searchAction && (
+        !minimal && searchAction && (
           <div class="hidden flex-1 md:flex">
             <SearchTypeahead client:idle action={searchAction} />
           </div>
@@ -143,7 +166,7 @@ const mobileNav = nav.map((item) => ({
       <!-- Actions: saved items + marketing CTAs + auth + account + cart (link only) + mobile menu -->
       <div class="ml-auto flex items-center gap-1">
         {
-          savedItemsHref && (
+          !minimal && savedItemsHref && (
             <a
               href={withBase(basePath, savedItemsHref)}
               aria-label="Saved items"
@@ -161,7 +184,7 @@ const mobileNav = nav.map((item) => ({
           )
         }
         {
-          headerCtas.length > 0 && (
+          !minimal && headerCtas.length > 0 && (
             <div class="hidden items-center gap-2 sm:flex">
               {headerCtas.map((cta) => (
                 <a href={withBase(basePath, cta.href)} class={ctaClass(cta.variant)}>
@@ -220,9 +243,9 @@ const mobileNav = nav.map((item) => ({
 
         <!-- Mobile menu: the MobileNav island (focus-trap, scroll-lock, Escape-to-close) -->
         {
-          nav.length > 0 && (
+          !minimal && nav.length > 0 && (
             <div class="md:hidden">
-              <MobileNav client:idle nav={mobileNav} announcement={announcement} />
+              <MobileNav client:idle nav={mobileNav} announcement={announcement} currentPath={currentPath} />
             </div>
           )
         }
@@ -230,12 +253,25 @@ const mobileNav = nav.map((item) => ({
     </div>
   </div>
 
-  <!-- Primary nav bar -->
+  <!-- Primary nav bar: desktop MegaMenu (hidden md:block) + a no-JS-safe mobile
+       fallback (md:hidden) below it. The fallback renders the SAME nav data as
+       real, crawlable <a href> links via a native <details>/<summary> accordion
+       (NavDropdown mode="accordion") — it works with zero JavaScript, since it
+       is below the `md` breakpoint the ONLY nav affordance a no-JS visitor has
+       (the MobileNav drawer above is a client:idle island and renders nothing
+       without JS). Once MobileNav hydrates it hides this fallback (see its
+       [data-mobile-nav-fallback] effect) so JS-enabled visitors get the drawer
+       as the primary/enhanced experience; this is additive, not a replacement. -->
   {
-    nav.length > 0 && (
+    !minimal && nav.length > 0 && (
       <div class="border-b border-border bg-surface">
         <div class="container-prose">
           <MegaMenu items={nav} />
+          <nav aria-label="Mobile" data-mobile-nav-fallback class="md:hidden">
+            <ul class="grid">
+              {nav.map((item) => <NavDropdown item={item} mode="accordion" />)}
+            </ul>
+          </nav>
         </div>
       </div>
     )

package/apps/storefront/src/components/compliance/AdultSignatureNotice.astro

@@ -4,7 +4,7 @@
  * require an of-age adult to sign; the wording is fixed here and the age
  * reflects tenant.compliance.minAge (defaults to 21). Renders NOTHING when
  * `enabled` is false. Driven by tenant.compliance.adultSignature — never hand-
- * authored on a marketing page (decision compliance-widgets-platform-owned).
+ * authored on a marketing page.
  */
 import ComplianceNotice from "./ComplianceNotice.astro";
 

package/apps/storefront/src/components/compliance/ComplianceNotice.astro

@@ -5,8 +5,7 @@
  * FDA NicotineWarning follows). It owns ONLY the chrome: the fixed legal text
  * is supplied by each sibling widget via <slot />, and every sibling renders it
  * ONLY when its tenant.compliance data is present. This component adds no copy
- * of its own — it never fabricates legal wording (decision
- * compliance-widgets-platform-owned).
+ * of its own — it never fabricates legal wording.
  *
  * Variants — one visual treatment per placement, token-styled so they re-skin
  * with the theme and never carry a hardcoded brand color:

package/apps/storefront/src/components/compliance/ExciseTaxNotice.astro

@@ -3,8 +3,7 @@
  * Excise-tax DISPLAY cue. Presentational only — it surfaces that applicable
  * excise taxes apply (and, optionally, a per-jurisdiction breakdown for shopper
  * transparency); it NEVER computes tax. The actual excise-tax CALCULATION is
- * product/commerce-owned (decision compliance-widgets-platform-owned). Renders
- * NOTHING when no note is supplied.
+ * product/commerce-owned. Renders NOTHING when no note is supplied.
  *
  * The optional jurisdiction breakdown is rendered as inline "label detail"
  * spans (valid inside the primitive's paragraph) so it re-skins with the theme

package/apps/storefront/src/components/compliance/PactActNotice.astro

@@ -6,7 +6,7 @@
  * Postal Service carriage; only whether it renders (and the age) comes from
  * tenant.compliance.pactAct / .minAge. Renders NOTHING when `enabled` is false,
  * so absent data never shows placeholder legal text. Never hand-author this on a
- * marketing page (decision compliance-widgets-platform-owned).
+ * marketing page.
  */
 import ComplianceNotice from "./ComplianceNotice.astro";
 

package/apps/storefront/src/components/compliance/Prop65Warning.astro

@@ -5,8 +5,7 @@
  * ("WARNING: … known to the State of California to cause …"), the ⚠ symbol, and
  * the official warnings URL. Only the variable slots — harm endpoint(s) and the
  * chemical name(s) named in the long form — come from tenant.compliance.prop65.
- * Renders NOTHING when the config is absent, so it never fabricates a warning
- * (decision compliance-widgets-platform-owned).
+ * Renders NOTHING when the config is absent, so it never fabricates a warning.
  *
  * `true` → short cancer + reproductive-harm warning. A Prop65Config selects the
  * harm endpoint(s); providing `chemicals` switches to the long form.

package/apps/storefront/src/components/compliance/PurchaseLimitNotice.astro

@@ -3,9 +3,8 @@
  * Purchase-quantity-limit DISPLAY. Surfaces a shopper-facing limit (e.g. state
  * or PACT-Act order caps). Display surface ONLY — the limit text comes from
  * tenant.compliance.purchaseLimit and the actual enforcement stays in the
- * product/commerce layer, never hand-built here (decision
- * compliance-widgets-platform-owned). Renders NOTHING when the config (or its
- * text) is absent.
+ * product/commerce layer, never hand-built here. Renders NOTHING when the
+ * config (or its text) is absent.
  */
 import type { PurchaseLimitConfig } from "@tot/public-runtime";
 import ComplianceNotice from "./ComplianceNotice.astro";

package/apps/storefront/src/components/compliance/ShippingRestrictionNotice.astro

@@ -3,8 +3,8 @@
  * Shipping-restriction DISPLAY notice (e.g. PACT Act no-ship states, adult
  * signature, carrier limits). Presentational only — it renders the tenant's
  * configured `compliance.shippingRestriction` text; the actual ship/no-ship
- * DECISION for an address stays in the product/commerce layer (decision
- * compliance-widgets-platform-owned). Renders NOTHING when `text` is absent.
+ * DECISION for an address stays in the product/commerce layer. Renders
+ * NOTHING when `text` is absent.
  *
  * This is the platform component behind the footer shipping band the app Layout
  * previously inlined — same data, same footer placement, now token-styled via

package/apps/storefront/src/components/compliance/StateEligibilityNotice.astro

@@ -3,9 +3,8 @@
  * State/jurisdiction sale-eligibility DISPLAY notice. Presentational only — it
  * SHOWS the tenant-configured eligibility messaging (which states a product is /
  * isn't available in); it does NOT decide whether a given cart/address is
- * eligible — that computation stays product-owned (decision
- * compliance-widgets-platform-owned). Renders NOTHING when no eligibility data
- * is supplied, so absent config never shows a placeholder.
+ * eligible — that computation stays product-owned. Renders NOTHING when no
+ * eligibility data is supplied, so absent config never shows a placeholder.
  *
  * Message precedence: an explicit `note` wins; otherwise a sentence is composed
  * from `restrictedStates` ("Not available for sale in: …") or, failing that,

package/apps/storefront/src/components/content/TrustStrip.astro

@@ -1,11 +1,11 @@
 ---
 /**
  * <TrustStrip> — the quiet row of proof tokens a store repeats across pages
- * ("Ships from USA", "Lab-tested", a rating). REAL-OR-ABSENT by construction
- * (f09): sanitizeTrustStrip() drops any claim that is scraped review-widget
- * markup and any rating that isn't a real positive aggregate, reusing f09's
+ * ("Ships from USA", "Lab-tested", a rating). REAL-OR-ABSENT by construction:
+ * sanitizeTrustStrip() drops any claim that is scraped review-widget
+ * markup and any rating that isn't a real positive aggregate, reusing the same
  * detector. If nothing real is left the strip renders NOTHING — never a
- * fabricated badge. Plain text + one rating glyph; styled from f06 tokens.
+ * fabricated badge. Plain text + one rating glyph; styled from design tokens.
  * data-widget="trust-strip".
  */
 import type { TrustStripItem } from "@/lib/content/trustStrip";

package/apps/storefront/src/components/islands/MobileNav.tsx

@@ -11,6 +11,7 @@
  * prefers-reduced-motion.
  */
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import { isCurrentNavHref } from "@/lib/chrome/navCurrent";
 
 interface NavChild {
   label: string;
@@ -25,9 +26,13 @@ interface NavItem {
 interface Props {
   nav: NavItem[];
   announcement?: string;
+  /** Current request path (Astro.url.pathname), for aria-current="page" — see navCurrent.ts. */
+  currentPath?: string;
 }
 
 const DRAWER_ID = "mobile-drawer";
+/** Matches SiteHeader.astro's no-JS fallback <nav data-mobile-nav-fallback>. */
+const FALLBACK_NAV_SELECTOR = "[data-mobile-nav-fallback]";
 
 function prefersReducedMotion(): boolean {
   return (
@@ -37,7 +42,7 @@ function prefersReducedMotion(): boolean {
   );
 }
 
-export default function MobileNav({ nav, announcement }: Props) {
+export default function MobileNav({ nav, announcement, currentPath }: Props) {
   const [open, setOpen] = useState(false);
   const buttonRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
@@ -45,6 +50,17 @@ export default function MobileNav({ nav, announcement }: Props) {
 
   const close = useCallback(() => setOpen(false), []);
 
+  // The no-JS fallback nav is only needed when JS never runs. Since this
+  // component mounting IS JS running, hide it in favor of the drawer above —
+  // additive progressive enhancement, not a replacement of either layer.
+  useEffect(() => {
+    document
+      .querySelectorAll<HTMLElement>(FALLBACK_NAV_SELECTOR)
+      .forEach((el) => {
+        el.hidden = true;
+      });
+  }, []);
+
   // Body scroll lock while open.
   useEffect(() => {
     if (!open) return;
@@ -202,6 +218,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                       <div class="px-3 py-2">
                         <a
                           href={item.href}
+                          aria-current={
+                            currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
+                          }
                           class="block font-display text-base font-medium text-text hover:text-primary"
                         >
                           {item.label}
@@ -211,6 +230,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                             <li key={child.href}>
                               <a
                                 href={child.href}
+                                aria-current={
+                                  currentPath && isCurrentNavHref(currentPath, child.href) ? "page" : undefined
+                                }
                                 class="block rounded px-2 py-1.5 font-body text-sm text-muted hover:bg-border/40 hover:text-text"
                               >
                                 {child.label}
@@ -222,6 +244,9 @@ export default function MobileNav({ nav, announcement }: Props) {
                     ) : (
                       <a
                         href={item.href}
+                        aria-current={
+                          currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
+                        }
                         class="block rounded px-3 py-2.5 font-display text-base font-medium text-text hover:bg-border/40 hover:text-primary"
                       >
                         {item.label}

package/apps/storefront/src/components/islands/VariantSelector.tsx

@@ -27,6 +27,7 @@ import type {
 } from "@tot/public-runtime";
 import { priceForPurchaseOption } from "@tot/public-runtime";
 import { formatPrice } from "@/lib/format";
+import { useCheckoutHandoffCorrelation } from "@/components/islands/useCheckoutHandoffCorrelation";
 
 interface OptionDef {
   name: string;
@@ -55,7 +56,7 @@ interface Props {
     byVariantId: Record<string, Record<string, VariantCartPayload>>;
   };
   /**
-   * Membership pricing (F10). Present only when an eligible member is resolved
+   * Membership pricing. Present only when an eligible member is resolved
    * for this request (Phase 2 shopper login). Undefined → list pricing only,
    * which is the Phase-1 anonymous behavior.
    */
@@ -63,6 +64,13 @@ interface Props {
     membershipRule: MembershipTierRule;
     stacking: MembershipStackingPolicy;
   };
+  /**
+   * Base-path-aware URL of the checkout-correlation mint endpoint
+   * (ext-commerce-10). When a store is wired the island posts the shopper's live
+   * consent snapshot here and, if the server attributes, carries the returned
+   * passthrough field on the managed-cart form. Undefined → no correlation.
+   */
+  handoffUrl?: string;
 }
 
 const LOW_STOCK_THRESHOLD = 5;
@@ -89,7 +97,14 @@ export default function VariantSelector({
   productTitle,
   checkoutCart,
   pricing,
+  handoffUrl,
 }: Props) {
+  // Checkout-correlation handoff mint (ext-commerce-10): resolved once the server
+  // attributes this shopper (analytics consent granted + signing secret present),
+  // else null → the buy form carries no correlation and the order is unattributed.
+  const correlationField = useCheckoutHandoffCorrelation(
+    checkoutCart ? handoffUrl : undefined,
+  );
   const sortedOptions = useMemo(
     () => [...options].sort((a, b) => a.position - b.position),
     [options],
@@ -219,7 +234,7 @@ export default function VariantSelector({
     }
   }
 
-  // Compose member + subscription pricing (F10). The pricing context carries the
+  // Compose member + subscription pricing. The pricing context carries the
   // resolved member tier only when an eligible member was resolved server-side;
   // otherwise it is a non-member and list pricing stands.
   const pricingCtx = pricing
@@ -474,6 +489,16 @@ export default function VariantSelector({
                 value={String(quantity)}
               />
             )}
+            {/* Checkout-correlation passthrough field (ext-commerce-10). Rides the
+                handoff as a never-signed hidden field the provider echoes back on
+                the order webhook; absent when unattributed. */}
+            {canBuy && correlationField && (
+              <input
+                type="hidden"
+                name={correlationField.name}
+                value={correlationField.value}
+              />
+            )}
             <button
               type="submit"
               disabled={!canBuy}

package/apps/storefront/src/components/islands/useCheckoutHandoffCorrelation.ts

@@ -0,0 +1,75 @@
+/**
+ * Client hook for the checkout-correlation handoff mint (ext-commerce-10).
+ *
+ * The shopper's analytics consent is a live CLIENT-side value, but the correlation
+ * token is minted under the SERVER-only signing secret. So at the handoff this hook
+ * posts the current consent snapshot (the renderer-owned `__TOT_INTEGRATION_CONSENT__`
+ * global) to `POST /api/commerce/checkout-handoff` and, when the server attributes,
+ * returns the opaque passthrough cart field for the managed-cart form to carry.
+ *
+ * Fail-safe by construction: no handoff URL, a network error, or an unattributed
+ * response yields `null` — the buy form renders and submits with NO correlation field,
+ * so the order is simply unattributed and checkout is never blocked.
+ */
+import { useEffect, useState } from "preact/hooks";
+
+/** The renderer-owned frozen consent-snapshot global (`render-phases.ts`). */
+const INTEGRATION_CONSENT_GLOBAL = "__TOT_INTEGRATION_CONSENT__";
+
+/** The opaque passthrough cart field to attach to the managed-cart form. */
+export interface HandoffCartField {
+  name: string;
+  value: string;
+}
+
+/**
+ * Read the `{ attributed, cartField }` handoff response fail-closed into a cart field,
+ * or `null` for any non-attributed / malformed shape. Pure — unit-tested directly.
+ */
+export function parseHandoffCartField(data: unknown): HandoffCartField | null {
+  if (!data || typeof data !== "object") return null;
+  const d = data as Record<string, unknown>;
+  if (d.attributed !== true) return null;
+  const field = d.cartField;
+  if (!field || typeof field !== "object") return null;
+  const { name, value } = field as Record<string, unknown>;
+  return typeof name === "string" && name.length > 0 && typeof value === "string" && value.length > 0
+    ? { name, value }
+    : null;
+}
+
+/** The live consent snapshot the renderer inlined + the CMP/native banner updates. */
+function readClientConsent(): unknown {
+  return (globalThis as Record<string, unknown>)[INTEGRATION_CONSENT_GLOBAL] ?? null;
+}
+
+/**
+ * Fetch the handoff correlation for this page. Returns the cart field to attach once
+ * the server attributes, else `null`. `handoffUrl` absent (no store / marketing
+ * tenant) is a no-op.
+ */
+export function useCheckoutHandoffCorrelation(handoffUrl?: string): HandoffCartField | null {
+  const [field, setField] = useState<HandoffCartField | null>(null);
+
+  useEffect(() => {
+    if (!handoffUrl) return;
+    let cancelled = false;
+    fetch(handoffUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ consent: readClientConsent() }),
+    })
+      .then((res) => res.json())
+      .then((data) => {
+        if (!cancelled) setField(parseHandoffCartField(data));
+      })
+      .catch(() => {
+        // Fail-safe: leave the order unattributed; never disturb the buy form.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [handoffUrl]);
+
+  return field;
+}

package/apps/storefront/src/components/membership/IllustrativeLabel.astro

@@ -4,8 +4,7 @@
  * offer" affordance shared by <TierCards>, <TierComparisonTable>, and the
  * subscription <SavingsExplainer>. When a group shows illustrative figures,
  * the widgets render this so an example price / savings number is never
- * mistaken for a live offer (decision compliance-widgets-platform-owned —
- * education only, no pricing mechanics).
+ * mistaken for a live offer — education only, no pricing mechanics.
  *
  * Two forms:
  *   - "badge" a compact pill placed at the group header (the visible marker)

package/apps/storefront/src/components/membership/TierCards.astro

@@ -6,8 +6,8 @@
  * checkout, or subscription mechanics — each tier's CTA is a plain handoff link
  * into the tenant's own (product-owned) subscribe/learn flow.
  *
- * Illustrative-figures affordance (decision compliance-widgets-platform-owned):
- * a tier's figure is treated as an EXAMPLE by default (isIllustrative). When any
+ * Illustrative-figures affordance: a tier's figure is treated as an EXAMPLE
+ * by default (isIllustrative). When any
  * shown tier is illustrative the group header carries a first-class
  * <IllustrativeLabel> badge, each such figure is prefixed with an "e.g."
  * affordance + data-illustrative hook, and a footnote spells it out — so an

package/apps/storefront/src/components/membership/TierComparisonTable.astro

@@ -6,8 +6,8 @@
  * subscription mechanics; a tier's optional figure and CTA are display/handoff
  * only.
  *
- * Illustrative-figures affordance (decision compliance-widgets-platform-owned):
- * when any tier shows an illustrative figure the header carries a first-class
+ * Illustrative-figures affordance: when any tier shows an illustrative
+ * figure the header carries a first-class
  * <IllustrativeLabel> badge, each such figure gets an "e.g." affordance +
  * data-illustrative hook, and a footnote spells it out — an example number is
  * never presented as a live offer.

package/apps/storefront/src/components/subscription/SavingsExplainer.astro

@@ -6,8 +6,8 @@
  * subscription mechanics — the CTA is a link into the tenant's own
  * (product-owned) subscribe/learn flow.
  *
- * Illustrative-figure affordance (decision compliance-widgets-platform-owned):
- * the figure is treated as an EXAMPLE by default (isIllustrative). When
+ * Illustrative-figure affordance: the figure is treated as an EXAMPLE by
+ * default (isIllustrative). When
  * illustrative, the figure carries an "e.g." affordance + a first-class
  * <IllustrativeLabel> badge/footnote so an example number is never presented
  * as a live offer. A tenant opts out only by asserting `real: true` on a

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

@@ -0,0 +1,35 @@
+/**
+ * Admin integration plane — arbitrary-tenant lookup provider (ext-kernel-09).
+ *
+ * The `/api/apps/admin/*` integration routes resolve a tenant named in the operator
+ * session (`auth.tenantId` — a vendor may administer a tenant that is NOT the
+ * request's own host scope, so `Astro.locals.tenant` does not apply). Materializing
+ * a tenant's OWN (tenant-local) declarations needs its full config (`compliance`,
+ * `siteType`, `integrations`), which requires the concrete resolver selection — and
+ * the `tenancy-resolver-fence` extractability invariant forbids pages/lib from
+ * importing that directly.
+ *
+ * This module lives in `src/config` (an approved location) and encapsulates
+ * `getTenantResolver()` + `staticTenants`, exposing exactly the by-id lookup the
+ * admin routes need, typed against the public `TenantConfig`. Mirrors
+ * `previewTenantLookup.ts`; the concrete resolver selection stays in `config`, so a
+ * constant single-tenant resolver remains a drop-in and the codebase stays
+ * always-extractable.
+ */
+import type { TenantConfig } from "@tot/public-runtime";
+import { getTenantResolver } from "@/config/resolver";
+import { staticTenants } from "@/config/tenants";
+
+/**
+ * Resolve the admin operator's tenant id (== appDomain for the built-in tenants) to
+ * its config. Strict domain match first (KV-backed in prod, static in dev), then the
+ * static registry by appDomain or tenant_id. Null for an unknown tenant.
+ */
+export async function resolveAdminTenant(tenantId: string): Promise<TenantConfig | null> {
+  const resolver = await getTenantResolver();
+  return (
+    (await resolver.resolveStrict(tenantId)) ??
+    staticTenants.find((t) => t.appDomain === tenantId || t.tenant_id === tenantId) ??
+    null
+  );
+}

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

@@ -27,14 +27,14 @@ import type { DeepPartial, TenantConfig, ThemeTokens } from "@tot/public-runtime
 /** Per-dir overrides the resolver derives from disk before synthesis. */
 export interface DevTenantHints {
   /**
-   * (E3) The resolvable appDomain for a SLUG tenant whose dir name isn't its
+   * The resolvable appDomain for a SLUG tenant whose dir name isn't its
    * domain. Read from the checkout's `.tot/config.json` `scope` when that scope
    * looks like a hostname (has a dot) — mirrors scripts/tot-dev.mjs resolveDomain.
    * Undefined ⇒ the colocation convention (dir == appDomain == scope).
    */
   appDomain?: string;
   /**
-   * (E2) True when catalog fixtures for this tenant's data scope are committed on
+   * True when catalog fixtures for this tenant's data scope are committed on
    * disk (the same `packages/migration/out/catalog/<scope>/` the FixtureToTClient
    * reads). When true we serve a real COMMERCE tenant so /collections + /products
    * render from them; when false we degrade to a marketing home (no catalog).
@@ -45,9 +45,9 @@ export interface DevTenantHints {
 /**
  * A servable TenantConfig for a local dev-loop checkout. Identity defaults to the
  * colocated dir name (dir == id == appDomain == tot_data_scope); a slug tenant can
- * override the resolvable appDomain via `hints.appDomain` (E3). No Storyblok space
+ * override the resolvable appDomain via `hints.appDomain`. No Storyblok space
  * (a "PLACEHOLDER" token → LocalContentProvider serves the checkout's content/).
- * Commerce is data-driven (E2): with catalog fixtures on disk the tenant is
+ * Commerce is data-driven: with catalog fixtures on disk the tenant is
  * COMMERCE (catalog on); without them it degrades to a marketing home (siteType
  * "marketing" → no catalog required, so the root renders instead of 404ing).
  * Theme tokens come from the checkout's theme.json.
@@ -57,7 +57,7 @@ export function synthesizeDevTenant(
   themeTokens: DeepPartial<ThemeTokens>,
   hints: DevTenantHints = {},
 ): TenantConfig {
-  // (E3) Prefer the .tot/config.json scope for a slug tenant; else colocation.
+  // Prefer the .tot/config.json scope for a slug tenant; else colocation.
   const appDomain = hints.appDomain ?? id;
   const base: TenantConfig = {
     tenant_id: id,
@@ -74,7 +74,7 @@ export function synthesizeDevTenant(
     theme_tokens: themeTokens,
   };
   if (hints.hasCatalog) {
-    // (E2) Catalog fixtures on disk → a real commerce tenant (siteType omitted ==
+    // Catalog fixtures on disk → a real commerce tenant (siteType omitted ==
     // commerce → catalog on). Cart wires to the shared ToT demo checkout store
     // (test mode, no secret), the same as the bundled demo tenants — so
     // /collections + /products resolve and add-to-cart works on localhost.
@@ -90,9 +90,9 @@ export function synthesizeDevTenant(
 
 /** Per-dir disk facts the resolver supplies so synthesis can go beyond colocation. */
 export interface DevTenantSeedOptions {
-  /** (E3) Resolved appDomain for a slug tenant (from `.tot/config.json` scope). */
+  /** Resolved appDomain for a slug tenant (from `.tot/config.json` scope). */
   scopeFor?: (id: string) => string | undefined;
-  /** (E2) Whether catalog fixtures are committed on disk for a given data scope. */
+  /** Whether catalog fixtures are committed on disk for a given data scope. */
   hasCatalog?: (scope: string) => boolean;
 }
 
@@ -100,7 +100,7 @@ export interface DevTenantSeedOptions {
  * The dev tenants to seed ALONGSIDE staticTenants: one synthesized config per
  * local tenant dir that isn't already a static tenant (those keep their richer
  * hardcoded config). `themeFor` supplies each dir's theme tokens; `opts` carries
- * the per-dir disk facts (E2 catalog presence, E3 slug scope) the resolver reads.
+ * the per-dir disk facts (catalog presence, slug scope) the resolver reads.
  *
  * @param localDirIds dir names discovered under `tenants/*` (dir == tenant id)
  * @param staticIds   tenant_ids already in the static registry (skipped)