@tokenoftrust/storefront-runner 3.12.2 → 3.12.4

package/apps/storefront/public/shared/commerce-chrome.css

@@ -175,6 +175,7 @@ body { overflow-x: clip; }
 }
 /* The menu-drawer copy of search (header.mobile.search "menu") shows only at narrow widths. */
 .header-search--menu { display: none; }
+.header-search--phone { display: none; width: 100%; max-width: none; margin: 0 0 10px; }
 .hamburger { display: none; flex-direction: column; gap: 5px; background: none; border: 0; padding: 6px; min-width: 44px; min-height: 44px; align-items: center; justify-content: center; }
 .hamburger span { width: 26px; height: 2px; background: var(--color-text); border-radius: 2px; }
 
@@ -453,10 +454,16 @@ a.article-card__tag:hover { text-decoration: underline; }
 .site-footer[data-variant="light-collapsible"] .footer-disclaimer p { color: var(--color-text); }
 
 /* --- Reveal-on-scroll (raw-chrome markup uses .reveal/.in) ---------------- */
-.reveal { opacity: 0; transform: translateY(18px); transition: opacity .5s ease, transform .5s ease; }
+/* Unmarked .reveal stays visible. Opacity 0 applies only with .is-below,
+   the same below-the-fold mark as [data-reveal], so an in-viewport block
+   is not hidden before a script adds .in. */
+.reveal { opacity: 1; }
+.reveal.is-below { transition: opacity .5s ease, transform .5s ease; }
+.reveal.is-below:not(.in) { opacity: 0; transform: translateY(18px); }
 .reveal.in { opacity: 1; transform: none; }
 @media (prefers-reduced-motion: reduce) {
-  .reveal { opacity: 1; transform: none; transition: none; }
+  .reveal,
+  .reveal.is-below:not(.in) { opacity: 1; transform: none; transition: none; }
 }
 
 /* --- Responsive ----------------------------------------------------------- */
@@ -522,6 +529,8 @@ a.article-card__tag:hover { text-decoration: underline; }
   .site-header[data-variant="compact-centered"] .header-search-trigger,
   .site-header[data-variant="compact-centered"] .header-actions > a[aria-label="Account"],
   .site-header[data-variant="compact-centered"] .member-cue { display: none; }
+  .site-header[data-variant="compact-centered"] .header-search--phone { display: block; }
+  .site-header[data-variant="compact-centered"] .header-search--phone.header-search--labelled { display: flex; }
   .mobile-bottom-nav {
     position: fixed; inset: auto 0 0; z-index: 130; min-height: 62px;
     display: flex; align-items: stretch; justify-content: space-around;

package/apps/storefront/src/components/catalog/storefront/ProductCard.astro

@@ -16,6 +16,7 @@ import PriceDisplay from "@/components/catalog/storefront/commerce/PriceDisplay.
 import RatingStars from "@/components/catalog/storefront/commerce/RatingStars.astro";
 import { withBase } from "@/lib/publication/shared/basePath";
 import { pageUrlForm } from "@/lib/content/seo/urlForm";
+import { buildCardCartForm } from "@/lib/checkout/commerce/cardCartForm";
 
 interface Props {
   product: CatalogProduct;
@@ -29,7 +30,7 @@ interface Props {
 }
 
 const { product, priority = false, rating, reviewCount } = Astro.props;
-const { tenant, basePath, features } = Astro.locals;
+const { tenant, basePath, features, commerce, apiBasePath, browserEnvironment } = Astro.locals;
 const showBadges = features.productBadges;
 
 // A compliance-verified item (age/lab/regulatory) earns a "Compliant" badge —
@@ -86,6 +87,14 @@ const snapshot = {
 };
 
 // Richer payload for the quick-view dialog (no variant picker — that's the PDP).
+const cardCart = await buildCardCartForm({
+  product,
+  tenant,
+  commerce,
+  apiBasePath,
+  environment: browserEnvironment.environment,
+});
+
 const quickview = {
   ...snapshot,
   images: product.images.slice(0, 4).map((im) => ({
@@ -200,6 +209,31 @@ const quickview = {
     </h3>
     <PriceDisplay product={product} locale={locale} class="mt-1.5" />
 
+    {
+      cardCart && (
+        <form
+          action={cardCart.action}
+          method={cardCart.method}
+          target="_top"
+          data-managed-cart
+          data-product-handle={product.handle}
+          data-variant-id={cardCart.variantId}
+          class="relative z-10 mt-3"
+        >
+          {cardCart.hidden.map((field) => (
+            <input type="hidden" name={field.name} value={field.value} />
+          ))}
+          <input type="hidden" name={cardCart.quantityName} value="1" />
+          <button
+            type="submit"
+            class="w-full rounded-full bg-[var(--color-primary)] px-4 py-3 font-display text-sm font-medium text-[var(--color-primary-contrast)]"
+          >
+            Add to cart
+          </button>
+        </form>
+      )
+    }
+
     {rating != null && <RatingStars rating={rating} count={reviewCount} class="mt-1.5" />}
 
     {

package/apps/storefront/src/components/catalog/storefront/commerce/ProductCarousel.astro

@@ -44,6 +44,8 @@ interface Props {
   variant?: "default" | "compact";
   tone?: "bg" | "surface";
   class?: string;
+  /** Stable home-block id forwarded to the section. */
+  blockId?: string;
 }
 
 const {
@@ -57,6 +59,7 @@ const {
   variant = "default",
   tone = "bg",
   class: className,
+  blockId,
 } = Astro.props;
 
 const tot = Astro.locals.tot;
@@ -94,7 +97,7 @@ const lgWidth: Record<NonNullable<Props["columns"]>, string> = {
 const gap = variant === "compact" ? "gap-3" : "gap-5";
 ---
 
-<Section title={title} eyebrow={eyebrow} tone={tone} class={className}>
+<Section title={title} eyebrow={eyebrow} tone={tone} class={className} blockId={blockId}>
   <div class="tot-carousel">
     {
       panels.map((panel, i) => (

package/apps/storefront/src/components/catalog/storefront/commerce/ProductGrid.astro

@@ -31,6 +31,8 @@ interface Props {
   /** Hide the whole section when there are no products (default true). */
   hideWhenEmpty?: boolean;
   class?: string;
+  /** Stable home-block id forwarded to the section. */
+  blockId?: string;
 }
 
 const {
@@ -43,6 +45,7 @@ const {
   tone = "bg",
   hideWhenEmpty = true,
   class: className,
+  blockId,
 } = Astro.props;
 
 const products =
@@ -60,7 +63,7 @@ const hidden = hideWhenEmpty && products.length === 0;
 
 {
   !hidden && (
-    <Section title={title} eyebrow={eyebrow} tone={tone} class={className}>
+    <Section title={title} eyebrow={eyebrow} tone={tone} class={className} blockId={blockId}>
       {products.length > 0 ? (
         <div class:list={["grid gap-5", colClass[columns]]}>
           {products.map((p, i) => (

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

@@ -13,14 +13,17 @@ interface Props {
   id?: string;
   /** Stable `data-widget` name, so the rendered page says which block this is. */
   widget?: string;
+  /** Stable home-block id. Omitted when the section is not a home block. */
+  blockId?: string;
 }
-const { title, eyebrow, tone = "bg", class: className, id, widget } = Astro.props;
+const { title, eyebrow, tone = "bg", class: className, id, widget, blockId } = Astro.props;
 const bg = tone === "surface" ? "bg-[var(--color-surface)]" : "bg-[var(--color-bg)]";
 ---
 
 <section
   id={id}
   data-widget={widget}
+  data-block={blockId}
   class:list={[bg, "py-[clamp(3rem,7vw,6rem)]", className]}
 >
   <div class="container-prose">

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

@@ -337,6 +337,19 @@ const currentPath = Astro.url.pathname;
     </div>
   </div>
 
+  {
+    compact && searchAction && (
+      <div class="border-b border-border bg-surface px-4 py-2 md:hidden" data-header-phone-search>
+        <SearchTypeahead
+          client:idle
+          action={searchAction}
+          placeholder={searchPlaceholder}
+          label={searchLabel}
+        />
+      </div>
+    )
+  }
+
   <!-- 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

package/apps/storefront/src/components/content/storefront/marketing/MarketingBlocks.astro

@@ -6,6 +6,7 @@
  * Reused by the homepage and (future) marketing content pages.
  */
 import type { MarketingBlock } from "@/lib/content/storyblok/content-model";
+import { homeBlockId } from "@/lib/content/shared/homeVisualParity";
 import MarketingHero from "@/components/content/storefront/marketing/MarketingHero.astro";
 import TrustBar from "@/components/content/storefront/marketing/TrustBar.astro";
 import SplitCompare from "@/components/content/storefront/marketing/SplitCompare.astro";
@@ -24,28 +25,69 @@ interface Props {
 const { blocks, basePath } = Astro.props;
 ---
 {
-  blocks.map((block) => {
+  blocks.map((block, index) => {
+    const blockId = homeBlockId(block, index);
     switch (block.component) {
       case "marketing_hero":
-        return <MarketingHero block={block} basePath={basePath} />;
+        return (
+          <div data-block={blockId}>
+            <MarketingHero block={block} basePath={basePath} />
+          </div>
+        );
       case "trust_bar":
-        return <TrustBar block={block} />;
+        return (
+          <div data-block={blockId}>
+            <TrustBar block={block} />
+          </div>
+        );
       case "split_compare":
-        return <SplitCompare block={block} />;
+        return (
+          <div data-block={blockId}>
+            <SplitCompare block={block} />
+          </div>
+        );
       case "steps":
-        return <Steps block={block} />;
+        return (
+          <div data-block={blockId}>
+            <Steps block={block} />
+          </div>
+        );
       case "card_grid":
-        return <CardGrid block={block} basePath={basePath} />;
+        return (
+          <div data-block={blockId}>
+            <CardGrid block={block} basePath={basePath} />
+          </div>
+        );
       case "integrations":
-        return <Integrations block={block} basePath={basePath} />;
+        return (
+          <div data-block={blockId}>
+            <Integrations block={block} basePath={basePath} />
+          </div>
+        );
       case "proof_strip":
-        return <ProofStrip block={block} />;
+        return (
+          <div data-block={blockId}>
+            <ProofStrip block={block} />
+          </div>
+        );
       case "testimonials":
-        return <Testimonials block={block} />;
+        return (
+          <div data-block={blockId}>
+            <Testimonials block={block} />
+          </div>
+        );
       case "faq":
-        return <Faq block={block} />;
+        return (
+          <div data-block={blockId}>
+            <Faq block={block} />
+          </div>
+        );
       case "cta_band":
-        return <CtaBand block={block} basePath={basePath} />;
+        return (
+          <div data-block={blockId}>
+            <CtaBand block={block} basePath={basePath} />
+          </div>
+        );
       default:
         return null;
     }

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

@@ -582,14 +582,26 @@ const footerWidgets = await renderWidgetSlot(
       mountWidgetPostMessageBridge();
     </script>
 
-    {/* Scroll-reveal + analytics pageview hook. ~0.5KB, no framework. */}
+    {/* Scroll-reveal. Initial-viewport blocks stay visible (no .is-below).
+        Only blocks below the fold start hidden, then .is-in shows them. */}
     <script>
-      // Reveal-on-scroll (respects reduced motion via CSS).
+      // Reveal-on-scroll. Reduced motion stays visible via CSS and .is-in.
       const els = document.querySelectorAll("[data-reveal]");
-      if (
-        els.length &&
-        !window.matchMedia("(prefers-reduced-motion: reduce)").matches
-      ) {
+      const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      const fold = window.innerHeight || document.documentElement.clientHeight || 0;
+      const below: Element[] = [];
+      for (const el of els) {
+        const rect = el.getBoundingClientRect();
+        const laidOut = rect.width > 0 && rect.height > 0;
+        const inView = !laidOut || fold <= 0 || (rect.bottom > 0 && rect.top < fold);
+        if (reduce || inView || typeof IntersectionObserver !== "function") {
+          el.classList.add("is-in");
+        } else {
+          el.classList.add("is-below");
+          below.push(el);
+        }
+      }
+      if (below.length) {
         const io = new IntersectionObserver(
           (entries) => {
             for (const e of entries) {
@@ -601,9 +613,7 @@ const footerWidgets = await renderWidgetSlot(
           },
           { rootMargin: "0px 0px -8% 0px", threshold: 0.05 },
         );
-        els.forEach((el) => io.observe(el));
-      } else {
-        els.forEach((el) => el.classList.add("is-in"));
+        for (const el of below) io.observe(el);
       }
     </script>
 

package/apps/storefront/src/lib/checkout/commerce/cardCartForm.ts

@@ -0,0 +1,85 @@
+/**
+ * Add-to-cart form for a catalog card. One default variant — the first
+ * available one — signed the same way the product page signs its handoff.
+ * No form when the product cannot be bought or the cart cannot be signed.
+ */
+import type { CatalogProduct, CatalogVariant, ResolvedManagedCheckout, TenantConfig } from "@tot/public-runtime";
+import {
+  ANONYMOUS_MEMBER,
+  buildMemberSignedCartPayload,
+  commerceTenantId,
+  normalizePurchaseOptions,
+  SAMPLE_CART_HANDOFF_URL,
+  sampleVariantCartPayload,
+  visiblePurchaseOptions,
+  isAutopilotEnabled,
+  workerCartApiPath,
+} from "@tot/public-runtime";
+import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
+import { resolveCartSigning } from "@/lib/checkout/shared/checkoutCommerce";
+
+export interface CardCartForm {
+  action: string;
+  method: "get" | "post";
+  variantId: string;
+  hidden: { name: string; value: string }[];
+  quantityName: string;
+}
+
+/** The card buys the first variant that can ship. Sold out yields none. */
+export function defaultCardVariant(product: CatalogProduct): CatalogVariant | null {
+  return product.variants.find((variant) => variant.inventory.available) ?? null;
+}
+
+export async function buildCardCartForm(input: {
+  product: CatalogProduct;
+  tenant: TenantConfig;
+  commerce: ResolvedManagedCheckout | null | undefined;
+  apiBasePath: string;
+  environment: string;
+}): Promise<CardCartForm | null> {
+  const variant = defaultCardVariant(input.product);
+  if (!variant) return null;
+  const sampleHandoff = isLocalSampleCheckout(input.tenant.tenant_id);
+  if (!sampleHandoff && !input.commerce) return null;
+  const signing = sampleHandoff ? { enabled: true as const, secret: undefined } : await resolveCartSigning(input.commerce!);
+  if (!signing.enabled) return null;
+  try {
+    const autopilotEnabled = isAutopilotEnabled(input.tenant.commerce?.autopilot);
+    const purchaseOption = visiblePurchaseOptions(normalizePurchaseOptions(input.product), { autopilotEnabled })[0];
+    if (!purchaseOption) return null;
+    const payload = sampleHandoff
+      ? sampleVariantCartPayload(input.product.handle, variant.id)
+      : await buildMemberSignedCartPayload(input.product, variant, {
+          mode: input.commerce!.mode,
+          secret: signing.secret,
+          purchaseOption,
+          pricing: { member: ANONYMOUS_MEMBER, program: input.tenant.commerce?.membership },
+          autopilotEnabled,
+          tenantId: commerceTenantId(input.tenant),
+          currency: input.tenant.currency,
+        });
+    const provider = input.tenant.serving?.provider === "s3-overwrite" ? "s3-overwrite" : "worker-r2-pointer";
+    return {
+      action: sampleHandoff
+        ? SAMPLE_CART_HANDOFF_URL
+        : workerCartApiPath({
+            provider,
+            phase: input.environment === "live" ? "publication" : "preview",
+            apiBasePath: input.apiBasePath,
+            endpoint: "/api/commerce/checkout-handoff",
+          }),
+      method: sampleHandoff ? "get" : "post",
+      variantId: variant.id,
+      hidden: payload.hidden,
+      quantityName: payload.quantityName,
+    };
+  } catch (err) {
+    if (!(err instanceof Error) || err.name !== "CartSigningUnavailableError") {
+      console.warn(
+        `[storefront] Invalid checkout purchase options for ${input.product.handle}; cart disabled for this product.`,
+      );
+    }
+    return null;
+  }
+}

package/apps/storefront/src/lib/content/shared/homeVisualParity.ts

@@ -94,6 +94,54 @@ export function promoTilesView(
   };
 }
 
+const BLOCK_ID_MAX = 64;
+
+function blockToken(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, BLOCK_ID_MAX);
+}
+
+/**
+ * Stable `data-block` id. A declared `id` wins. Otherwise the component name
+ * plus the block's index. Never random, and never a tenant id.
+ */
+export function homeBlockId(block: { component: string; id?: string }, index: number): string {
+  const declared = typeof block.id === "string" ? blockToken(block.id) : "";
+  if (declared) return declared;
+  const component = blockToken(block.component) || "block";
+  const position = Number.isInteger(index) && index >= 0 ? index : 0;
+  return `${component}-${position}`.slice(0, BLOCK_ID_MAX);
+}
+
+export interface EditorialBlockView {
+  excerpt?: string;
+  date?: string;
+  cta: { label: string; href: string; variant: "link" | "button" } | null;
+}
+
+function declaredText(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/** Excerpt, date, and CTA. A button variant carries the label with no arrow. */
+export function editorialBlockView(block: EditorialBlock): EditorialBlockView {
+  const label = declaredText(block.ctaLabel);
+  const href = declaredText(block.ctaHref);
+  return {
+    excerpt: declaredText(block.excerpt),
+    date: declaredText(block.date),
+    cta:
+      label && href && isSafeStorefrontHref(href)
+        ? { label, href, variant: block.ctaVariant === "button" ? "button" : "link" }
+        : null,
+  };
+}
+
 /**
  * The editorial block's media column: the block image, else generated art when
  * the block asks for it with `imageSeed`, else none — a text-only block.

package/apps/storefront/src/lib/content/shared/rawChrome.ts

@@ -281,13 +281,14 @@ function renderNavItem(item: ChromeNavItem, index: number, currentPath?: string)
  * The header search form. `inMenu` is the copy placed inside the menu drawer
  * (header.mobile.search "menu"); it carries its own input id so both can exist.
  */
-function renderSearchForm(search: ChromeSearch, inMenu = false): string {
-  const id = inMenu ? "hdr-q-menu" : "hdr-q";
+function renderSearchForm(search: ChromeSearch, placement: "row" | "menu" | "phone" = "row"): string {
+  const id = placement === "menu" ? "hdr-q-menu" : placement === "phone" ? "hdr-q-phone" : "hdr-q";
   const button = search.buttonLabel
     ? `<button type="submit" class="header-search__submit">${esc(search.buttonLabel)}</button>`
     : `<button type="submit" aria-label="Search">${ICON_SEARCH}</button>`;
+  const placementClass = placement === "menu" ? " header-search--menu" : placement === "phone" ? " header-search--phone" : "";
   return (
-    `<form class="header-search${inMenu ? " header-search--menu" : ""}${search.buttonLabel ? " header-search--labelled" : ""}" action="${esc(search.action ?? "/search")}" method="get" role="search">\n` +
+    `<form class="header-search${placementClass}${search.buttonLabel ? " header-search--labelled" : ""}" action="${esc(search.action ?? "/search")}" method="get" role="search">\n` +
     `      <label class="sr-only" for="${id}">${esc(search.label ?? "Search")}</label>\n` +
     `      <input id="${id}" type="search" name="q" placeholder="${esc(search.placeholder ?? "Search")}" autocomplete="off">\n` +
     `      ${button}\n` +
@@ -381,7 +382,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const navItems = header.nav
     .map((item, i) => renderNavItem(item, i, currentPath))
     .join("\n          ");
-  const menuSearch = searchInMenu ? `        ${renderSearchForm(header.search!, true)}\n` : "";
+  const menuSearch = searchInMenu ? `        ${renderSearchForm(header.search!, "menu")}\n` : "";
   const primaryNav =
     `<nav class="primary-nav" id="primaryNav" aria-label="Primary">\n` +
     menuSearch +
@@ -402,6 +403,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
     compact && header.search
       ? `<a class="header-search-trigger" data-header-fixed-action href="${esc(header.search.action ?? "/search")}" aria-label="${esc(header.search.label ?? "Search")}">${ICON_SEARCH}</a>`
       : "";
+  const phoneSearch = compact && header.search ? `  ${renderSearchForm(header.search, "phone")}\n` : "";
   const mobileBottom =
     compact
       ? `<nav class="mobile-bottom-nav" aria-label="Quick links">` +
@@ -426,6 +428,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
     (!minimal && !compact && search ? `    ${search}\n` : "") +
     `    <div class="header-actions">${memberCue}${ctas}${compactSearch}${actionLinks}${account}${cart}${menuLeft ? "" : hamburger}</div>\n` +
     `  </div>\n` +
+    phoneSearch +
     navBar +
     `</header>` +
     mobileBottom

package/apps/storefront/src/lib/content/storyblok/content-model.ts

@@ -14,7 +14,9 @@ import type { Tier } from "@/lib/membership/model";
 import type { TrustStripItem } from "@/lib/content/trustStrip";
 import type { PromoTilePresentation } from "@tot/public-runtime";
 
-export type HomeBlock =
+type BlockIdentity = { id?: string };
+
+export type HomeBlock = (
   | HeroBlock
   | PromoTilesBlock
   | CommerceTrustStripBlock
@@ -23,7 +25,9 @@ export type HomeBlock =
   | MembershipBandBlock
   | EditorialBlock
   | NewsletterBlock
-  | FaqBlock;
+  | FaqBlock
+) &
+  BlockIdentity;
 
 export interface CommerceTrustStripBlock {
   component: "trust_strip";
@@ -139,8 +143,14 @@ export interface EditorialBlock {
   image?: string;
   imageAlt?: string;
   align?: "left" | "right";
+  /** Plain-text dek. Rendered only when declared. */
+  excerpt?: string;
+  /** Plain-text publication date. Rendered only when declared. */
+  date?: string;
   ctaLabel?: string;
   ctaHref?: string;
+  /** `button` is a label with no forced arrow. Absent or `link` keeps the arrow link. */
+  ctaVariant?: "link" | "button";
 }
 
 export interface NewsletterBlock {
@@ -278,7 +288,7 @@ export interface CtaBandBlock {
   ctas?: MarketingCta[];
 }
 
-export type MarketingBlock =
+export type MarketingBlock = (
   | MarketingHeroBlock
   | TrustBarBlock
   | SplitCompareBlock
@@ -288,7 +298,9 @@ export type MarketingBlock =
   | ProofStripBlock
   | TestimonialsBlock
   | FaqBlock
-  | CtaBandBlock;
+  | CtaBandBlock
+) &
+  BlockIdentity;
 
 /** Discriminators that identify a marketing block (vs a commerce HomeBlock). */
 export const MARKETING_COMPONENTS = new Set<MarketingBlock["component"]>([

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

@@ -38,7 +38,9 @@ import {
 import { resolveSectionSource } from "@/lib/content/shared/sections";
 import { featuredProductsPresentationView } from "@/lib/catalog/shared/featuredProductsPresentation";
 import {
+  editorialBlockView,
   editorialMediaView,
+  homeBlockId,
   resolveCommerceStaticBlock,
   type CommerceStaticResolved,
 } from "@/lib/content/shared/homeVisualParity";
@@ -103,11 +105,12 @@ const marketingBlocks: MarketingBlock[] = marketing
 const collections = marketing ? [] : await tot.listCollections();
 
 // --- Resolve each block into a typed, render-ready view-model -----------------
-type Resolved =
+type Resolved = (
   | { kind: "hero"; block: HeroBlock; product: CatalogProduct | null; instanceKey: string }
   | { kind: "collections"; title?: string; cols: CatalogCollection[] }
   | { kind: "products"; title?: string; products: CatalogProduct[]; presentation?: FeaturedProductsBlock["presentation"] }
-  | CommerceStaticResolved;
+  | CommerceStaticResolved
+) & { blockId: string };
 
 async function resolveProducts(
   source: FeaturedProductsBlock["source"],
@@ -122,10 +125,11 @@ async function resolveProducts(
 }
 
 const resolved: Resolved[] = [];
-for (const block of marketing ? [] : home.blocks) {
+for (const [index, block] of (marketing ? [] : home.blocks).entries()) {
+  const blockId = homeBlockId(block, index);
   const staticBlock = resolveCommerceStaticBlock(block);
   if (staticBlock) {
-    resolved.push(staticBlock);
+    resolved.push({ ...staticBlock, blockId });
     continue;
   }
   switch (block.component) {
@@ -136,7 +140,7 @@ for (const block of marketing ? [] : home.blocks) {
         const firstHandle = col?.product_handles[0];
         if (firstHandle) product = await tot.getProductByHandle(firstHandle);
       }
-      resolved.push({ kind: "hero", block, product, instanceKey: `home-${resolved.length}` });
+      resolved.push({ kind: "hero", block, product, instanceKey: `home-${resolved.length}`, blockId });
       break;
     }
     case "featured_collections": {
@@ -146,7 +150,7 @@ for (const block of marketing ? [] : home.blocks) {
       const cols = handles
         .map((h) => collections.find((c) => c.handle === h))
         .filter((c): c is CatalogCollection => !!c);
-      resolved.push({ kind: "collections", title: block.title, cols });
+      resolved.push({ kind: "collections", title: block.title, cols, blockId });
       break;
     }
     case "featured_products": {
@@ -155,7 +159,7 @@ for (const block of marketing ? [] : home.blocks) {
         block.handles,
         block.limit ?? 4,
       );
-      resolved.push({ kind: "products", title: block.title, products, presentation: block.presentation });
+      resolved.push({ kind: "products", title: block.title, products, presentation: block.presentation, blockId });
       break;
     }
   }
@@ -201,17 +205,29 @@ const homeSectionWidgets = marketing
   {
     !marketing && resolved.map((r) => {
       if (r.kind === "hero") {
-        return <Hero block={r.block} featureProduct={r.product} instanceKey={r.instanceKey} />;
+        return (
+          <div data-block={r.blockId}>
+            <Hero block={r.block} featureProduct={r.product} instanceKey={r.instanceKey} />
+          </div>
+        );
       }
       if (r.kind === "promo_tiles") {
-        return <PromoTiles block={r.block} basePath={basePath} tenantId={tenant.tenant_id} />;
+        return (
+          <div data-block={r.blockId}>
+            <PromoTiles block={r.block} basePath={basePath} tenantId={tenant.tenant_id} />
+          </div>
+        );
       }
       if (r.kind === "trust_strip") {
-        return <TrustStrip items={r.block.items} tenantId={tenant.tenant_id} mobile={r.block.mobile} />;
+        return (
+          <div data-block={r.blockId}>
+            <TrustStrip items={r.block.items} tenantId={tenant.tenant_id} mobile={r.block.mobile} />
+          </div>
+        );
       }
       if (r.kind === "collections") {
         return (
-          <Section title={r.title} eyebrow="Collections" tone="bg">
+          <Section title={r.title} eyebrow="Collections" tone="bg" blockId={r.blockId}>
             <div class="grid gap-5 sm:grid-cols-2 lg:grid-cols-3">
               {r.cols.map((c) => (
                 <CollectionCard collection={c} productCount={c.product_handles.length} />
@@ -222,9 +238,9 @@ const homeSectionWidgets = marketing
       }
       if (r.kind === "products") {
         if (featuredProductsPresentationView(r.presentation) === "carousel") {
-          return <ProductCarousel products={r.products} title={r.title} eyebrow="Shop" tone="surface" />;
+          return <ProductCarousel products={r.products} title={r.title} eyebrow="Shop" tone="surface" blockId={r.blockId} />;
         }
-        return <ProductGrid products={r.products} title={r.title} eyebrow="Shop" tone="surface" />;
+        return <ProductGrid products={r.products} title={r.title} eyebrow="Shop" tone="surface" blockId={r.blockId} />;
       }
       if (r.kind === "membership_band") {
         const b = r.block;
@@ -235,7 +251,7 @@ const homeSectionWidgets = marketing
           t.cta ? { ...t, cta: { ...t.cta, href: withBase(basePath, t.cta.href) } } : t,
         );
         return (
-          <section class="bg-[var(--color-surface)] py-[clamp(3rem,7vw,6rem)]">
+          <section class="bg-[var(--color-surface)] py-[clamp(3rem,7vw,6rem)]" data-block={r.blockId}>
             <TierCards tiers={tiers} eyebrow={b.eyebrow} heading={b.title} subhead={b.subhead} />
           </section>
         );
@@ -243,10 +259,11 @@ const homeSectionWidgets = marketing
       if (r.kind === "editorial") {
         const b = r.block;
         const media = editorialMediaView(b, tenant.tenant_id);
+        const fields = editorialBlockView(b);
         const right = b.align !== "left";
         const textOnly = media.kind === "none";
         return (
-          <Section tone="bg">
+          <Section tone="bg" blockId={r.blockId}>
             <div
               class:list={[
                 textOnly ? "max-w-[68ch]" : "grid items-center gap-10 md:grid-cols-2",
@@ -259,15 +276,26 @@ const homeSectionWidgets = marketing
                 <h2 class="display-md">
                   {b.title}
                 </h2>
+                {fields.date && <p class="mt-3 font-mono text-xs uppercase tracking-[0.12em] text-[var(--color-muted)]">{fields.date}</p>}
+                {fields.excerpt && <p class="mt-4 text-[var(--color-text)]">{fields.excerpt}</p>}
                 <div class="rte mt-5 text-[var(--color-muted)]" set:html={b.body_html} />
-                {b.ctaLabel && b.ctaHref && (
+                {fields.cta && (
                   <div class="mt-7">
-                    <a
-                      href={withBase(basePath, b.ctaHref)}
-                      class="link-accent link-accent--cta font-display text-sm font-medium"
-                    >
-                      {b.ctaLabel} →
-                    </a>
+                    {fields.cta.variant === "button" ? (
+                      <a
+                        href={withBase(basePath, fields.cta.href)}
+                        class="inline-flex rounded-full bg-[var(--color-primary)] px-6 py-3 font-display text-sm font-medium text-[var(--color-primary-contrast)]"
+                      >
+                        {fields.cta.label}
+                      </a>
+                    ) : (
+                      <a
+                        href={withBase(basePath, fields.cta.href)}
+                        class="link-accent link-accent--cta font-display text-sm font-medium"
+                      >
+                        {fields.cta.label} →
+                      </a>
+                    )}
                   </div>
                 )}
               </div>
@@ -304,7 +332,7 @@ const homeSectionWidgets = marketing
       if (r.kind === "newsletter") {
         const b = r.block;
         return (
-          <Section tone="surface" id="newsletter">
+          <Section tone="surface" id="newsletter" blockId={r.blockId}>
             <div class="mx-auto max-w-xl text-center" data-reveal>
               <h2 class="display-md">
                 {b.title}
@@ -337,7 +365,11 @@ const homeSectionWidgets = marketing
         );
       }
       if (r.kind === "faq") {
-        return <Faq block={r.block} />;
+        return (
+          <div data-block={r.blockId}>
+            <Faq block={r.block} />
+          </div>
+        );
       }
       return null;
     })

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

@@ -335,18 +335,30 @@
   h2:is(.display-xl, .display-lg, .display-md) { font-size: var(--heading-h2, var(--display-size)); }
   h3:is(.display-xl, .display-lg, .display-md) { font-size: var(--heading-h3, var(--display-size)); }
 
-  /* Tasteful scroll-reveal; opt-in via [data-reveal], JS toggles .is-in. */
+  /* Scroll-reveal only after the script marks a block below the fold.
+     An unmarked [data-reveal] stays at opacity 1, so a block already in the
+     initial viewport is visible with no IntersectionObserver and no tenant flag. */
   [data-reveal] {
+    opacity: 1;
+  }
+  [data-reveal].is-below {
+    transition: opacity 0.6s ease, transform 0.6s cubic-bezier(0.22, 1, 0.36, 1);
+  }
+  [data-reveal].is-below:not(.is-in) {
     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; }
+    [data-reveal],
+    [data-reveal].is-below:not(.is-in) {
+      opacity: 1;
+      transform: none;
+      transition: none;
+    }
   }
 
   /* Island animations (MobileNav drawer slide-in). Globally neutralized by the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.12.2",
+  "version": "3.12.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/scripts/tenant/validate.mjs

@@ -569,6 +569,20 @@ function validateFaq(block, file, at, out) {
   });
 }
 
+function validateEditorial(block, file, at, out) {
+  for (const prop of ["excerpt", "date", "id"]) {
+    if (block[prop] !== undefined && (typeof block[prop] !== "string" || !block[prop].trim())) {
+      out.push(mk(ERROR, "block-prop", file, `${at}.${prop} must be a non-empty string`));
+    }
+  }
+  if (block.ctaVariant !== undefined && block.ctaVariant !== "button" && block.ctaVariant !== "link") {
+    out.push(mk(ERROR, "block-prop", file, `${at}.ctaVariant must be button or link`));
+  }
+  if (typeof block.ctaHref === "string" && !isSafeStorefrontHref(block.ctaHref)) {
+    out.push(mk(ERROR, "navigation-href", file, `${at}.ctaHref must be a same-storefront root-relative path`));
+  }
+}
+
 function validateHomeDoc(doc, file, tenantId) {
   const out = [];
   if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
@@ -620,12 +634,16 @@ function validateHomeDoc(doc, file, tenantId) {
     if (component === "hero" && block.notice !== undefined && (typeof block.notice !== "string" || !block.notice.trim())) {
       out.push(mk(ERROR, "block-prop", file, `${at}.notice must be a non-empty plain-text string`));
     }
+    if (block.id !== undefined && (typeof block.id !== "string" || !block.id.trim())) {
+      out.push(mk(ERROR, "block-prop", file, `${at}.id must be a non-empty string`));
+    }
     if (component === "editorial" && block.image !== undefined) {
       validateVisualAsset(block.image, file, `${at}.image`, out, tenantId);
       if (typeof block.imageAlt !== "string") {
         out.push(mk(ERROR, "block-required", file, `${at}.imageAlt is required when ${at}.image is supplied`));
       }
     }
+    if (component === "editorial") validateEditorial(block, file, at, out);
     if (component === "promo_tiles") validatePromoTiles(block, file, at, out, tenantId);
     if (component === "trust_strip") validateTrustStrip(block, file, at, out, tenantId);
     if (component === "faq") validateFaq(block, file, at, out);