@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/pages/llms.txt.ts

@@ -0,0 +1,92 @@
+/**
+ * Per-tenant llms.txt — the emerging /llms.txt convention: a concise,
+ * machine-readable guide that helps LLM answer engines (ChatGPT, Perplexity,
+ * Google AI Overviews, etc.) understand what this store is and where its key
+ * content lives. Mirrors robots.txt / sitemap.xml: built per request from the
+ * resolved tenant's catalog + content, canonical base from the Host.
+ *
+ * Every line traces to REAL migrated data or tenant config — no fabricated copy
+ * (playbook/codebase-health.md T7). Summary/descriptions are the merchant's own
+ * SEO text; compliance facts come from tenant.compliance.
+ */
+import type { APIContext } from "astro";
+import { createContentProvider } from "@/lib/storyblok/provider";
+
+/** Collapse HTML/whitespace to a single trimmed line for a link description. */
+function oneLine(s: string | undefined, max = 140): string | undefined {
+  if (!s) return undefined;
+  const t = s.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+  if (!t) return undefined;
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const { tot, tenant, canonicalBase } = context.locals;
+  const base = canonicalBase.replace(/\/$/, "");
+  const provider = createContentProvider(tenant);
+
+  const [collections, pages, featured, home] = await Promise.all([
+    tot.listCollections(),
+    provider.listPages(),
+    tot.getFeatured(12),
+    provider.getHome().catch(() => null),
+  ]);
+
+  const lines: string[] = [`# ${tenant.displayName}`, ""];
+
+  const summary = oneLine(home?.seoDescription, 280);
+  if (summary) lines.push(`> ${summary}`, "");
+
+  // Compliance facts — sourced from tenant config, never invented.
+  const c = tenant.compliance;
+  if (c && (c.minAge || c.nicotineWarning || c.shippingRestriction)) {
+    const facts: string[] = [];
+    if (c.minAge) facts.push(`age-restricted — customers must be ${c.minAge}+`);
+    if (c.nicotineWarning) facts.push("products contain nicotine (FDA warning applies)");
+    if (facts.length) lines.push(`**Compliance:** ${facts.join("; ")}.`);
+    const ship = oneLine(c.shippingRestriction, 240);
+    if (ship) lines.push(`**Shipping:** ${ship}`);
+    lines.push("");
+  }
+
+  if (collections.length) {
+    lines.push("## Collections");
+    for (const col of collections) {
+      const desc = oneLine(col.description_text ?? col.seo.description);
+      lines.push(`- [${col.title}](${base}/collections/${col.handle})${desc ? `: ${desc}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  if (featured.length) {
+    lines.push("## Featured products");
+    for (const p of featured) {
+      const desc = oneLine(p.seo.description ?? p.description_text);
+      lines.push(`- [${p.title}](${base}/products/${p.handle})${desc ? `: ${desc}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  if (pages.length) {
+    lines.push("## Pages");
+    for (const pg of pages) {
+      lines.push(`- [${pg.title}](${base}/${pg.slug})`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Optional");
+  lines.push(`- [Full product catalog (XML sitemap)](${base}/sitemap.xml)`);
+  lines.push(`- [Search](${base}/search)`);
+  lines.push(
+    "- Every page ships Schema.org JSON-LD (Product, Offer, AggregateRating, Breadcrumb, Organization) for structured extraction.",
+  );
+  lines.push("");
+
+  return new Response(lines.join("\n"), {
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "public, max-age=300, s-maxage=3600",
+    },
+  });
+}

package/apps/storefront/src/pages/products/[handle].astro

@@ -0,0 +1,402 @@
+---
+/**
+ * PDP — the conversion centerpiece (brief §5). Gallery + variant selector
+ * islands, breadcrumbs, structured specs from metafields, related products,
+ * badges, review-stars placeholder, disabled buy CTA (no cart in Phase 1),
+ * Product + BreadcrumbList JSON-LD.
+ */
+import Layout from "@/layouts/Layout.astro";
+import Breadcrumbs from "@/components/Breadcrumbs.astro";
+import Badge from "@/components/Badge.astro";
+import ProductCard from "@/components/ProductCard.astro";
+import Section from "@/components/Section.astro";
+import ImageGallery from "@/components/islands/ImageGallery.tsx";
+import VariantSelector from "@/components/islands/VariantSelector.tsx";
+import RecentlyViewed from "@/components/islands/RecentlyViewed.tsx";
+import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
+import ReviewSummary from "@/components/commerce/ReviewSummary.astro";
+import ReviewList from "@/components/commerce/ReviewList.astro";
+import { isOnSale, isNew, isAvailable, fromPrice } from "@/lib/tot/query";
+import { buildVariantCartPayload } from "@tot/public-runtime";
+import type { VariantCartPayload } from "@tot/public-runtime";
+import { readCartSecret } from "@/lib/foxyCommerce";
+import { truncate } from "@/lib/format";
+import { productLd, breadcrumbLd, reviewLd } from "@/lib/jsonld";
+import { isUsableImageUrl } from "@/lib/placeholder";
+import { withBase } from "@/lib/basePath";
+
+const { handle } = Astro.params;
+const { tenant, tot, canonicalBase, basePath, commerce } = Astro.locals;
+// Commerce-only route: marketing tenants have no product detail pages.
+if (!Astro.locals.features.catalog) return new Response(null, { status: 404 });
+const compliance = tenant.compliance;
+
+if (!handle) return Astro.redirect(withBase(basePath, "/404"));
+const product = await tot.getProductByHandle(handle);
+
+// Draft canary: drafts resolve by handle (preview/direct link) but are noindex.
+if (!product || product.status === "archived") {
+  return new Response(null, { status: 404 });
+}
+const isDraft = product.status !== "active";
+
+// Related: same collection first, then shared-tag fallback, exclude self+drafts.
+const related = await (async () => {
+  const out = new Map<string, typeof product>();
+  for (const colHandle of product.collections) {
+    const { products } = await tot.listProducts({ collection: colHandle, pageSize: 12 });
+    for (const p of products) if (p.handle !== product.handle) out.set(p.handle, p);
+  }
+  if (out.size < 4 && product.tags.length) {
+    const { products } = await tot.listProducts({ pageSize: 50 });
+    for (const p of products) {
+      if (p.handle === product.handle) continue;
+      if (p.tags.some((t) => product.tags.includes(t))) out.set(p.handle, p);
+    }
+  }
+  return [...out.values()].slice(0, 4);
+})();
+
+const crumbs = [
+  { label: tenant.displayName, href: "/" },
+  ...(product.collections[0]
+    ? [{ label: titleCase(product.collections[0]), href: `/collections/${product.collections[0]}` }]
+    : []),
+  { label: product.title, href: `/products/${product.handle}` },
+];
+
+function titleCase(s: string) {
+  return s.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// Metafield reader.
+const mf = (ns: string, key: string) =>
+  product.metafields.find((m) => m.namespace === ns && m.key === key)?.value;
+
+// Reviews — REAL data from the store's reviews app (Stamped), pulled as metafields.
+const reviewCount = Number(mf("stamped", "reviews_count") ?? mf("reviews", "count") ?? "0");
+const reviewAvg = Number(mf("stamped", "reviews_average") ?? mf("reviews", "rating") ?? "0");
+
+// Short description (merchant's concise summary) shown high on the PDP, like the
+// source store. The longer description_html still renders below the buy column.
+const shortDescription = mf("my_fields", "short_description") ?? mf("specs", "short_description");
+
+// OG image = the real product image (Shopify CDN supports ?width=), sized for
+// social. Falls back to the tenant brand OG only when there's no usable image.
+const ogPrimary = product.images[0];
+const ogImage =
+  ogPrimary && isUsableImageUrl(ogPrimary.url, ogPrimary.rehosted)
+    ? `${ogPrimary.url}${ogPrimary.url.includes("?") ? "&" : "?"}width=1200`
+    : undefined;
+
+// Product attributes shown the way the SOURCE STORE presents them: plain
+// "Label: value" lines below the description (Flavors / VG % / Bottle Type),
+// sourced from F:-prefixed tags + merchant my_fields. The compliance.* metafields
+// are ToT-internal sync data and are NOT displayed — the source store doesn't
+// show them either (they gate shipping/eligibility, not merchandising).
+// Each flavor links to that flavor filtered within the product's collection —
+// mirrors the source store's /collections/<handle>/<tag> pattern using our
+// existing ?tag= PLP filter. General: any tag → a filtered listing; only the
+// "F: " flavor-tag convention is merchant-specific (same as the display above).
+const flavorCollection = product.collections[0];
+const flavorTags = (product.tags ?? [])
+  .filter((t) => t.startsWith("F: "))
+  .map((t) => ({
+    label: t.slice(3).trim(),
+    href: flavorCollection
+      ? `/collections/${flavorCollection}?tag=${encodeURIComponent(t)}`
+      : undefined,
+  }))
+  .filter((f) => f.label);
+const vgPercentage = mf("my_fields", "vg_percentage");
+const bottleType = mf("my_fields", "bottle_type");
+
+// State sales restrictions (ToT compliance sync). Where this can't ship/sell.
+let restrictedStates: string[] = [];
+const restrictedRaw = mf("compliance", "restricted_states");
+if (restrictedRaw) {
+  try {
+    const parsed = JSON.parse(restrictedRaw);
+    restrictedStates = Array.isArray(parsed) ? parsed : Object.keys(parsed);
+  } catch {
+    /* not JSON — ignore */
+  }
+}
+
+// Legal/safety disclaimer (scraped from the store's own PDP by the migration),
+// per product category — sub-ohm on salts, battery on devices, etc. Selected by
+// product_type (or the compliance.product_category metafield); default fallback.
+const chrome = await Astro.locals.content.getChrome();
+const productCategory = product.product_type || mf("compliance", "product_category");
+const disclaimer =
+  (productCategory && chrome.disclaimers?.[productCategory]) || chrome.disclaimer;
+
+// Full review content (migrated from the store's reviews app). The aggregate
+// (reviewAvg/reviewCount above) comes from metafields; this is the per-review text.
+const reviews = await tot.getReviews(product.handle);
+
+const onSale = isOnSale(product);
+const available = isAvailable(product);
+
+// FoxyCart add-to-cart (Track A). Pre-build each variant's cart payload server-
+// side so the island can render a signed, tamper-proof form. In `signed` mode a
+// missing secret means we render NO cart (never a tamperable form); the
+// `unsigned-demo` mode needs no secret. Drafts still get a cart (preview links).
+let foxyCart:
+  | { action: string; byVariantId: Record<string, VariantCartPayload> }
+  | undefined;
+if (commerce) {
+  const secret = await readCartSecret(commerce);
+  if (commerce.mode !== "signed" || secret) {
+    const entries = await Promise.all(
+      product.variants.map(
+        async (v) =>
+          [
+            v.id,
+            await buildVariantCartPayload(product, v, {
+              mode: commerce.mode,
+              secret,
+            }),
+          ] as const,
+      ),
+    );
+    foxyCart = { action: commerce.cartUrl, byVariantId: Object.fromEntries(entries) };
+  }
+}
+
+const snapshot = {
+  handle: product.handle,
+  title: product.title,
+  price: fromPrice(product),
+  currency: product.price_range.currency,
+  vendor: product.vendor,
+  img: product.images[0]?.url,
+  rehosted: product.images[0]?.rehosted,
+  seed: product.images[0]?.id ?? product.handle,
+};
+
+// Enrich with the real aggregate rating + reviews for rich results (SEO), per the
+// review-markup policy (docs/architecture/review-markup-policy.md).
+const productJsonLd: Record<string, unknown> = {
+  ...productLd(product, tenant, canonicalBase),
+  ...reviewLd(reviewAvg, reviewCount, reviews),
+};
+const jsonLd = [productJsonLd, breadcrumbLd(crumbs, canonicalBase)];
+---
+
+<Layout
+  title={product.seo.title || product.title}
+  description={product.seo.description || truncate(product.description_text, 160)}
+  path={`/products/${product.handle}`}
+  ogType="product"
+  ogImage={ogImage}
+  noindex={isDraft}
+  jsonLd={jsonLd}
+>
+  <div class="container-prose pt-6">
+    <Breadcrumbs crumbs={crumbs} />
+  </div>
+
+  {isDraft && (
+    <div class="container-prose">
+      <p class="mt-4 rounded-[var(--radius-md)] border border-[var(--color-accent)] bg-[color-mix(in_srgb,var(--color-accent)_8%,transparent)] px-4 py-3 text-sm text-[var(--color-text)]">
+        Draft preview — this product isn't published and won't appear in listings or search.
+      </p>
+    </div>
+  )}
+
+  <div class="container-prose grid gap-10 py-8 md:grid-cols-2 lg:gap-16">
+    {/* Gallery (island) */}
+    <div>
+      <ImageGallery
+        client:idle
+        images={product.images}
+        title={product.title}
+        productHandle={product.handle}
+      />
+    </div>
+
+    {/* Buy column */}
+    <div class="md:pt-2">
+      <div class="flex flex-wrap items-center gap-2">
+        {onSale && <Badge variant="sale" label="Sale" />}
+        {!onSale && isNew(product) && <Badge variant="new" label="New" />}
+        {!available && <Badge variant="soldout" label="Sold out" />}
+      </div>
+
+      {product.vendor && (
+        <p class="eyebrow mt-4">{product.vendor}</p>
+      )}
+      <h1 class="display-md mt-1.5">
+        {product.title}
+      </h1>
+
+      {/* Review badge — REAL aggregate (rating + count) from the store's reviews
+          app, mirrored to product metafields. */}
+      {reviewCount > 0 && reviewAvg > 0 && (
+        <div class="mt-3">
+          <ReviewSummary average={reviewAvg} count={reviewCount} href={reviews.length > 0 ? "#reviews" : undefined} />
+        </div>
+      )}
+
+      {shortDescription && (
+        <p class="mt-4 max-w-prose text-[1.02rem] leading-relaxed text-[var(--color-text)]">
+          {shortDescription}
+        </p>
+      )}
+
+      {compliance?.nicotineWarning && (
+        <div class="mt-6">
+          <NicotineWarning variant="block" />
+        </div>
+      )}
+
+      {restrictedStates.length > 0 && (
+        <div class="mt-4 rounded-[var(--radius-md)] border border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-3 text-sm" role="note">
+          <p class="font-display font-medium text-[var(--color-text)]">Where we can ship this</p>
+          <p class="mt-1 text-[var(--color-muted)]">
+            Due to state laws, this product can't ship to: {restrictedStates.join(", ")}.
+          </p>
+        </div>
+      )}
+
+      {/* Variant selector island owns live price/SKU/availability + buy CTA. */}
+      <div class="mt-7">
+        <VariantSelector
+          client:load
+          variants={product.variants}
+          options={product.options}
+          currency={product.price_range.currency}
+          locale={tenant.locale}
+          foxyCart={foxyCart}
+        />
+        <button
+          type="button"
+          class="wishlist-toggle group mt-3 inline-flex w-full items-center justify-center gap-2 rounded-[var(--radius-md)] border border-[var(--color-border)] py-2.5 font-display text-sm font-medium transition-colors hover:border-[var(--color-sale)] hover:text-[var(--color-sale)] aria-pressed:border-[var(--color-sale)] aria-pressed:text-[var(--color-sale)]"
+          aria-pressed="false"
+          aria-label={`Save ${product.title}`}
+          data-wishlist={JSON.stringify(snapshot)}
+        >
+          <svg class="wishlist-heart h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" aria-hidden="true">
+            <path d="M12 21s-7.5-4.6-10-9.2C.4 8.6 2 5 5.5 5 8 5 9.4 6.6 12 9c2.6-2.4 4-4 6.5-4C22 5 23.6 8.6 22 11.8 19.5 16.4 12 21 12 21z" />
+          </svg>
+          <span class="wl-label">Save for later</span>
+        </button>
+      </div>
+
+      {/* Rich description + attribute lines — matches the source store's PDP:
+          the longer description, then plain "Label: value" lines (no spec table). */}
+      <div class="mt-9 border-t border-[var(--color-border)] pt-7">
+        <div class="rte text-[var(--color-text)]" set:html={product.description_html} />
+        {(flavorTags.length > 0 || vgPercentage || bottleType) && (
+          <div class="mt-5 space-y-1.5 text-sm leading-relaxed">
+            {flavorTags.length > 0 && (
+              <p>
+                <span class="text-[var(--color-muted)]">Flavors:</span>{" "}
+                {flavorTags.map((f, i) => (
+                  <>
+                    {i > 0 && <span class="text-[var(--color-border)]"> | </span>}
+                    {f.href ? (
+                      <a href={withBase(basePath, f.href)} class="link-accent">{f.label}</a>
+                    ) : (
+                      <span>{f.label}</span>
+                    )}
+                  </>
+                ))}
+              </p>
+            )}
+            {vgPercentage && (
+              <p><span class="text-[var(--color-muted)]">VG Percentage:</span> {vgPercentage}</p>
+            )}
+            {bottleType && (
+              <p><span class="text-[var(--color-muted)]">Bottle Type:</span> {bottleType}</p>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Safety & legal (scraped disclaimer) + Shipping & returns. The source
+          store shows no attribute/spec table — attributes appear as lines above. */}
+      <div class="mt-8 border-t border-[var(--color-border)]">
+        {disclaimer && (
+          <details class="accordion group">
+            <summary class="accordion__summary">
+              <span>Safety &amp; legal</span>
+              <span class="accordion__chevron" aria-hidden="true">+</span>
+            </summary>
+            <div class="accordion__body rte text-sm leading-relaxed text-[var(--color-muted)]" set:html={disclaimer} />
+          </details>
+        )}
+
+        <details class="accordion group">
+          <summary class="accordion__summary">
+            <span>Shipping &amp; returns</span>
+            <span class="accordion__chevron" aria-hidden="true">+</span>
+          </summary>
+          <div class="accordion__body text-sm leading-relaxed text-[var(--color-text)]">
+            <p>
+              Delivery times, rates, and returns are covered in our policy —
+              including the adult-signature (21+) requirement on every order.
+            </p>
+            <a
+              href={withBase(basePath, "/shipping-returns")}
+              class="link-accent mt-3 inline-block font-medium"
+            >
+              Shipping &amp; returns policy
+            </a>
+          </div>
+        </details>
+      </div>
+    </div>
+  </div>
+
+  {/* Customer reviews — real content migrated from the store's reviews app. */}
+  {reviews.length > 0 && (
+    <Section
+      id="reviews"
+      title="Customer reviews"
+      eyebrow={`${reviewAvg.toFixed(1)} ★ · ${reviewCount || reviews.length} review${(reviewCount || reviews.length) === 1 ? "" : "s"}`}
+    >
+      <ReviewList reviews={reviews} locale={tenant.locale} />
+    </Section>
+  )}
+
+  {/* Related */}
+  {related.length > 0 && (
+    <Section title="You may also like" eyebrow="More from the line" tone="surface">
+      <div class="grid grid-cols-2 gap-5 lg:grid-cols-4">
+        {related.map((p, i) => (
+          <ProductCard product={p} position={i} list="related" />
+        ))}
+      </div>
+    </Section>
+  )}
+
+  {/* Recently viewed (client island; records this product, shows the rest). */}
+  <RecentlyViewed
+    client:idle
+    locale={tenant.locale}
+    current={{
+      handle: product.handle,
+      title: product.title,
+      price: fromPrice(product),
+      currency: product.price_range.currency,
+      vendor: product.vendor,
+      img: product.images[0]?.url,
+      rehosted: product.images[0]?.rehosted,
+      seed: product.images[0]?.id ?? product.handle,
+    }}
+  />
+
+  {/* PDP-view analytics event. Phase 1: dispatched to a window event that the
+      no-op sink (or a Phase 2 real sink) can subscribe to. No-op by default. */}
+  <script type="application/json" id="pdp-meta" set:html={JSON.stringify({ type: "pdp_view", handle: product.handle })}></script>
+  <script is:inline nonce={Astro.locals.cspNonce}>
+    try {
+      const el = document.getElementById("pdp-meta");
+      if (el?.textContent) {
+        window.dispatchEvent(new CustomEvent("tot:analytics", { detail: JSON.parse(el.textContent) }));
+      }
+    } catch {}
+  </script>
+</Layout>

package/apps/storefront/src/pages/robots.txt.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-tenant robots.txt. Allow all, keep crawlers out of the parameterized
+ * /search results, and point at this tenant's sitemap (canonical base is
+ * resolved per-request from the Host).
+ */
+import type { APIContext } from "astro";
+
+export async function GET(context: APIContext): Promise<Response> {
+  const base = context.locals.canonicalBase.replace(/\/$/, "");
+
+  const body = `User-agent: *
+Allow: /
+Disallow: /search
+
+Sitemap: ${base}/sitemap.xml
+`;
+
+  return new Response(body, {
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "public, max-age=3600",
+    },
+  });
+}

package/apps/storefront/src/pages/saved.astro

@@ -0,0 +1,35 @@
+---
+/**
+ * /saved — the wishlist page. Content is client-rendered from localStorage
+ * (SavedList island); noindex since it's per-device and has no stable content.
+ */
+import Layout from "@/layouts/Layout.astro";
+import Breadcrumbs from "@/components/Breadcrumbs.astro";
+import SavedList from "@/components/islands/SavedList.tsx";
+
+const { tenant } = Astro.locals;
+// Commerce-only route: marketing tenants have no saved-items surface.
+if (!Astro.locals.features.savedItems) return new Response(null, { status: 404 });
+const crumbs = [
+  { label: tenant.displayName, href: "/" },
+  { label: "Saved", href: "/saved" },
+];
+---
+
+<Layout
+  title="Saved items"
+  description="Products you've saved for later."
+  path="/saved"
+  noindex
+>
+  <div class="container-prose pt-6">
+    <Breadcrumbs crumbs={crumbs} />
+  </div>
+  <div class="container-prose py-8">
+    <header class="mb-8" data-reveal>
+      <p class="eyebrow eyebrow--tick mb-3">Your list</p>
+      <h1 class="display-xl">Saved</h1>
+    </header>
+    <SavedList client:only="preact" locale={tenant.locale} />
+  </div>
+</Layout>