@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -0,0 +1,57 @@
+/**
+ * GET /tenants/<id>/<path> — serve a tenant's versioned static asset from R2.
+ *
+ * The version-scoped replacement for the build-time `copy-tenant-assets.mjs`
+ * baking (decision `assets-r2-versioned`). Resolves the tenant's active
+ * channel→snapshot versionId from the `cust:assets-pointer:<id>` KV record and
+ * streams `tenants/<id>/<versionId>/<rel>` from the TENANT_ASSETS R2 bucket with
+ * the right content-type + a revalidating cache header + a versionId ETag.
+ *
+ * BACK-COMPAT: this SSR route only runs when NO baked static file matched — the
+ * Cloudflare/Vite static layer serves `public/tenants/<id>/…` first. So a
+ * NON-versioned tenant (still baked by copy-tenant-assets) never reaches here,
+ * and a versioned tenant (skipped from baking via a `.tot/assets-versioned`
+ * marker) falls through to R2. When the tenant has no published asset version,
+ * `serveTenantAsset` returns null → 404 (nothing published yet).
+ */
+import type { APIContext } from "astro";
+import {
+  serveTenantAsset,
+  type R2BucketLike,
+} from "@tot/public-runtime";
+import { readR2, readKv } from "@/lib/env";
+
+export const prerender = false;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const [bucket, kv] = await Promise.all([
+    readR2("TENANT_ASSETS"),
+    readKv("TENANT_CACHE"),
+  ]);
+  // No R2/KV binding (plain `astro dev`, or unconfigured) → nothing to serve.
+  if (!bucket || !kv) {
+    return new Response("Not found", {
+      status: 404,
+      headers: { "cache-control": "no-store" },
+    });
+  }
+
+  const res = await serveTenantAsset(
+    {
+      // Runtime binding structurally satisfies the shared-runtime R2 seam.
+      bucket: bucket as unknown as R2BucketLike,
+      kvGet: (key) => kv.get(key),
+      channel: context.locals.customizationEnv ?? "live",
+      ifNoneMatch: context.request.headers.get("if-none-match"),
+    },
+    new URL(context.request.url).pathname,
+  );
+
+  return (
+    res ??
+    new Response("Not found", {
+      status: 404,
+      headers: { "cache-control": "no-store" },
+    })
+  );
+}

package/apps/storefront/src/styles/global.css

@@ -0,0 +1,292 @@
+@import "tailwindcss";
+
+/*
+ * Theme bridge (brief §6/§7).
+ *
+ * The per-tenant identity arrives as CSS custom properties in a :root{} block
+ * injected by the middleware (src/themes/schema.ts -> Layout.astro). Here we map
+ * those vars into Tailwind v4 theme tokens so utilities like `bg-bg`,
+ * `text-primary`, `font-display`, `rounded-md` resolve to the LIVE tenant value.
+ * Components stay theme-agnostic: they use utilities, the utilities read vars,
+ * the vars come from the tenant. Swap a tenant -> the whole UI reskins, no
+ * component edits.
+ *
+ * Fallback values below keep the design coherent before/without the injected
+ * block (e.g. error pages, prerendered routes).
+ */
+@theme {
+  --color-bg: var(--color-bg, #f4f1ea);
+  --color-surface: var(--color-surface, #fcfaf5);
+  --color-text: var(--color-text, #1c2624);
+  --color-muted: var(--color-muted, #5c6663);
+  --color-primary: var(--color-primary, #1f3a34);
+  --color-primary-contrast: var(--color-primary-contrast, #f4f1ea);
+  --color-accent: var(--color-accent, #b5612f);
+  /* Darkened accent for SMALL text/links on light bg/surface (the bright
+     `accent` is reserved for large display type on the spruce hero, where it
+     reads as the brass spark). Derived from the tenant's own accent so it stays
+     theme-agnostic. Reference value resolves to ~#985127 (≥5:1 on bg/surface).
+     A tenant MAY hand-tune it for exact AA by emitting --color-accent-ink; else
+     it derives from the tenant's own accent so it stays theme-agnostic. */
+  --color-accent-ink: var(--color-accent-ink, color-mix(in srgb, var(--color-accent) 84%, #000));
+  --color-border: var(--color-border, #dcd6c9);
+  --color-success: var(--color-success, #3f6b4f);
+  --color-sale: var(--color-sale, #9e3b2e);
+
+  /* Semantic/state extensions (token-contract.md). Platform defaults kept
+     resolvable here so components can always read them; a tenant theme overrides
+     any by emitting the matching --color-* via themeToCssVars. */
+  --color-surface-2: var(--color-surface-2, #ece7db);
+  --color-warning: var(--color-warning, #8a5717);
+  --color-error: var(--color-error, #a22014);
+  --color-info: var(--color-info, #2c5b73);
+
+  /* Hover policy: components read --color-{primary,accent}-hover; the default is
+     a derived darken of the base, overridable per tenant for hand-tuned values. */
+  --color-primary-hover: var(--color-primary-hover, color-mix(in srgb, var(--color-primary) 88%, #000));
+  --color-accent-hover: var(--color-accent-hover, color-mix(in srgb, var(--color-accent) 88%, #000));
+
+  --font-display: var(--font-display, "Space Grotesk"), system-ui, sans-serif;
+  --font-body: var(--font-body, "Source Serif 4"), Georgia, serif;
+  --font-mono: var(--font-mono, "Space Mono"), ui-monospace, monospace;
+
+  --radius-sm: var(--radius-sm, 3px);
+  --radius-md: var(--radius-md, 6px);
+  --radius-lg: var(--radius-lg, 12px);
+  --radius-full: var(--radius-full, 999px);
+
+  --shadow-sm: var(--shadow-sm, 0 1px 2px rgba(28, 38, 36, 0.06));
+  --shadow-md: var(--shadow-md, 0 6px 24px -8px rgba(28, 38, 36, 0.14));
+  --shadow-lg: var(--shadow-lg, 0 24px 60px -20px rgba(28, 38, 36, 0.22));
+
+  --container-max: var(--container-max, 1240px);
+}
+
+/* ---- base ---------------------------------------------------------------- */
+@layer base {
+  :root {
+    /* Fluid modular type scale; overridden by injected --fs-* when present. */
+    color-scheme: light;
+  }
+
+  html {
+    font-family: var(--font-body);
+    color: var(--color-text);
+    background: var(--color-bg);
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+    scroll-behavior: smooth;
+  }
+
+  body {
+    font-size: var(--fs-base, 1.0625rem);
+    line-height: 1.6;
+    letter-spacing: var(--type-tracking, -0.011em);
+  }
+
+  h1, h2, h3, h4, h5 {
+    font-family: var(--font-display);
+    font-weight: 600;
+    line-height: 1.05;
+    letter-spacing: -0.02em;
+    color: var(--color-text);
+    text-wrap: balance;
+  }
+
+  /* Body copy rhythm: a comfortable measure + paragraph spacing for prose-y
+     blocks that aren't inside .rte (e.g. editorial subheads). */
+  p { text-wrap: pretty; }
+
+  a {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  /* Visible keyboard focus everywhere (WCAG 2.2 AA, brief §8). */
+  :focus-visible {
+    outline: var(--border-thick, 2px) solid var(--color-accent);
+    outline-offset: 2px;
+    border-radius: 2px;
+  }
+
+  ::selection {
+    background: var(--color-primary);
+    color: var(--color-primary-contrast);
+  }
+
+  img { max-width: 100%; height: auto; }
+
+  /* Honor reduced motion (brief §6/§8). */
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.001ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.001ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}
+
+/* ---- shared component primitives ----------------------------------------- */
+@layer components {
+  .container-prose {
+    width: 100%;
+    max-width: var(--container-max);
+    margin-inline: auto;
+    padding-inline: clamp(1rem, 4vw, 2.5rem);
+  }
+
+  .eyebrow {
+    font-family: var(--font-mono);
+    font-size: 0.72rem;
+    letter-spacing: 0.16em;
+    text-transform: uppercase;
+    color: var(--color-muted);
+  }
+
+  /* Eyebrow with the signature leading tick — a single short amber rule, the
+     "one brass rivet" motif from DESIGN.md, applied as a quiet structural mark.
+     Opt-in via .eyebrow.eyebrow--tick so it never fires where it'd read as noise. */
+  .eyebrow--tick {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.6em;
+  }
+  .eyebrow--tick::before {
+    content: "";
+    width: 1.6em;
+    height: 2px;
+    background: var(--color-accent);
+    flex: none;
+  }
+
+  /* Fluid display scale, derived from the tenant's emitted modular --fs-* steps
+     (the major-third scale in DESIGN.md). One rhythm across every page instead
+     of ad-hoc per-component clamps. min = small step, max = large step. */
+  .display-hero {
+    font-family: var(--font-display);
+    font-weight: 600;
+    line-height: 0.95;
+    letter-spacing: -0.03em;
+    font-size: clamp(var(--fs-3xl, 3.05rem), 8vw, var(--fs-5xl, 4.77rem));
+  }
+  .display-xl {
+    font-family: var(--font-display);
+    font-weight: 600;
+    line-height: 1.02;
+    letter-spacing: -0.025em;
+    font-size: clamp(var(--fs-2xl, 2.44rem), 5vw, var(--fs-4xl, 3.81rem));
+  }
+  .display-lg {
+    font-family: var(--font-display);
+    font-weight: 600;
+    line-height: 1.05;
+    letter-spacing: -0.02em;
+    font-size: clamp(var(--fs-xl, 1.95rem), 3.5vw, var(--fs-3xl, 3.05rem));
+  }
+  .display-md {
+    font-family: var(--font-display);
+    font-weight: 600;
+    line-height: 1.1;
+    letter-spacing: -0.018em;
+    font-size: clamp(var(--fs-lg, 1.56rem), 3vw, var(--fs-2xl, 2.44rem));
+  }
+
+  /* Tasteful scroll-reveal; opt-in via [data-reveal], JS toggles .is-in. */
+  [data-reveal] {
+    opacity: 0;
+    transform: translateY(14px);
+    transition: opacity 0.6s ease, transform 0.6s cubic-bezier(0.22, 1, 0.36, 1);
+  }
+  [data-reveal].is-in {
+    opacity: 1;
+    transform: none;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    [data-reveal] { opacity: 1; transform: none; }
+  }
+
+  /* Island animations (MobileNav drawer slide-in). Globally neutralized by the
+     reduced-motion guard above; islands also guard in JS. */
+  @keyframes tot-slidein {
+    from { transform: translateX(100%); }
+    to   { transform: translateX(0); }
+  }
+
+  /* Rich text from CMS/description. */
+  .rte > * + * { margin-top: 1em; }
+  .rte h2 { font-size: var(--fs-xl, 1.6rem); margin-top: 1.6em; }
+  .rte h3 { font-size: var(--fs-lg, 1.3rem); margin-top: 1.3em; }
+  .rte ul, .rte ol { padding-left: 1.4em; }
+  .rte ul { list-style: disc; }
+  .rte ol { list-style: decimal; }
+  .rte li + li { margin-top: 0.35em; }
+  .rte strong { font-weight: 600; }
+  .rte a { color: var(--color-accent-ink); text-decoration: underline; text-underline-offset: 3px; }
+
+  /* Accent text-link with an animated underline — restrained micro-interaction
+     for inline CTAs. Uses accent-ink (AA on light surfaces). */
+  .link-accent {
+    color: var(--color-text);
+    background-image: linear-gradient(var(--color-accent-ink), var(--color-accent-ink));
+    background-position: 0 100%;
+    background-repeat: no-repeat;
+    background-size: 100% 1.5px;
+    transition: color 0.2s ease, background-size 0.25s cubic-bezier(0.22, 1, 0.36, 1);
+  }
+  .link-accent:hover,
+  .link-accent:focus-visible {
+    color: var(--color-accent-ink);
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    .link-accent { background-size: 0% 1.5px; }
+    .link-accent:hover,
+    .link-accent:focus-visible { background-size: 100% 1.5px; }
+  }
+
+  /* Collapsible PDP info sections (native <details>). Zero-JS, accessible. */
+  .accordion {
+    border-bottom: 1px solid var(--color-border);
+  }
+  .accordion__summary {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    padding: 1rem 0;
+    cursor: pointer;
+    list-style: none;
+    font-family: var(--font-display);
+    font-weight: 500;
+    font-size: 0.95rem;
+    color: var(--color-text);
+    transition: color 0.15s ease;
+  }
+  .accordion__summary::-webkit-details-marker { display: none; }
+  .accordion__summary:hover { color: var(--color-primary); }
+  .accordion__chevron {
+    font-family: var(--font-mono);
+    font-size: 1.1rem;
+    line-height: 1;
+    color: var(--color-muted);
+    transition: transform 0.2s ease;
+  }
+  .accordion[open] .accordion__chevron { transform: rotate(45deg); }
+  .accordion__body { padding-bottom: 1.1rem; }
+
+  /* Wishlist saved state (robust, no JS text swap): fill the heart and relabel
+     when aria-pressed. Applies to card hearts and the PDP "Save for later". */
+  .wishlist-toggle[aria-pressed="true"] .wishlist-heart { fill: currentColor; }
+  .wishlist-toggle[aria-pressed="true"] .wl-label { font-size: 0; }
+  .wishlist-toggle[aria-pressed="true"] .wl-label::after {
+    content: "Saved";
+    font-size: 0.875rem;
+  }
+
+  /* Quick-view dialog entrance (reduced-motion neutralized by the base guard). */
+  .quickview[open] { animation: tot-pop 0.18s cubic-bezier(0.22, 1, 0.36, 1); }
+  @keyframes tot-pop {
+    from { opacity: 0; transform: translateY(8px) scale(0.98); }
+    to   { opacity: 1; transform: none; }
+  }
+}

package/apps/storefront/src/themes/reference.ts

@@ -0,0 +1,68 @@
+/**
+ * Reference theme — "Northwind" pilot identity. See DESIGN.md for full rationale.
+ *
+ * Thesis: a Pacific-Northwest maker of considered apparel + home goods.
+ * The voice is overcast-day calm with one sharp accent — like a single brass
+ * rivet on a waxed-canvas bag.
+ *
+ * Deliberate anti-AI-default moves (brief §6):
+ *  - Palette is INK + SPRUCE on a warm GREIGE surface — NOT cream/terracotta,
+ *    NOT near-black/acid-green. Sale red is a muted brick, not a siren.
+ *  - Type pairing INVERTS the tired "serif headline" cliché: a tight geometric
+ *    grotesque (Space Grotesk) carries display; a warm humanist serif
+ *    (Source Serif 4) carries body copy. Personality up top, readability below.
+ *  - Boldness is spent in ONE place: the homepage hero's oversized split-type
+ *    lockup. Everything else stays quiet.
+ */
+import type { ThemeTokens } from "@tot/public-runtime";
+
+export const referenceTheme: ThemeTokens = {
+  color: {
+    bg: "#F4F1EA", // warm greige paper — NOT cream, lower chroma + cooler
+    surface: "#FCFAF5", // raised card surface, a touch lighter than bg
+    text: "#1C2624", // spruce-ink, near-black with a green undertone
+    muted: "#5C6663", // slate-sage for secondary text
+    primary: "#1F3A34", // deep spruce green — the brand anchor
+    "primary-contrast": "#F4F1EA",
+    accent: "#B5612F", // burnt amber / brass — the single warm spark
+    border: "#DCD6C9", // soft sand hairline (NOT broadsheet black)
+    success: "#3F6B4F",
+    sale: "#9E3B2E", // muted brick red, not fire-engine
+    // Semantic/state extensions (contract optional; stated here as the canonical
+    // reference values). accent-ink + *-hover are intentionally omitted so the
+    // reference identity exercises the derived @theme defaults.
+    "surface-2": "#ECE7DB", // inset greige well, a step deeper than bg
+    warning: "#8A5717", // deep amber — AA on the light greige surfaces
+    error: "#A22014", // deep true-red, kept distinct from the brick `sale`
+    info: "#2C5B73", // calm slate-blue, distinct from the spruce `primary`
+  },
+  type: {
+    display: { family: "Space Grotesk", weights: [500, 600, 700] },
+    body: { family: "Source Serif 4", weights: [400, 500, 600] },
+    mono: { family: "Space Mono", weights: [400] },
+    scale: 1.25, // major third — generous but not theatrical
+    tracking: "-0.011em",
+  },
+  space: {
+    base: 4,
+    scale: [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64],
+    containerMaxWidth: "1240px",
+    sectionRhythm: "clamp(4rem, 9vw, 8rem)",
+  },
+  shape: {
+    radius: { sm: "3px", md: "6px", lg: "12px", full: "999px" },
+    borderWeights: { thin: "1px", medium: "1.5px", thick: "2px" },
+    shadow: {
+      sm: "0 1px 2px rgba(28, 38, 36, 0.06)",
+      md: "0 6px 24px -8px rgba(28, 38, 36, 0.14)",
+      lg: "0 24px 60px -20px rgba(28, 38, 36, 0.22)",
+    },
+  },
+  brand: {
+    logoLight: "/brand/northwind-logo-light.svg",
+    logoDark: "/brand/northwind-logo-dark.svg",
+    favicon: "/favicon.svg",
+    ogImage: "/brand/northwind-og.svg",
+    motion: "full",
+  },
+};

package/apps/storefront/src/themes/schema.ts

@@ -0,0 +1,111 @@
+/**
+ * Theme token -> CSS custom property serialization.
+ *
+ * Components are theme-AGNOSTIC: they only ever read var(--color-primary),
+ * var(--font-display), etc. This module turns a resolved ThemeTokens object
+ * into the `<style>` block the middleware injects per request, so one component
+ * library renders every tenant's identity. See DESIGN.md.
+ */
+import type { DeepPartial, ThemeTokens } from "@tot/public-runtime";
+
+/** Deep-merge tenant overrides over the reference defaults. */
+export function mergeTheme(
+  base: ThemeTokens,
+  override?: DeepPartial<ThemeTokens>,
+): ThemeTokens {
+  if (!override) return base;
+  return deepMerge(base, override) as ThemeTokens;
+}
+
+function deepMerge<T>(base: T, over: DeepPartial<T>): T {
+  if (Array.isArray(base)) return (over as unknown as T) ?? base;
+  if (typeof base === "object" && base !== null) {
+    const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+    for (const [k, v] of Object.entries(over as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      const bv = (base as Record<string, unknown>)[k];
+      out[k] =
+        bv && typeof bv === "object" && !Array.isArray(bv) && typeof v === "object"
+          ? deepMerge(bv, v as DeepPartial<unknown>)
+          : v;
+    }
+    return out as T;
+  }
+  return (over as unknown as T) ?? base;
+}
+
+/**
+ * Serialize ThemeTokens into a `:root { --x: y }` declaration block.
+ * Returns the INNER CSS (no <style> wrapper) so the caller controls nonce/attrs.
+ */
+export function themeToCssVars(t: ThemeTokens): string {
+  const lines: string[] = [];
+  const push = (name: string, value: string | number) =>
+    lines.push(`  --${name}: ${value};`);
+
+  // Color
+  for (const [k, v] of Object.entries(t.color)) push(`color-${k}`, v);
+
+  // Type
+  push("font-display", `"${t.type.display.family}"`);
+  push("font-body", `"${t.type.body.family}"`);
+  if (t.type.mono) push("font-mono", `"${t.type.mono.family}"`);
+  push("type-scale", t.type.scale);
+  if (t.type.tracking) push("type-tracking", t.type.tracking);
+  // Emit a modular type scale (rem) from the ratio.
+  const ratio = t.type.scale;
+  const steps: Record<string, number> = {
+    "xs": -2, "sm": -1, "base": 0, "md": 1, "lg": 2,
+    "xl": 3, "2xl": 4, "3xl": 5, "4xl": 6, "5xl": 7,
+  };
+  for (const [name, step] of Object.entries(steps)) {
+    push(`fs-${name}`, `${(1 * Math.pow(ratio, step)).toFixed(4)}rem`);
+  }
+
+  // Space
+  push("space-base", `${t.space.base}px`);
+  t.space.scale.forEach((mult, i) =>
+    push(`space-${i}`, `${(t.space.base * mult).toFixed(2)}px`),
+  );
+  push("container-max", t.space.containerMaxWidth);
+  push("section-rhythm", t.space.sectionRhythm);
+
+  // Shape
+  push("radius-sm", t.shape.radius.sm);
+  push("radius-md", t.shape.radius.md);
+  push("radius-lg", t.shape.radius.lg);
+  push("radius-full", t.shape.radius.full);
+  push("border-thin", t.shape.borderWeights.thin);
+  push("border-medium", t.shape.borderWeights.medium);
+  push("border-thick", t.shape.borderWeights.thick);
+  push("shadow-sm", t.shape.shadow.sm);
+  push("shadow-md", t.shape.shadow.md);
+  push("shadow-lg", t.shape.shadow.lg);
+
+  return `:root{\n${lines.join("\n")}\n}`;
+}
+
+/** Google Fonts <link> for a theme's display+body+mono families (if Google-hosted). */
+export function themeFontHref(t: ThemeTokens): string | null {
+  const families = new Map<string, number[]>();
+  families.set(t.type.display.family, t.type.display.weights);
+  families.set(t.type.body.family, t.type.body.weights);
+  if (t.type.mono) families.set(t.type.mono.family, t.type.mono.weights);
+
+  const params = [...families]
+    .filter(([fam]) => !SYSTEM_FONTS.has(fam))
+    .map(([fam, weights]) => {
+      const w = [...new Set(weights)].sort((a, b) => a - b).join(";");
+      return `family=${encodeURIComponent(fam).replace(/%20/g, "+")}:wght@${w}`;
+    });
+  if (!params.length) return null;
+  return `https://fonts.googleapis.com/css2?${params.join("&")}&display=swap`;
+}
+
+const SYSTEM_FONTS = new Set([
+  "system-ui",
+  "-apple-system",
+  "Arial",
+  "Helvetica",
+  "Georgia",
+]);

package/apps/storefront/src/themes/tenants/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-vendor theme registry.
+ *
+ * A tenant's theme override lives at the colocated repo-root path
+ * `tenants/<tenant_id>/theme.json` (a DeepPartial<ThemeTokens> — only the tokens
+ * you want to override; the reference theme fills the rest) and it's
+ * auto-discovered at build time. This is the seam the brand adopter targets: its
+ * `out/branding/<tenant>.theme.json` output is written to `tenants/<id>/theme.json`.
+ *
+ * Files may include documentation keys (`_vendor`, `_note`, `$schema`); those are
+ * stripped so only real tokens reach the theme merge.
+ *
+ * Depth: from src/themes/tenants/ the repo root is five levels up
+ * (tenants→themes→src→storefront→apps→root).
+ */
+import type { DeepPartial, ThemeTokens } from "@tot/public-runtime";
+
+const modules = import.meta.glob<Record<string, unknown>>(
+  "../../../../../tenants/*/theme.json",
+  {
+    eager: true,
+    import: "default",
+  },
+);
+
+function stripMeta(obj: Record<string, unknown>): DeepPartial<ThemeTokens> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith("_") || k.startsWith("$")) continue;
+    out[k] = v;
+  }
+  return out as DeepPartial<ThemeTokens>;
+}
+
+const THEMES: Record<string, DeepPartial<ThemeTokens>> = {};
+for (const [path, mod] of Object.entries(modules)) {
+  // Path looks like ".../tenants/<id>/theme.json" — the id is the dir segment.
+  const id = /\/tenants\/([^/]+)\/theme\.json$/.exec(path)?.[1];
+  if (!id) continue;
+  THEMES[id] = stripMeta(mod as Record<string, unknown>);
+}
+
+/** Theme-token overrides for a tenant, or {} if the vendor has no theme file. */
+export function getTenantTheme(tenantId: string): DeepPartial<ThemeTokens> {
+  return THEMES[tenantId] ?? {};
+}
+
+/** Tenant ids that ship a theme file (for diagnostics / listing). */
+export function tenantsWithThemes(): string[] {
+  return Object.keys(THEMES);
+}

package/apps/storefront/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": false,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": [".astro/types.d.ts", "src/**/*", "*.config.mjs", "env.d.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/apps/storefront/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "vitest/config";
+import { fileURLToPath } from "node:url";
+
+// Storefront unit tests — pure TS logic (tenant routing, search, query engine,
+// image-attr resolution, edge cache, etc.). We deliberately do NOT render .astro
+// components here: the Astro Container API needs Astro's Vite pipeline, whose
+// vite-plugin-head crashes under vitest@2 + astro@7 (configureServer reads an
+// undefined `ssr`). Render *logic* is extracted into testable modules instead
+// (e.g. lib/imageAttrs.ts), and rendered output is verified on a live preview.
+export default defineConfig({
+  // Mirror the `@` -> src alias from tsconfig so tests can import aliased modules
+  // (e.g. src/config/tenants.ts, which pulls the theme registry).
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tokenoftrust/storefront-runner",
+  "version": "1.3.2",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
+  "packageManager": "pnpm@11.9.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "pnpm --filter @tot/storefront-runner dev",
+    "build": "pnpm --filter @tot/storefront-runner build",
+    "typecheck": "pnpm -r typecheck",
+    "depcruise": "pnpm --filter @tot/storefront-runner depcruise"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "storefront-runner": "scripts/tot-dev.mjs"
+  }
+}