@forgecart/cli 2.202608121449.0 → 2.202608200713.0

package/templates/storefront/src/components/ForgeTracker.tsx

@@ -3,6 +3,8 @@
 import { usePathname } from 'next/navigation';
 import { useEffect } from 'react';
 
+import { mintUuid } from '../lib/uuid';
+
 /**
  * Storefront event tracker (design doc S7). Renders nothing.
  *
@@ -28,12 +30,14 @@ import { useEffect } from 'react';
  *     one on refocus) — liveness plumbing only, excluded from aggregates.
  *
  * Delivery: events buffer and flush as one batch at {@link FLUSH_MAX_EVENTS}
- * events or after {@link FLUSH_INTERVAL_MS} via `fetch(keepalive)`;
- * `sendBeacon` is used ONLY for the `pagehide` flush (its unload-time queueing
- * guarantee is the one thing keepalive fetch lacks). Every event carries a
- * client-minted `eventId` (`crypto.randomUUID`) — the server dedupes on it, so
- * an accidental double-send is harmless. Delivery is fire-and-forget: failures
- * are swallowed and never retried; analytics must never break the storefront.
+ * events or after an age timer via `fetch(keepalive)` — the FIRST batch waits
+ * {@link ESTABLISHMENT_GRACE_MS}, every later batch {@link FLUSH_INTERVAL_MS}
+ * (see the grace rationale on the constant); `sendBeacon` is used ONLY for the
+ * `pagehide` flush (its unload-time queueing guarantee is the one thing
+ * keepalive fetch lacks). Every event carries a client-minted `eventId`
+ * (`crypto.randomUUID`) — the server dedupes on it, so an accidental
+ * double-send is harmless. Delivery is fire-and-forget: failures are
+ * swallowed and never retried; analytics must never break the storefront.
  *
  * Deliberately NO 30-second same-path dedup (the old `ForgeAnalytics`
  * behavior): it was live-map-correct but funnel-lossy — A→B→A inside 30s
@@ -54,8 +58,27 @@ const HEARTBEAT_MIN_SPACING_MS = 30_000;
 /** Batch flush thresholds: whichever of size / age is hit first sends. */
 const FLUSH_MAX_EVENTS = 10;
 const FLUSH_INTERVAL_MS = 500;
+/**
+ * Age timer for the FIRST batch only. On a cookie-less first touch the relay
+ * and the first cart Server Action race to mint the shopper session, and the
+ * browser keeps whichever `Set-Cookie` lands last — if the tracker's ~500ms
+ * page_view batch wins that race against a fast add-to-cart, the cookie flips
+ * away from the session holding the just-created cart. Holding the initial
+ * flush for this grace lets the cart's cookie land first, so the relay batch
+ * then CARRIES it and rides the cart's session instead of minting a rival
+ * (design doc S7: the first tracked interaction establishes the identity the
+ * cart later reuses — establishment still happens, just not mid-race).
+ * Events are timestamped at enqueue (`occurredAt`), so deferral loses nothing.
+ */
+const ESTABLISHMENT_GRACE_MS = 2_000;
 /** Same-signal suppression window (per click slug; per page_view path). */
 const SUPPRESS_MS = 300;
+/**
+ * Minimum VISIBLE dwell before a route's scroll_depth summary is worth a
+ * row (#1022 phase 2b) — filters bounce-through navigations and StrictMode's
+ * dev-only phantom unmount.
+ */
+const ENGAGEMENT_MIN_DWELL_MS = 250;
 const TRACK_ENDPOINT = '/__fc/track';
 
 /** One buffered event — the relay forwards these fields to `trackEvent`. */
@@ -71,6 +94,8 @@ interface TrackedEvent {
 // exactly one tracker per page.
 let buffer: TrackedEvent[] = [];
 let flushTimer: number | null = null;
+/** True once any batch has gone out — ends the establishment grace. */
+let firstBatchSent = false;
 const lastClickAtBySlug = new Map<string, number>();
 let lastPageView: { path: string; at: number } | null = null;
 let previousPathname: string | null = null;
@@ -87,19 +112,12 @@ function hasTrackingConsent(): boolean {
 }
 
 /**
- * Client-side idempotency key: `crypto.randomUUID` where available; on the one
- * environment it isn't (insecure-context LAN-IP dev hosts — the API is
- * secure-context gated, `getRandomValues` is not) mint the same v4 shape by
- * hand, because a thrown TypeError inside a click listener would violate the
- * "analytics never breaks the storefront" invariant.
+ * Client-side idempotency key via the shared insecure-context-safe minter
+ * (lib/uuid.ts) — a thrown TypeError inside a click listener would violate
+ * the "analytics never breaks the storefront" invariant.
  */
 function mintEventId(): string {
-  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
-  const bytes = crypto.getRandomValues(new Uint8Array(16));
-  bytes[6] = (bytes[6] & 0x0f) | 0x40;
-  bytes[8] = (bytes[8] & 0x3f) | 0x80;
-  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  return mintUuid();
 }
 
 /** Stamp and buffer one event; flush on size, else arm the age timer. */
@@ -118,7 +136,8 @@ function enqueue(eventType: string, properties?: Record<string, unknown>): void
     return;
   }
   if (flushTimer === null) {
-    flushTimer = window.setTimeout(flush, FLUSH_INTERVAL_MS);
+    const delay = firstBatchSent ? FLUSH_INTERVAL_MS : ESTABLISHMENT_GRACE_MS;
+    flushTimer = window.setTimeout(flush, delay);
   }
 }
 
@@ -130,6 +149,9 @@ function drain(): TrackedEvent[] {
   }
   const events = buffer;
   buffer = [];
+  // The grace ends once a batch actually goes out — from then on the age
+  // timer runs at the normal cadence.
+  if (events.length > 0) firstBatchSent = true;
   return events;
 }
 
@@ -166,15 +188,13 @@ function flushOnPagehide(): void {
   }).catch(() => undefined);
 }
 
-export function ForgeTracker({
-  shopApiUrl,
-  channelToken,
-}: {
-  shopApiUrl: string;
-  channelToken: string;
-}) {
+/**
+ * `enabled` is computed SERVER-side (env presence) and passed as a boolean —
+ * the tracker only needs to know whether the relay is configured; the channel
+ * token itself must never serialize into the RSC payload.
+ */
+export function ForgeTracker({ enabled }: { enabled: boolean }) {
   const pathname = usePathname();
-  const enabled = Boolean(shopApiUrl && channelToken);
 
   // page_view — initial load + every route change.
   useEffect(() => {
@@ -263,5 +283,90 @@ export function ForgeTracker({
     };
   }, [enabled]);
 
+  // scroll_depth — ONE engagement summary per route (#1022 phase 2b): the
+  // max scroll depth reached (percent, 0-100) and the VISIBLE dwell time,
+  // emitted when the route unmounts (client-side navigation) or the page
+  // hides. Rides the dormant `scroll_depth` event type already in the
+  // default shop allowlist; the server hoists both properties into the
+  // typed `scrollDepth`/`durationMs` ClickHouse columns (CH 005).
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let maxDepthPct = 0;
+    let visibleMs = 0;
+    let visibleSince: number | null =
+      document.visibilityState === 'visible' ? performance.now() : null;
+    let ticking = false;
+    let emitted = false;
+
+    const measure = (): void => {
+      ticking = false;
+      const doc = document.documentElement;
+      // A page shorter than the viewport is fully seen — 100 by definition;
+      // otherwise percent of total document height brought into view.
+      const pct =
+        doc.scrollHeight <= window.innerHeight
+          ? 100
+          : Math.min(
+              100,
+              Math.round(((window.scrollY + window.innerHeight) / doc.scrollHeight) * 100),
+            );
+      if (pct > maxDepthPct) maxDepthPct = pct;
+    };
+    const onScroll = (): void => {
+      if (ticking) return;
+      ticking = true;
+      requestAnimationFrame(measure);
+    };
+    const onVisibility = (): void => {
+      const now = performance.now();
+      if (document.visibilityState === 'visible') {
+        visibleSince ??= now;
+        return;
+      }
+      if (visibleSince !== null) {
+        visibleMs += now - visibleSince;
+        visibleSince = null;
+      }
+    };
+    const emit = (): void => {
+      if (emitted) return;
+      if (visibleSince !== null) {
+        visibleMs += performance.now() - visibleSince;
+        visibleSince = null;
+      }
+      // Dwell floor: a route that never accumulated meaningful visible time
+      // has no engagement story — this also swallows StrictMode's dev-only
+      // mount/unmount phantom, which would otherwise emit a zero-dwell row.
+      if (visibleMs < ENGAGEMENT_MIN_DWELL_MS) return;
+      emitted = true;
+      enqueue('scroll_depth', {
+        path: window.location.pathname,
+        scrollDepth: maxDepthPct,
+        durationMs: Math.round(visibleMs),
+      });
+    };
+    const onPagehide = (): void => {
+      // Emit BEFORE the flush so the summary rides the pagehide beacon —
+      // flushOnPagehide drains-and-no-ops on empty, so the sibling pagehide
+      // listener's own call stays harmless.
+      emit();
+      flushOnPagehide();
+    };
+
+    measure(); // above-the-fold baseline before any scroll fires
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('pagehide', onPagehide);
+      emit(); // client-side route change: summarize the route being left
+    };
+  }, [enabled, pathname]);
+
   return null;
 }

package/templates/storefront/src/components/Header.tsx

@@ -20,24 +20,22 @@ export function Header() {
   }, []);
 
   return (
-    <header className="border-b border-gray-200 bg-white">
-      <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-4">
-        <Link href="/" className="text-lg font-bold tracking-tight text-gray-900">
+    <header className="sticky top-0 z-30 border-b border-base-300 bg-base-100">
+      <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-3">
+        <Link href="/" className="text-lg font-bold tracking-tight">
           Storefront
         </Link>
-        <nav className="flex items-center gap-6 text-sm font-medium text-gray-600">
-          <Link href="/" className="hover:text-gray-900">
+        <nav aria-label="Store" className="flex items-center gap-1 text-sm font-medium">
+          <Link href="/" className="btn btn-ghost btn-sm">
             Home
           </Link>
-          <Link href="/products" className="hover:text-gray-900">
+          <Link href="/products" className="btn btn-ghost btn-sm">
             Products
           </Link>
-          <Link href="/cart" data-fc-track="header-cart" className="relative hover:text-gray-900">
+          <Link href="/cart" data-fc-track="header-cart" className="btn btn-ghost btn-sm">
             Cart
             {mounted && itemCount > 0 && (
-              <span className="ml-1 inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-gray-900 px-1.5 text-xs font-semibold text-white">
-                {itemCount}
-              </span>
+              <span className="badge badge-primary badge-sm font-semibold">{itemCount}</span>
             )}
           </Link>
         </nav>

package/templates/storefront/src/components/ProductCard.tsx

@@ -1,38 +1,50 @@
 import Link from 'next/link';
 
-import { formatPrice, getStartingPrice, type Product } from '../lib/forgecart';
+import type { Product } from '../lib/forgecart';
+import { formatPrice, getStartingPrice } from '../lib/format';
 
-/** A product tile linking to its detail page. Used by the home and grid pages. */
-export function ProductCard({ product }: { product: Product }) {
+/**
+ * A product tile linking to its detail page — canonical daisyUI card
+ * (figure + card-body + card-title). Used by the home and grid pages;
+ * `emphasis` renders the home grid's large lead tile with a bigger title.
+ */
+export function ProductCard({
+  product,
+  emphasis = false,
+}: {
+  product: Product;
+  emphasis?: boolean;
+}) {
   const startingPrice = getStartingPrice(product);
 
   return (
     <Link
       href={`/products/${product.slug}`}
       data-fc-track="product-card"
-      className="group flex flex-col overflow-hidden rounded-lg border border-gray-200 bg-white transition hover:shadow-md"
+      className="card card-border group h-full bg-base-100 transition-shadow hover:shadow-md"
     >
-      <div className="aspect-square overflow-hidden bg-gray-100">
+      <figure className="aspect-square bg-base-200">
         {product.featuredAsset ? (
           // Plain <img> keeps the template dependency-free of next/image config.
           // eslint-disable-next-line @next/next/no-img-element
           <img
             src={product.featuredAsset.preview}
             alt={product.name}
-            className="h-full w-full object-cover transition group-hover:scale-105"
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
           />
         ) : (
-          <div className="flex h-full w-full items-center justify-center text-sm text-gray-400">
+          <div className="flex h-full w-full items-center justify-center text-sm text-base-content/40">
             No image
           </div>
         )}
-      </div>
-      <div className="flex flex-1 flex-col gap-1 p-4">
-        <h3 className="font-medium text-gray-900">{product.name}</h3>
+      </figure>
+      <div className="card-body gap-1 p-4">
+        <h3 className={`card-title font-medium ${emphasis ? 'text-lg' : 'text-base'}`}>
+          {product.name}
+        </h3>
         {startingPrice !== null && (
-          <p className="text-sm text-gray-600">
-            From {formatPrice(startingPrice)}
-          </p>
+          <p className="text-sm text-base-content/60">From {formatPrice(startingPrice)}</p>
         )}
       </div>
     </Link>

package/templates/storefront/src/components/ProductPurchase.tsx

@@ -3,16 +3,13 @@
 import { useEffect, useMemo, useState } from 'react';
 
 import { useCart } from '../lib/cart-context';
+import type { Product, ProductVariant, SellingPlan, SellingPlanGroup } from '../lib/forgecart';
 import {
   formatPrice,
   getPlanCadenceLabel,
   getPlanPreviewPrice,
   getPlanSavingsLabel,
-  type Product,
-  type ProductVariant,
-  type SellingPlan,
-  type SellingPlanGroup,
-} from '../lib/forgecart';
+} from '../lib/format';
 
 /**
  * Variant picker + purchase-options + add-to-cart for the product detail page.
@@ -127,14 +124,14 @@ export function ProductPurchase({
   return (
     <div className="space-y-4">
       {variant && previewPrice !== null ? (
-        <p className="text-xl font-semibold text-gray-900">{formatPrice(previewPrice)}</p>
+        <p className="text-xl font-semibold text-base-content">{formatPrice(previewPrice)}</p>
       ) : (
-        <p className="text-sm text-gray-500">Select options to see the price.</p>
+        <p className="text-sm text-base-content/60">Select options to see the price.</p>
       )}
 
       {product.optionGroups.map((group) => (
         <div key={group.id}>
-          <h3 className="mb-1 text-sm font-medium text-gray-700">{group.name}</h3>
+          <h3 className="mb-1 text-sm font-medium text-base-content/70">{group.name}</h3>
           <div className="flex flex-wrap gap-2">
             {group.options.map((opt) => {
               const active = selected[group.id] === opt.id;
@@ -145,8 +142,8 @@ export function ProductPurchase({
                   onClick={() => setSelected((s) => ({ ...s, [group.id]: opt.id }))}
                   className={`rounded-md border px-3 py-1.5 text-sm transition ${
                     active
-                      ? 'border-gray-900 bg-gray-900 text-white'
-                      : 'border-gray-300 text-gray-700 hover:border-gray-900'
+                      ? 'border-primary bg-primary text-primary-content'
+                      : 'border-base-300 text-base-content/70 hover:border-primary'
                   }`}
                 >
                   {opt.name}
@@ -159,7 +156,7 @@ export function ProductPurchase({
 
       {variant && hasPurchaseOptions && (
         <div>
-          <h3 className="mb-1 text-sm font-medium text-gray-700">Purchase options</h3>
+          <h3 className="mb-1 text-sm font-medium text-base-content/70">Purchase options</h3>
           <div className="flex flex-col gap-2">
             {oneTimeAllowed && (
               <PurchaseOption
@@ -194,7 +191,7 @@ export function ProductPurchase({
         onClick={onAdd}
         disabled={!variant || pending}
         data-fc-track="add-to-cart"
-        className="rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+        className="btn btn-primary"
       >
         {pending ? 'Adding…' : added ? 'Added!' : variant ? 'Add to cart' : 'Unavailable'}
       </button>
@@ -222,16 +219,14 @@ function PurchaseOption({
       onClick={onSelect}
       aria-pressed={active}
       className={`flex items-center justify-between gap-3 rounded-md border px-3 py-2 text-left text-sm transition ${
-        active
-          ? 'border-gray-900 ring-1 ring-gray-900'
-          : 'border-gray-300 hover:border-gray-900'
+        active ? 'border-primary ring-1 ring-primary' : 'border-base-300 hover:border-primary'
       }`}
     >
       <span className="min-w-0">
-        <span className="block font-medium text-gray-900">{label}</span>
-        {hint && <span className="block text-xs text-gray-500">{hint}</span>}
+        <span className="block font-medium text-base-content">{label}</span>
+        {hint && <span className="block text-xs text-base-content/60">{hint}</span>}
       </span>
-      <span className="shrink-0 font-medium text-gray-900">{priceLabel}</span>
+      <span className="shrink-0 font-medium text-base-content">{priceLabel}</span>
     </button>
   );
 }