@forgecart/cli 2.202607190047.0 → 2.202607240817.0

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

@@ -0,0 +1,267 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+/**
+ * Storefront event tracker (design doc S7). Renders nothing.
+ *
+ * The single client-side emitter of marketing events. Everything goes through
+ * the same-origin `/__fc/track` relay — NEVER the SDK's WebSocket singleton,
+ * whose connection pins one identity and would mis-attribute every event after
+ * a login. The relay replays the shopper's `forgecart-session` cookie per
+ * request, so attribution follows the identity.
+ *
+ * What it emits:
+ *   - `page_view` on the initial load and on every App-Router route change
+ *     (client-effect emission is the only prefetch-safe choice — `<Link>`
+ *     prefetches run middleware and RSC fetches but no client effects).
+ *     `properties.referrerPath` is the module-tracked previous pathname:
+ *     `document.referrer` is frozen across soft navigations and must not be
+ *     read per-view; only the initial load additionally carries it (origin
+ *     level under the default Referrer-Policy) as `properties.referrer`.
+ *   - `cta_click` from ONE delegated capture-phase click listener for any
+ *     `[data-fc-track]` element — the element stays dumb (a semantic slug in
+ *     `properties.trackId`); what the click MEANS is backend automation
+ *     config, never deployed code.
+ *   - `heartbeat` every {@link HEARTBEAT_MS} while the tab is visible (plus
+ *     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.
+ *
+ * Deliberately NO 30-second same-path dedup (the old `ForgeAnalytics`
+ * behavior): it was live-map-correct but funnel-lossy — A→B→A inside 30s
+ * dropped the return view. The short same-signal suppressors (300ms; also what
+ * keeps StrictMode's double-mount from double-emitting, via module scope) plus
+ * the server-side `eventId` dedupe replace it, so revisits are recorded.
+ *
+ * Two deliberate suppressions:
+ *   - missing config (the pod image pre-renders the template before
+ *     `forgecart init` writes `.env`) → the tracker is inert;
+ *   - framed embeds (`window.parent !== window`) → the visual editor's
+ *     artboard preview emits nothing, so funnels stay production-visitor-only.
+ */
+
+const HEARTBEAT_MS = 60_000;
+/** Minimum spacing between heartbeats (refocus storms, StrictMode remounts). */
+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;
+/** Same-signal suppression window (per click slug; per page_view path). */
+const SUPPRESS_MS = 300;
+const TRACK_ENDPOINT = '/__fc/track';
+
+/** One buffered event — the relay forwards these fields to `trackEvent`. */
+interface TrackedEvent {
+  eventType: string;
+  eventId: string;
+  occurredAt: string;
+  properties?: Record<string, unknown>;
+}
+
+// Module scope on purpose: the buffer, timers and suppressors must survive
+// StrictMode's mount → unmount → mount cycle (a ref would reset) and there is
+// exactly one tracker per page.
+let buffer: TrackedEvent[] = [];
+let flushTimer: number | null = null;
+const lastClickAtBySlug = new Map<string, number>();
+let lastPageView: { path: string; at: number } | null = null;
+let previousPathname: string | null = null;
+let lastHeartbeatAt = 0;
+
+/**
+ * Consent extension point. Tracking currently needs no opt-in, so this is a
+ * no-op returning `true`; the merchant cookie-banner fast-follow implements
+ * the real gate HERE (read the stored consent state) and every emission path
+ * already respects it — nothing enters the buffer without consent.
+ */
+function hasTrackingConsent(): boolean {
+  return true;
+}
+
+/**
+ * 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.
+ */
+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)}`;
+}
+
+/** Stamp and buffer one event; flush on size, else arm the age timer. */
+function enqueue(eventType: string, properties?: Record<string, unknown>): void {
+  if (!hasTrackingConsent()) return;
+  const event: TrackedEvent = {
+    eventType,
+    eventId: mintEventId(),
+    occurredAt: new Date().toISOString(),
+  };
+  if (properties) event.properties = properties;
+  buffer.push(event);
+
+  if (buffer.length >= FLUSH_MAX_EVENTS) {
+    flush();
+    return;
+  }
+  if (flushTimer === null) {
+    flushTimer = window.setTimeout(flush, FLUSH_INTERVAL_MS);
+  }
+}
+
+/** Drain the buffer, returning the batch to send (empties module state). */
+function drain(): TrackedEvent[] {
+  if (flushTimer !== null) {
+    window.clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  const events = buffer;
+  buffer = [];
+  return events;
+}
+
+/** Primary delivery: keepalive fetch, fire-and-forget, failures swallowed. */
+function flush(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ events }),
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+/**
+ * `pagehide` delivery: `sendBeacon` — the only flush that uses it, for its
+ * survive-the-unload queueing guarantee. Falls back to keepalive fetch where
+ * the API is unavailable.
+ */
+function flushOnPagehide(): void {
+  const events = drain();
+  if (events.length === 0) return;
+  const body = JSON.stringify({ events });
+  if (typeof navigator.sendBeacon === 'function') {
+    navigator.sendBeacon(TRACK_ENDPOINT, new Blob([body], { type: 'application/json' }));
+    return;
+  }
+  void fetch(TRACK_ENDPOINT, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+    keepalive: true,
+  }).catch(() => undefined);
+}
+
+export function ForgeTracker({
+  shopApiUrl,
+  channelToken,
+}: {
+  shopApiUrl: string;
+  channelToken: string;
+}) {
+  const pathname = usePathname();
+  const enabled = Boolean(shopApiUrl && channelToken);
+
+  // page_view — initial load + every route change.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+    const now = Date.now();
+    if (lastPageView && lastPageView.path === pathname && now - lastPageView.at < SUPPRESS_MS) {
+      return;
+    }
+    lastPageView = { path: pathname, at: now };
+    const properties: Record<string, unknown> = { path: pathname };
+    if (previousPathname !== null) {
+      properties.referrerPath = previousPathname;
+    } else if (document.referrer) {
+      properties.referrer = document.referrer;
+    }
+    previousPathname = pathname;
+    enqueue('page_view', properties);
+  }, [enabled, pathname]);
+
+  // cta_click — one delegated capture-phase listener — and the pagehide flush.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    const onClick = (event: Event): void => {
+      if (!(event.target instanceof Element)) return;
+      const tracked = event.target.closest('[data-fc-track]');
+      if (!tracked) return;
+      const trackId = tracked.getAttribute('data-fc-track');
+      if (!trackId) return;
+      const now = Date.now();
+      const lastAt = lastClickAtBySlug.get(trackId);
+      if (lastAt !== undefined && now - lastAt < SUPPRESS_MS) return;
+      lastClickAtBySlug.set(trackId, now);
+      enqueue('cta_click', { trackId, path: window.location.pathname });
+    };
+    const onPagehide = (): void => flushOnPagehide();
+
+    // Capture phase so the event is seen even when a handler below stops
+    // propagation (e.g. a framework's synthetic-event stopPropagation).
+    document.addEventListener('click', onClick, true);
+    window.addEventListener('pagehide', onPagehide);
+    return () => {
+      document.removeEventListener('click', onClick, true);
+      window.removeEventListener('pagehide', onPagehide);
+    };
+  }, [enabled]);
+
+  // heartbeat — while visible, plus one on refocus; paused while hidden.
+  useEffect(() => {
+    if (!enabled) return;
+    if (window.parent !== window) return;
+
+    let interval: ReturnType<typeof setInterval> | null = null;
+
+    const beat = (): void => {
+      const now = Date.now();
+      if (now - lastHeartbeatAt < HEARTBEAT_MIN_SPACING_MS) return;
+      lastHeartbeatAt = now;
+      enqueue('heartbeat');
+    };
+    const start = (): void => {
+      if (interval !== null) return;
+      interval = setInterval(beat, HEARTBEAT_MS);
+    };
+    const stop = (): void => {
+      if (interval === null) return;
+      clearInterval(interval);
+      interval = null;
+    };
+    const onVisibility = (): void => {
+      if (document.visibilityState === 'visible') {
+        beat();
+        start();
+      } else {
+        stop();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisibility);
+    if (document.visibilityState === 'visible') start();
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      stop();
+    };
+  }, [enabled]);
+
+  return null;
+}

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

@@ -32,7 +32,7 @@ export function Header() {
           <Link href="/products" className="hover:text-gray-900">
             Products
           </Link>
-          <Link href="/cart" className="relative hover:text-gray-900">
+          <Link href="/cart" data-fc-track="header-cart" className="relative hover:text-gray-900">
             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">

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

@@ -9,6 +9,7 @@ export function ProductCard({ product }: { product: 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"
     >
       <div className="aspect-square overflow-hidden bg-gray-100">

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

@@ -193,6 +193,7 @@ export function ProductPurchase({
         type="button"
         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"
       >
         {pending ? 'Adding…' : added ? 'Added!' : variant ? 'Add to cart' : 'Unavailable'}

package/templates/storefront/src/lib/cart-actions.ts

@@ -63,7 +63,7 @@ async function persistSession(client: ForgeCartShopClient): Promise<void> {
 /**
  * Read the active order (cart). Safe to call from a Server Component.
  *
- * Before `forgecart init` writes `.env.local` (notably the image-build pre-warm,
+ * Before `forgecart init` writes `.env` (notably the image-build pre-warm,
  * which renders `/` with no env), there is no shop to talk to — return an empty
  * cart immediately instead of driving the client into a doomed fetch. The
  * layout renders on every route, so this read must never stall an unconfigured

package/templates/storefront/src/lib/experiments.ts

@@ -0,0 +1,335 @@
+import {
+  deriveExposureEventId,
+  resolveExperimentAssignment,
+  type AssignmentResult,
+  type AssignmentSource,
+  type ExperimentAssignmentConfig,
+} from '@forgecart/sdk';
+import { cookies, headers } from 'next/headers';
+import { after } from 'next/server';
+import { cache } from 'react';
+import { uuidv7 } from 'uuidv7';
+
+import { forwardTrackEvent, getUpstreamConfig, isObviousBot } from './track-forward';
+import type { TrackEventInput, UpstreamConfig } from './track-forward';
+
+/**
+ * Server-side A/B variant resolution (design doc Wave F-B).
+ *
+ * `getVariant(experimentKey)` is the ONE storefront API for experiments:
+ * Server Components call it and branch on the returned `variantKey` (variant
+ * payloads are code branches first, `payload` JSON second). Resolution is
+ * LOCAL — the SDK's deterministic assignment engine over a TTL-cached config
+ * — so variants render with zero flicker and zero added request round-trips.
+ *
+ * How the pieces fit:
+ *  - Config: the public `activeExperiments` shop query, fetched over raw
+ *    HTTP GraphQL with the hand-rolled `forgecart-token` header (the
+ *    `track-forward.ts` pattern — the template's pinned published SDK has no
+ *    plain-HTTP query path) and cached module-scope for
+ *    {@link CONFIG_TTL_MS} keyed by channel token. A fetch failure resolves
+ *    to "no experiments" (every caller renders the default branch) and is
+ *    cached for the same TTL, so a dead backend costs one failed fetch per
+ *    minute — never one per request.
+ *  - Subject: the `forgecart-visitor` cookie (S6). When absent, an id is
+ *    minted IN-REQUEST via a request-scoped `cache()` — never relying on
+ *    middleware→RSC cookie propagation (S6 doc rule; the middleware persists
+ *    the durable cookie, this module only needs a consistent value for the
+ *    current render). Same UUIDv7 value shape as the middleware mint.
+ *  - Forced entry: the `forgecart-exp-force` cookie the middleware merges
+ *    from `?fc-exp=` campaign URLs. The engine honors it only when the
+ *    experiment allows forced entry and the variant exists
+ *    (`assignmentSource: 'forced'`).
+ *  - Exposure: when the engine says `exposed` (hashed or forced), ONE
+ *    `experiment_exposure` marketing event is emitted per request inside
+ *    `next/server` `after()` — after the response, off the critical path —
+ *    through the shared `forwardTrackEvent` (never an HTTP self-call to the
+ *    relay, never the SDK's identity-pinning WebSocket). The event id is the
+ *    SDK's deterministic UUIDv5 over `salt:subjectKey:utcDay`, so re-renders
+ *    and multi-page sessions dedupe server-side to one exposure per subject
+ *    per UTC day.
+ *
+ * `currencyCode` is deliberately ABSENT from the exposure input: §A wants the
+ * session market's currency on exposures, but pre-cart the template server
+ * has no side-effect-free source for it — the shop API surfaces currency only
+ * via `activeOrder` (whose read AUTO-CREATES an order for a session, see
+ * `cart-actions.ts#getCart`) and the geo-seeded market lives in a session
+ * that a first-touch page view does not yet have. Inventing a source here
+ * (e.g. the channel default off a product read) would mislabel the segment;
+ * the field stays unset until the ingest side can stamp the session market
+ * server-side.
+ */
+
+const VISITOR_COOKIE = 'forgecart-visitor';
+const SESSION_COOKIE = 'forgecart-session';
+const FORCED_ENTRY_COOKIE = 'forgecart-exp-force';
+
+/** Delivery-config cache TTL — the design doc's 60s config-plane freshness. */
+const CONFIG_TTL_MS = 60_000;
+
+/** Canonical textual UUID — the only visitor-cookie shape trusted as subject. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Backend slug grammar (`ExperimentService`) — gates keys read from cookies. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * The SDK's own `ShopActiveExperiments` document, inlined — same rationale as
+ * `track-forward.ts`: the generated client is WebSocket-only, so the config
+ * read speaks plain HTTP GraphQL with the identical selection.
+ */
+const ACTIVE_EXPERIMENTS_QUERY = `query ShopActiveExperiments {
+  activeExperiments {
+    experimentKey
+    subjectType
+    version
+    salt
+    lifecycle
+    trafficBps
+    allowForcedEntry
+    variants {
+      key
+      weight
+      payload
+    }
+    winnerVariantKey
+  }
+}`;
+
+/** One variant as the `activeExperiments` shop query delivers it. */
+interface ActiveExperimentVariant {
+  key: string;
+  weight: number;
+  payload: Record<string, unknown> | null;
+}
+
+/** The public delivery projection of one experiment (FB2b contract). */
+interface ActiveExperiment {
+  experimentKey: string;
+  subjectType: 'visitor' | 'customer';
+  version: number;
+  salt: string;
+  lifecycle: 'running' | 'paused' | 'completed';
+  trafficBps: number;
+  allowForcedEntry: boolean;
+  variants: ActiveExperimentVariant[];
+  winnerVariantKey: string | null;
+}
+
+/** What a Server Component branches on. */
+export interface ExperimentVariantResult {
+  /**
+   * The assigned variant key, or `null` when the experiment is unknown /
+   * undelivered / malformed — callers treat `null` as "render the default
+   * branch", which keeps every page correct with zero experiments configured.
+   */
+  variantKey: string | null;
+  /**
+   * How the variant was decided: `'hashed'` (randomized cohort), `'forced'`
+   * (campaign entry — excluded from the randomized comparison), `'lifecycle'`
+   * (paused → control / completed → winner), or `null` (non-participant
+   * control or no experiment).
+   */
+  assignmentSource: AssignmentSource | null;
+  /** The variant's optional delivery payload (design doc Q5), if any. */
+  payload: Record<string, unknown> | null;
+}
+
+interface GraphQLActiveExperimentsResponse {
+  data?: { activeExperiments?: unknown } | null;
+  errors?: unknown[];
+}
+
+/** Module-scope 60s TTL cache — one config fetch per server per minute. */
+let configCache: {
+  channelToken: string;
+  expiresAt: number;
+  load: Promise<ActiveExperiment[]>;
+} | null = null;
+
+async function fetchActiveExperiments(upstream: UpstreamConfig): Promise<ActiveExperiment[]> {
+  try {
+    const response = await fetch(upstream.shopApiUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'forgecart-token': upstream.channelToken,
+      },
+      body: JSON.stringify({ query: ACTIVE_EXPERIMENTS_QUERY }),
+    });
+    if (!response.ok) return [];
+    const payload = (await response.json()) as GraphQLActiveExperimentsResponse;
+    const list = payload.data?.activeExperiments;
+    return Array.isArray(list) ? (list as ActiveExperiment[]) : [];
+  } catch {
+    // Experiments must never break the storefront: no config → every caller
+    // renders its default branch until the next TTL window retries.
+    return [];
+  }
+}
+
+function getActiveExperiments(): Promise<ActiveExperiment[]> {
+  const upstream = getUpstreamConfig();
+  // Inert before `forgecart init` writes `.env` (image-prewarm contract).
+  if (!upstream) return Promise.resolve([]);
+  const now = Date.now();
+  if (
+    configCache &&
+    configCache.channelToken === upstream.channelToken &&
+    now < configCache.expiresAt
+  ) {
+    return configCache.load;
+  }
+  configCache = {
+    channelToken: upstream.channelToken,
+    expiresAt: now + CONFIG_TTL_MS,
+    load: fetchActiveExperiments(upstream),
+  };
+  return configCache.load;
+}
+
+/**
+ * The assignment subject for this request: the S6 visitor cookie when it
+ * rode in, else ONE in-request UUIDv7 shared by every `getVariant` call of
+ * the render (request-scoped `cache()`). A cookie-less first page view thus
+ * gets a consistent assignment within its own render; the middleware's
+ * Set-Cookie makes the durable id authoritative from the next request on.
+ */
+const getRequestVisitorId = cache(async (): Promise<string> => {
+  const store = await cookies();
+  const existing = store.get(VISITOR_COOKIE)?.value;
+  if (existing && UUID_PATTERN.test(existing)) return existing;
+  return uuidv7();
+});
+
+/** The forced-entry map from the middleware-merged cookie, slug-validated. */
+const getForcedVariantMap = cache(async (): Promise<Record<string, string>> => {
+  const store = await cookies();
+  const raw = store.get(FORCED_ENTRY_COOKIE)?.value;
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    // `cookies()` already percent-decodes — `raw` is the JSON text.
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
+  const map: Record<string, string> = {};
+  for (const [experimentKey, variantKey] of Object.entries(parsed)) {
+    if (typeof variantKey !== 'string') continue;
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    map[experimentKey] = variantKey;
+  }
+  return map;
+});
+
+function toAssignmentConfig(experiment: ActiveExperiment): ExperimentAssignmentConfig {
+  return {
+    salt: experiment.salt,
+    lifecycle: experiment.lifecycle,
+    trafficBps: experiment.trafficBps,
+    allowForcedEntry: experiment.allowForcedEntry,
+    variants: experiment.variants.map(({ key, weight }) => ({ key, weight })),
+    winnerVariantKey: experiment.winnerVariantKey,
+  };
+}
+
+/**
+ * Emit the `experiment_exposure` marketing event inside `after()`. Request
+ * data (UA, client IP, session) is captured HERE, during render — `after()`
+ * callbacks run once the response is done and must not touch request APIs.
+ * The response is already sent when a session-less exposure reaches the shop
+ * API, so a token minted for it cannot be persisted — accepted: the relay's
+ * first client batch establishes the durable shopper session.
+ */
+async function scheduleExposure(
+  experiment: ActiveExperiment,
+  result: AssignmentResult,
+  visitorId: string,
+): Promise<void> {
+  const requestHeaders = await headers();
+  const userAgent = requestHeaders.get('user-agent') ?? '';
+  // Same bot policy as the relay: unambiguous crawlers emit nothing.
+  if (isObviousBot(userAgent)) return;
+  const forwardedFor = requestHeaders.get('x-forwarded-for');
+  const store = await cookies();
+  const sessionToken = store.get(SESSION_COOKIE)?.value ?? null;
+
+  const occurredAt = new Date();
+  const input: TrackEventInput = {
+    eventType: 'experiment_exposure',
+    // Deterministic UUIDv5 over salt:subjectKey:utcDay — every re-render of
+    // this subject today resubmits the SAME id and the backend dedupes.
+    eventId: deriveExposureEventId(experiment.salt, visitorId, occurredAt),
+    occurredAt: occurredAt.toISOString(),
+    properties: {
+      experimentKey: experiment.experimentKey,
+      variantKey: result.variantKey,
+      version: experiment.version,
+      subjectType: experiment.subjectType,
+      assignmentSource: result.assignmentSource,
+      visitorId,
+    },
+  };
+
+  after(async () => {
+    await forwardTrackEvent(input, { sessionToken, userAgent, forwardedFor });
+  });
+}
+
+/**
+ * Resolve the variant for one experiment. Request-scoped `cache()` keeps the
+ * whole render consistent — layout and page asking for the same key get one
+ * resolution and at most ONE exposure emission per request.
+ */
+export const getVariant = cache(
+  async (experimentKey: string): Promise<ExperimentVariantResult> => {
+    const inert: ExperimentVariantResult = {
+      variantKey: null,
+      assignmentSource: null,
+      payload: null,
+    };
+    if (!SLUG_REGEX.test(experimentKey)) return inert;
+
+    const experiments = await getActiveExperiments();
+    const experiment = experiments.find((entry) => entry.experimentKey === experimentKey);
+    if (!experiment) return inert;
+
+    if (experiment.subjectType === 'customer') {
+      // The storefront server has no verified customer id (auth lives behind
+      // the shop API session) — a customer-scoped experiment renders as
+      // non-participant control here, with no exposure. Customer-subject
+      // resolution belongs to clients that KNOW the customer id.
+      const control = experiment.variants[0];
+      if (!control) return inert;
+      return { variantKey: control.key, assignmentSource: null, payload: control.payload ?? null };
+    }
+
+    const visitorId = await getRequestVisitorId();
+    const forcedVariantKey = (await getForcedVariantMap())[experimentKey] ?? null;
+
+    let result: AssignmentResult;
+    try {
+      result = resolveExperimentAssignment(toAssignmentConfig(experiment), {
+        subjectKey: visitorId,
+        forcedVariantKey,
+      });
+    } catch {
+      // A malformed delivery (out-of-bounds weight, empty variants) must
+      // never break rendering — the caller falls back to its default branch.
+      return inert;
+    }
+
+    if (result.exposed && result.variantKey !== null) {
+      await scheduleExposure(experiment, result, visitorId);
+    }
+
+    const variant = experiment.variants.find((entry) => entry.key === result.variantKey);
+    return {
+      variantKey: result.variantKey,
+      assignmentSource: result.assignmentSource,
+      payload: variant?.payload ?? null,
+    };
+  },
+);

package/templates/storefront/src/lib/forgecart.ts

@@ -15,7 +15,7 @@ import type {
  *
  * The channel token is sent as the `forgecart-token` header on every request
  * (the SDK adds it from `channelToken`), and the endpoint points at the
- * channel's shop-api. Both values come from the environment (`.env.local`,
+ * channel's shop-api. Both values come from the environment (`.env`,
  * written by `forgecart init`):
  *   - FORGECART_SHOP_API_URL  -> endpoint
  *   - FORGECART_CHANNEL_TOKEN -> channelToken
@@ -42,12 +42,12 @@ let client: ForgeCartShopClient | null = null;
 export function getShopClient(): ForgeCartShopClient {
   if (!SHOP_API_URL) {
     throw new Error(
-      'FORGECART_SHOP_API_URL is not set. Add it to .env.local (forgecart init writes it for you).',
+      'FORGECART_SHOP_API_URL is not set. Add it to .env (forgecart init writes it for you).',
     );
   }
   if (!CHANNEL_TOKEN) {
     throw new Error(
-      'FORGECART_CHANNEL_TOKEN is not set. Add it to .env.local (forgecart init writes it for you).',
+      'FORGECART_CHANNEL_TOKEN is not set. Add it to .env (forgecart init writes it for you).',
     );
   }
   if (!client) {