@forgecart/cli 2.202608160103.0 → 2.202608200713.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202608160103.0",
+  "version": "2.202608200713.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/src/app/%5F%5Ffc/track/route.ts

@@ -145,6 +145,12 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
 
   const incomingSession = request.cookies.get(SESSION_COOKIE)?.value ?? null;
   const forwardedFor = request.headers.get('x-forwarded-for');
+  // #1014: mirror the browser's low-entropy Client Hints trio upstream —
+  // Chromium sends them on every request; the shop API's device
+  // identification prefers them over the frozen UA.
+  const secChUa = request.headers.get('sec-ch-ua') ?? undefined;
+  const secChUaMobile = request.headers.get('sec-ch-ua-mobile') ?? undefined;
+  const secChUaPlatform = request.headers.get('sec-ch-ua-platform') ?? undefined;
 
   let sessionToken = incomingSession;
   const results: TrackItemResult[] = [];
@@ -157,7 +163,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       results.push({ accepted: false, eventId: null });
       continue;
     }
-    const outcome = await forwardTrackEvent(input, { sessionToken, userAgent, forwardedFor });
+    const outcome = await forwardTrackEvent(input, { sessionToken, userAgent, forwardedFor, secChUa, secChUaMobile, secChUaPlatform });
     results.push({ accepted: outcome.accepted, eventId: outcome.eventId });
     if (outcome.sessionToken) sessionToken = outcome.sessionToken;
   }

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

@@ -73,6 +73,12 @@ const FLUSH_INTERVAL_MS = 500;
 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`. */
@@ -277,5 +283,90 @@ export function ForgeTracker({ enabled }: { enabled: boolean }) {
     };
   }, [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/lib/track-forward.ts

@@ -74,6 +74,16 @@ export interface ForwardHeaders {
   sessionToken: string | null;
   /** The browser's own User-Agent, forwarded for device enrichment. */
   userAgent: string;
+  /**
+   * The browser's low-entropy Client Hints (`sec-ch-ua`, `sec-ch-ua-mobile`,
+   * `sec-ch-ua-platform`), mirrored verbatim so device identification can
+   * outrank the frozen UA per-field (#1014). Chromium sends the trio on
+   * every request — no handshake, no `Accept-CH` — so this is a pure
+   * pass-through; absent on non-Chromium browsers.
+   */
+  secChUa?: string;
+  secChUaMobile?: string;
+  secChUaPlatform?: string;
   /**
    * Client IP as `x-forwarded-for` (the proxy-standard contract the shop API
    * trusts) — NEVER ForgeCart's edge-secret-gated client-IP override header
@@ -119,7 +129,7 @@ export function isObviousBot(userAgent: string): boolean {
  */
 export async function forwardTrackEvent(
   input: TrackEventInput,
-  { sessionToken, userAgent, forwardedFor }: ForwardHeaders,
+  { sessionToken, userAgent, forwardedFor, secChUa, secChUaMobile, secChUaPlatform }: ForwardHeaders,
 ): Promise<UpstreamOutcome> {
   const upstream = getUpstreamConfig();
   if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
@@ -131,6 +141,9 @@ export async function forwardTrackEvent(
   if (sessionToken) headers['Authorization'] = `Bearer ${sessionToken}`;
   if (userAgent) headers['user-agent'] = userAgent;
   if (forwardedFor) headers['x-forwarded-for'] = forwardedFor;
+  if (secChUa) headers['sec-ch-ua'] = secChUa;
+  if (secChUaMobile) headers['sec-ch-ua-mobile'] = secChUaMobile;
+  if (secChUaPlatform) headers['sec-ch-ua-platform'] = secChUaPlatform;
 
   try {
     const response = await fetch(upstream.shopApiUrl, {