@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "utils": "@/components/ui/utils",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/templates/storefront-shadcn/next.config.js

@@ -0,0 +1,105 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Produce a self-contained build so a channel workspace can run the
+  // storefront with `next start` without a full node_modules tree.
+  output: 'standalone',
+  reactStrictMode: true,
+  // The embedded NestJS backend (src/server/) must be required at runtime
+  // from node_modules, not bundled: Nest's core carries optional
+  // peer-dependency requires (microservices, platform adapters) that the
+  // bundler would otherwise chase into "module not found" errors.
+  // NOTE: externalizing Nest keeps it out of the NORMAL server bundle, but
+  // `src/instrumentation.ts` compiles under its own rules and statically
+  // resolves Nest's lazy `require('class-transformer')` /
+  // `require('class-validator')` (class-serializer + ValidationPipe). Those
+  // optional peers are therefore REAL dependencies in package.json — remove
+  // them and `next build` dies with Module-not-found on the Epinio staging
+  // path (CI run 31764049991, both attempts) while dev mode keeps working.
+  serverExternalPackages: ['@nestjs/core', '@nestjs/common'],
+  // The visual-editor preview runs THIS dev server inside a workspace pod,
+  // embedded cross-origin in the dashboard's editor iframe. Next 16 ENFORCES
+  // `allowedDevOrigins`: it 403s any cross-site request to an internal dev
+  // resource (`/_next`, `/__nextjs`, the HMR websocket) whose Origin/Referer
+  // host is not localhost/127.0.0.1 and not listed here — silently killing the
+  // dashboard iframe's dev channel with no page error. So this list must name
+  // every ORIGIN THAT EMBEDS the editor — i.e. each env's DASHBOARD host — not
+  // just the preview subdomain. GOTCHA: `*` matches exactly ONE label (Next's
+  // `matchWildcardDomain`), so `*.forgecart.dev` does NOT cover the two-label
+  // prod preview host `<code>.preview.forgecart.dev` — it must be listed
+  // explicitly. Dev-only — `next start` (deployed storefronts) ignores it.
+  allowedDevOrigins: [
+    '*.127.0.0.1.nip.io', // LOCAL preview ingress (k3s Traefik :8081) — the host every local pod serves under; without it Next dev 403s the store's own /_next chunks locally (2026-08-13; the wm real-next-app fixture pins the same contract)
+    '*.vm.forgecart.com', // `pnpm vm` Cloudflare-tunnel dashboards
+    '*.dev.forgecart.dev', // dev dashboard + dev preview subdomains
+    '*.forgecart.dev', // single-label deployed preview hosts
+    '*.preview.forgecart.dev', // two-label prod preview host (`*.forgecart.dev` can't match it)
+    '*.preview.test.forgecart.com', // test-env preview subdomains (plain-http zone; .dev is HSTS-preloaded)
+    'dashboard.test.forgecart.com', // test dashboard origin that embeds the editor
+    'dashboard.forgecart.com', // prod dashboard origin that embeds the editor
+  ],
+  // CACHE COMPONENTS: OFF, explicitly — and the explicitness is the point.
+  //
+  // The root layout reads the request locale (`x-forgecart-locale`) to set
+  // `<html lang>`, which is an attribute on the document root and therefore
+  // structurally outside every Suspense boundary. Under Cache Components that
+  // combination is not buildable: `headers()` returns a hanging promise, and a
+  // component aborted with no Suspense frame in its stack raises `blocking-route`
+  // → `StaticGenBailoutError`. The only escape Next offers is a `<Suspense>`
+  // ABOVE `<body>` — in its own words, "an explicit signal from the user that
+  // they acknowledge the empty shell".
+  //
+  // Taking that escape would cost the locale contract entirely. A real 308/404
+  // is assigned only when the render promise REJECTS (`renderToStream`'s catch);
+  // with a boundary above, React resolves as CLIENT_RENDERED instead, so
+  // `notFound()` / `permanentRedirect()` from the layout would emit a 200
+  // carrying a 404 page — a soft-404, indexed rather than dropped, which is the
+  // exact failure this storefront's locale routing exists to prevent.
+  //
+  // Nothing is given up by turning it off: the escape hatch yields an empty
+  // prelude on every route anyway (identical TTFB), and the template uses no
+  // `use cache`. The per-route Suspense boundaries below still stream their
+  // holes — that is core SSR, not a Cache Components feature.
+  //
+  // Written as an explicit `false` rather than omitted: `enforceExperimentalFeatures`
+  // re-enables an UNDEFINED value ("we do respect an explicit value in the user
+  // config"), so on a future 16.x under this package's caret range a deleted key
+  // would silently restore the failure above — in the merchant's scaffold, far
+  // from this repo's CI. An explicit false is immune.
+  cacheComponents: false,
+  experimental: {
+    // Persist Turbopack's dev compile artifacts to `.next` so a pod can serve
+    // a PRE-WARMED `.next` baked at build time instead of paying a cold first
+    // compile. The cache is path-keyed, so it is only valid when warmed at the
+    // SAME absolute path the pod serves from (/workspace) — see the workspace-pod
+    // Dockerfile `storefront-prewarm` stage and the STOREFRONT materialization
+    // initContainer (serve-in-place; never the /opt→/workspace copy). Default-on
+    // in Next 16.1+; set explicitly to document the contract.
+    turbopackFileSystemCacheForDev: true,
+  },
+  // Dev-only `data-fc-source` stamping for the ForgeCart visual editor. The
+  // loader marks host JSX elements with their source file:line:col so the
+  // dashboard can map a sprayed region back to code. It runs under Turbopack
+  // before SWC — with no `as` field, Turbopack chains loader -> built-in SWC,
+  // so the stamped TSX is still compiled normally.
+  //
+  // GLOB GOTCHA (Next 15.5): Turbopack matches a rule key by FILENAME unless it
+  // contains `/` (then by full project-relative path), and it does NOT expand
+  // braces. The earlier `src/**/*.{tsx,jsx}` therefore matched nothing and the
+  // loader silently never ran (`data-fc-source` count: 0). Per-extension
+  // filename globs are what Turbopack honors. The loader self-gates on
+  // NODE_ENV === 'development', so `next build` (webpack, production) is
+  // untouched.
+  turbopack: {
+    rules: {
+      '*.tsx': { loaders: ['@forgecart/designer-runtime/turbo-loader'] },
+      '*.jsx': { loaders: ['@forgecart/designer-runtime/turbo-loader'] },
+    },
+  },
+  images: {
+    // The shop API serves product/asset previews from arbitrary hosts, so
+    // allow any remote image. Tighten this to your asset host in production.
+    remotePatterns: [{ protocol: 'https', hostname: '**' }],
+  },
+};
+
+module.exports = nextConfig;

package/templates/storefront-shadcn/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "storefront",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@forgecart/designer-runtime": "^1.202607161748.0",
+    "@forgecart/sdk": "^1.202609282317.0",
+    "@nestjs/common": "^11.1.14",
+    "@nestjs/core": "^11.1.14",
+    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-slot": "^1.2.4",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "next": "^16.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "server-only": "^0.0.1",
+    "tailwind-merge": "^3.5.0",
+    "uuidv7": "^1.1.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/storefront-shadcn/postcss.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};

package/templates/storefront-shadcn/src/app/%5F%5Ffc/identify/route.ts

@@ -0,0 +1,205 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+import {
+  forwardMarketingIdentifiers,
+  type MarketingIdentifierInput,
+} from '../../../lib/identify-forward';
+import { CLICK_ID_VALUE_MAX_LENGTH } from '../../../lib/marketing-params';
+import { SESSION_COOKIE, establishSessionCookies } from '../../../lib/session-cookies';
+import { getUpstreamConfig, isObviousBot } from '../../../lib/track-forward';
+
+/**
+ * Same-origin marketing-identity relay (#1596).
+ *
+ * A shopper arriving from an ad carries the platform's CLICK ID in the landing
+ * URL and nowhere else — no cookie, no header, and gone the moment they reach a
+ * second page. `lib/marketing-params.ts` reads it on the client, the landing
+ * page POSTs what it found here, and this handler forwards the batch to the
+ * ForgeCart shop API as one `setMarketingIdentifiers` mutation.
+ *
+ * The upstream hop itself (raw HTTP GraphQL with the channel token, the shopper
+ * session as Bearer, and every failure resolving to an empty outcome instead of
+ * a throw) lives in `src/lib/identify-forward.ts`. This route owns everything
+ * request-shaped: parsing untrusted JSON, per-identifier validation, the bot
+ * gate, session threading and cookie persistence.
+ *
+ * Sibling by construction: `../track/route.ts` relays EVENTS over the same
+ * transport, through the same gates, onto the same session cookie PAIR (both
+ * routes write it through `src/lib/session-cookies.ts`) — read the two
+ * together, and change them together. They stay separate routes because a
+ * click ID is not an event: it names the IDENTITY the events belong to, it is
+ * sent once per landing rather than once per batch, and the ad platforms read
+ * it back out of that identity months later when a conversion is reported.
+ *
+ * Inert guard: before `forgecart init` writes `.env` (the image-build prewarm)
+ * there is no shop to talk to, so every submitted key answers `rejected` with
+ * zero upstream calls and the server never crashes.
+ *
+ * Session capture: the shop API surfaces a freshly minted session in the
+ * response `extensions` exactly once. The relay may ESTABLISH the shopper
+ * identity — persisting that mint into BOTH homes of the session pair, the
+ * httpOnly `forgecart-session` cookie and its JS-readable mirror
+ * `forgecart-session-client` (`src/lib/session-cookies.ts`) — when the request
+ * arrived cookie-less, but it never REPLACES an existing cookie. The asymmetry
+ * is the sibling's, for the sibling's reason: an incoming cookie is either a
+ * live session owned by the cart path (clobbering it would vanish a
+ * just-created cart) or a stale one, whose replacement is the cart path's job.
+ *
+ * Writing both homes matters most HERE (#1733). On an ad landing this route
+ * runs before anything else — `ForgeTracker` awaits it before enqueuing the
+ * first page_view — so it is what establishes the session the click ID has just
+ * been attached to. Write the httpOnly half alone and the shopper's own socket
+ * boots unauthenticated, its first cart operation mints a RIVAL session, and
+ * the click ID stays on an identity the settled order never resolves to: the
+ * attribution this route exists to make possible, lost behind a 200. Presence
+ * is still read from the httpOnly copy alone — it is the authoritative one, and
+ * the mirror is client-writable.
+ *
+ * Folder name: `%5F%5Ffc` is URL-encoded `__fc` — the App Router treats
+ * `_`-prefixed folders as PRIVATE (excluded from routing), and the `%5F` escape
+ * is Next's documented way to serve a literal-underscore URL segment. A folder
+ * literally named `__fc` would silently 404.
+ */
+
+/**
+ * The largest identifier list this route will look at.
+ *
+ * A landing page sends at most one entry per click ID it recognises: three
+ * today (`lib/marketing-params.ts`), six registered backend-side. Sixteen is
+ * headroom for every registration that could plausibly be added without
+ * admitting a list no client of ours would ever send — past it the caller is
+ * not our page, and the request is refused whole rather than trimmed, because
+ * silently keeping a prefix of somebody else's batch is the worse answer.
+ */
+const MAX_IDENTIFIERS = 16;
+
+interface IdentifyResponseBody {
+  /** Identifier keys the backend recognised and stored. */
+  accepted: readonly string[];
+  /**
+   * Keys the backend does not know — a NORMAL outcome, never an error. The
+   * upstream partitions the submitted keys against its identifier registry,
+   * stores the ones it knows and reports the rest; nothing was rolled back and
+   * nothing may be retried. A key landing here means only that this storefront
+   * and the backend registry disagree about a spelling, which is a deployment
+   * fact worth being able to read.
+   */
+  rejected: readonly string[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Every answer this route gives is the same pair of key lists. */
+function respond(accepted: readonly string[], rejected: readonly string[]): NextResponse {
+  const body: IdentifyResponseBody = { accepted, rejected };
+  return NextResponse.json(body);
+}
+
+/** Parse the request body into a bounded identifier array, or `null` when malformed. */
+async function parseIdentifiers(request: NextRequest): Promise<unknown[] | null> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(body) || !Array.isArray(body.identifiers)) return null;
+  if (body.identifiers.length === 0 || body.identifiers.length > MAX_IDENTIFIERS) return null;
+  return body.identifiers;
+}
+
+/**
+ * Validate one raw entry into a `MarketingIdentifierInput`, or `null` when it
+ * is not a usable pair. The route rebuilds the pair from untrusted JSON rather
+ * than trusting anything the client typed, so only these two fields cross.
+ *
+ * Both strings share the click-ID bound. The key is looked up in a registry
+ * whose entries are short words, so its cap is a garbage fence rather than a
+ * limit anyone can reach honestly — and a second number for the same purpose
+ * would be one more thing to keep in step, for no gain. The value's bound is
+ * the one that matters and is deliberately generous: Meta's `fbclid` routinely
+ * runs past 128 characters, and a click ID short by one character matches
+ * nothing at the platform that issued it.
+ */
+function validateIdentifier(raw: unknown): MarketingIdentifierInput | null {
+  if (!isPlainObject(raw)) return null;
+  const { key, value } = raw;
+  if (typeof key !== 'string' || key.length === 0 || key.length > CLICK_ID_VALUE_MAX_LENGTH) {
+    return null;
+  }
+  if (typeof value !== 'string' || value.length === 0 || value.length > CLICK_ID_VALUE_MAX_LENGTH) {
+    return null;
+  }
+  return { key, value };
+}
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const submitted = await parseIdentifiers(request);
+  if (!submitted) {
+    return NextResponse.json({ error: 'malformed identifiers' }, { status: 400 });
+  }
+
+  // Validation runs BEFORE the gates here, unlike the event sibling: its reject
+  // shape is positional (one result per submitted item) and can be built from
+  // the raw batch, while this route answers with KEYS — which exist only once
+  // an entry has been proven to carry one.
+  const identifiers: MarketingIdentifierInput[] = [];
+  for (const entry of submitted) {
+    const identifier = validateIdentifier(entry);
+    // A malformed entry is DROPPED, never a 400: one bad pair must not cost a
+    // shopper the attribution the others carry. It is then absent from both
+    // answer lists rather than reported as rejected, so `rejected` keeps its
+    // single meaning — "the upstream does not know this key" — and can never be
+    // read as "you sent junk".
+    if (identifier) identifiers.push(identifier);
+  }
+  // Nothing survived validation: answer the empty verdict without an upstream
+  // call. Forwarding an empty list would mint a session for a request that has
+  // nothing to store against it.
+  if (identifiers.length === 0) return respond([], []);
+
+  const rejectAll = (): NextResponse => respond([], identifiers.map((identifier) => identifier.key));
+
+  // Inert before `forgecart init` writes `.env` (image-prewarm contract).
+  if (!getUpstreamConfig()) return rejectAll();
+
+  const userAgent = request.headers.get('user-agent') ?? '';
+  if (isObviousBot(userAgent)) return rejectAll();
+
+  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;
+
+  // One call for the whole list: the mutation takes an array and the backend
+  // writes it against a single identity, so there is no per-item sequencing to
+  // get wrong here (the event relay loops only because `trackEvent` takes one
+  // event at a time).
+  const outcome = await forwardMarketingIdentifiers(identifiers, {
+    sessionToken: incomingSession,
+    userAgent,
+    forwardedFor,
+    secChUa,
+    secChUaMobile,
+    secChUaPlatform,
+  });
+
+  const response = respond(outcome.accepted, outcome.rejected);
+  // Establish-only persist: write the session ONLY when the request arrived
+  // without one, and then into BOTH of its homes — the httpOnly original the
+  // server reads and the mirror the shopper's own socket boots from. A mint
+  // against an EXISTING cookie is never persisted here — replacing a live
+  // session would vanish the cart it holds, and replacing a stale one belongs
+  // to the cart path (see the module docstring).
+  if (!incomingSession && outcome.sessionToken) {
+    establishSessionCookies(response, outcome.sessionToken);
+  }
+  return response;
+}

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

@@ -0,0 +1,189 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+import { SESSION_COOKIE, establishSessionCookies } from '../../../lib/session-cookies';
+import {
+  forwardTrackEvent,
+  getUpstreamConfig,
+  isObviousBot,
+  type TrackEventInput,
+} from '../../../lib/track-forward';
+
+/**
+ * Same-origin marketing-event relay (design doc S7).
+ *
+ * `ForgeTracker` batches client events (page_view, cta_click, heartbeat, …)
+ * and POSTs them here; this handler forwards each item to the ForgeCart shop
+ * API as a `trackEvent` GraphQL mutation. Unlike `__forge_beacon` this route
+ * is a PRODUCTION feature — tracking runs on deployed storefronts — with one
+ * inert guard: before `forgecart init` writes `.env` (the image-build
+ * prewarm) there is no shop to talk to, so every item answers `accepted:false`
+ * without any upstream call and the server never crashes.
+ *
+ * The upstream hop itself (raw HTTP GraphQL POST with the channel token, the
+ * shopper session as Bearer, UA + `x-forwarded-for` enrichment, and the
+ * why-not-the-SDK rationale) lives in `src/lib/track-forward.ts` — shared with
+ * the F-B `experiment_exposure` emission so both server-side emitters speak
+ * one contract. This route owns everything batch-shaped: parsing, per-item
+ * validation, the bot gate, session threading, and cookie persistence.
+ *
+ * Session capture: the shop API surfaces a freshly minted session in the
+ * response `extensions` (`forgecart-auth-token`) exactly once; the first
+ * touched item captures it and the remaining items of the batch ride it as
+ * Bearer (one identity per batch). The relay may ESTABLISH the shopper
+ * identity — persisting that mint into BOTH homes of the session pair, the
+ * httpOnly `forgecart-session` cookie and its JS-readable mirror
+ * `forgecart-session-client`, through the contract `src/lib/session-cookies.ts`
+ * owns and `src/lib/session-actions.ts#syncShopSession` writes too — but it
+ * never REPLACES an existing cookie. The asymmetry is deliberate: an incoming
+ * cookie that the upstream re-mints against is either a live session owned by
+ * the cart path (clobbering it would vanish a just-created cart — the
+ * first-touch double-mint race) or a stale one, whose replacement is the cart
+ * path's job (the SDK adopts re-mints and `syncShopSession` persists them; the
+ * relay replacing it here would race those writers).
+ *
+ * Both homes or neither (#1733): the browser's shop socket boots its auth from
+ * the MIRROR (`lib/shop-session.ts`), so a session established into the httpOnly
+ * half alone never reaches the client at all — the first cart operation mints a
+ * RIVAL session, `syncShopSession` overwrites the pair with it, and the events
+ * this batch just recorded stay on a session no attribution read resolves to.
+ * Presence, in contrast, is read from the httpOnly copy ALONE: it is the
+ * authoritative one, the mirror is derived from it, and a client-writable cookie
+ * must not be able to decide whether this relay establishes at all.
+ *
+ * Residual window: two writers that BOTH start cookie-less inside the same
+ * in-flight window remain last-writer-wins. With the tracker's deferred first
+ * flush (`ForgeTracker`'s establishment grace) that requires a click-to-
+ * response race under ~100ms — accepted.
+ *
+ * Contract: per-item isolation (one upstream failure never kills the batch),
+ * `accepted:false` is TERMINAL for that item (the tracker never retries), and
+ * obviously non-human user agents short-circuit the whole batch with zero
+ * upstream calls.
+ *
+ * Folder name: `%5F%5Ffc` is URL-encoded `__fc` — the App Router treats
+ * `_`-prefixed folders as PRIVATE (excluded from routing), and the `%5F`
+ * escape is Next's documented way to serve a literal-underscore URL segment.
+ * A folder literally named `__fc` would silently 404.
+ */
+
+/** The tracker flushes at ≤10 events; anything past this is not our client. */
+const MAX_BATCH_SIZE = 50;
+
+/** Canonical textual UUID — the only client `eventId` shape the API accepts. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+interface TrackItemResult {
+  accepted: boolean;
+  eventId: string | null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Parse the request body into a bounded batch array, or `null` when malformed. */
+async function parseBatch(request: NextRequest): Promise<unknown[] | null> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(body) || !Array.isArray(body.events)) return null;
+  if (body.events.length === 0 || body.events.length > MAX_BATCH_SIZE) return null;
+  return body.events;
+}
+
+/** Copy an optional string field from the raw item, rejecting non-string junk. */
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Validate one raw batch item into a `TrackEventInput`, or `null` when the
+ * item is malformed (missing/empty `eventType`, non-UUID `eventId`, non-object
+ * `properties`). Only allowlisted fields cross to the upstream call.
+ */
+function validateItem(raw: unknown): TrackEventInput | null {
+  if (!isPlainObject(raw)) return null;
+  const { eventType, eventId, properties } = raw;
+  if (typeof eventType !== 'string' || eventType.length === 0) return null;
+  if (eventId !== undefined && (typeof eventId !== 'string' || !UUID_PATTERN.test(eventId))) {
+    return null;
+  }
+  if (properties !== undefined && !isPlainObject(properties)) return null;
+
+  const input: TrackEventInput = { eventType };
+  if (typeof eventId === 'string') input.eventId = eventId;
+  const occurredAt = readOptionalString(raw.occurredAt);
+  if (occurredAt) input.occurredAt = occurredAt;
+  if (isPlainObject(properties)) input.properties = properties;
+  const utmSource = readOptionalString(raw.utmSource);
+  if (utmSource) input.utmSource = utmSource;
+  const utmMedium = readOptionalString(raw.utmMedium);
+  if (utmMedium) input.utmMedium = utmMedium;
+  const utmCampaign = readOptionalString(raw.utmCampaign);
+  if (utmCampaign) input.utmCampaign = utmCampaign;
+  const utmTerm = readOptionalString(raw.utmTerm);
+  if (utmTerm) input.utmTerm = utmTerm;
+  const utmContent = readOptionalString(raw.utmContent);
+  if (utmContent) input.utmContent = utmContent;
+  const currencyCode = readOptionalString(raw.currencyCode);
+  if (currencyCode) input.currencyCode = currencyCode;
+  return input;
+}
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const batch = await parseBatch(request);
+  if (!batch) {
+    return NextResponse.json({ error: 'malformed batch' }, { status: 400 });
+  }
+
+  const rejectAll = (): NextResponse =>
+    NextResponse.json({
+      results: batch.map((): TrackItemResult => ({ accepted: false, eventId: null })),
+    });
+
+  // Inert before `forgecart init` writes `.env` (image-prewarm contract).
+  if (!getUpstreamConfig()) return rejectAll();
+
+  const userAgent = request.headers.get('user-agent') ?? '';
+  if (isObviousBot(userAgent)) return rejectAll();
+
+  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[] = [];
+  // Sequential on purpose: the first touched item mints the session and every
+  // later item of the batch must ride it — parallel sends would mint one
+  // identity per item and shatter attribution.
+  for (const raw of batch) {
+    const input = validateItem(raw);
+    if (!input) {
+      results.push({ accepted: false, eventId: null });
+      continue;
+    }
+    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;
+  }
+
+  const response = NextResponse.json({ results });
+  // Establish-only persist: write the session ONLY when the request arrived
+  // without one — and then into BOTH of its homes, which is all
+  // `establishSessionCookies` does. A mint against an EXISTING cookie is never
+  // persisted here — replacing a live session would vanish the cart it holds
+  // (first-touch double-mint race), and replacing a stale one belongs to the
+  // cart path, whose SDK capture + persist owns re-mints (see the module
+  // docstring).
+  if (!incomingSession && sessionToken) establishSessionCookies(response, sessionToken);
+  return response;
+}

package/templates/storefront-shadcn/src/app/%5F%5Fforge_beacon/route.ts

@@ -0,0 +1,87 @@
+/**
+ * DEV-ONLY same-origin error-beacon forwarder.
+ *
+ * The storefront's client beacon (`ForgeErrorBeacon`) POSTs a browser-surfaced
+ * runtime error here — same-origin, so the browser never learns the pod-internal
+ * receiver address. This handler forwards the body SERVER-side to the in-pod
+ * workspace-manager receiver at `http://127.0.0.1:<FORGE_BEACON_PORT>/__forge_beacon`,
+ * which folds it into the supervisor's runtime state so the shop's recovery brain
+ * can originate a fix for a crash the dev-server's stderr scan cannot see.
+ *
+ * Gated entirely on `NODE_ENV === 'development'`: a deployed `next start` storefront
+ * answers 404 here and forwards nothing — the whole beacon path ships only in the
+ * in-pod dev-server. Request access keeps it out of any static prerender so it
+ * behaves identically under `next dev` and a dev build.
+ *
+ * Folder name: `%5F%5Fforge_beacon` is URL-encoded `__forge_beacon`. The App Router
+ * treats a folder whose name starts with `_` as PRIVATE and leaves it out of routing
+ * entirely, so the literal spelling this route shipped with answered the not-found
+ * page to every POST — silently, because the client swallows delivery failures by
+ * design (#2103). The `%5F` escape is Next's documented way to serve a URL segment
+ * that really starts with an underscore, and only the FOLDER may change: the URL is
+ * a contract with the in-pod receiver (`StorefrontBeaconService`'s `BEACON_PATH`),
+ * which this template's server half (`src/instrumentation.ts`) posts to as well.
+ */
+
+const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
+
+/**
+ * The revision the reporting page was SERVED at, lifted out of the forwarded
+ * body for the log line below, or `null` when the report is untagged.
+ *
+ * Reads the body it is ALREADY forwarding verbatim rather than re-deriving
+ * anything: the value was stamped into the document at render time, and this
+ * handler is a forwarder, not a second opinion. The parse is guarded because a
+ * malformed body must not change what this route does — the forward still
+ * happens and the client still gets its 204, exactly as before. `JSON.parse` is
+ * the one throw on this path and it carries no code to classify, which is why it
+ * is caught here and nowhere else (`instrumentation.ts` swallows its own boot
+ * failure in the same template for the same reason); judging the payload stays
+ * the receiver's job.
+ */
+function servedRevision(body: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const value = (parsed as { atRevision?: unknown }).atRevision;
+    if (typeof value !== 'string' || value.length === 0) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+export async function POST(request: Request): Promise<Response> {
+  if (process.env.NODE_ENV !== 'development') {
+    return new Response(null, { status: 404 });
+  }
+
+  const body = await request.text();
+  // Make the dev-server's output ring revision-attributable (#847): this line is
+  // written to the ring the supervisor retains and `TailServerLogs` serves, so a
+  // human or the recovery brain reading the ring can tell WHICH tree a
+  // browser-surfaced crash belongs to instead of guessing from timing.
+  //
+  // It deliberately carries the revision and NOTHING ELSE — no message, no stack,
+  // no route. The ambient scanner matches dev-server output case-insensitively
+  // against RUNTIME_ERROR_PATTERNS ('error:', 'typeerror', 'unhandled', …;
+  // `runtime-error-scanner.types.ts`), so echoing the reported message here would
+  // put the crash text INTO the stream that scanner reads and fold a second,
+  // independent ambient error for the very report already on its way to the
+  // receiver — a self-inflicted double-fire. An untagged report stays silent
+  // rather than logging a placeholder, which keeps today's output byte-identical
+  // for every producer that does not stamp (the server `onRequestError` path
+  // never reaches this route at all — it POSTs the receiver directly).
+  const revision = servedRevision(body);
+  if (revision !== null) console.log(`[forge-beacon browser rev=${revision}]`);
+  // Forward server-side to the loopback receiver. A delivery failure is swallowed —
+  // the beacon is a best-effort backstop, never a hard dependency of the page — but
+  // the client still gets a clean 204 so it never retries against a flapping pod.
+  await fetch(`http://127.0.0.1:${BEACON_PORT}/__forge_beacon`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  }).catch(() => undefined);
+
+  return new Response(null, { status: 204 });
+}